From a31ee131494f657cb469e8a0295387cc2266b7e2 Mon Sep 17 00:00:00 2001
From: Ivan Skvortsov <ivanskv2000@gmail.com>
Date: Fri, 15 May 2026 11:38:32 +0200
Subject: [PATCH 1/7] refactor(frontend): introduce useDataTableUrlSync and
 enhance useDataTable for controlled state

---
 .../src/shared/composables/useDataTable.ts    |  36 ++++--
 .../shared/composables/useDataTableUrlSync.ts | 104 ++++++++++++++++++
 2 files changed, 129 insertions(+), 11 deletions(-)
 create mode 100644 frontend/src/shared/composables/useDataTableUrlSync.ts

diff --git a/frontend/src/shared/composables/useDataTable.ts b/frontend/src/shared/composables/useDataTable.ts
index 681ba2d..9bb5107 100644
--- a/frontend/src/shared/composables/useDataTable.ts
+++ b/frontend/src/shared/composables/useDataTable.ts
@@ -1,10 +1,11 @@
-import { ref } from 'vue'
+import { ref, type Ref } from 'vue'
 import type {
   ColumnDef,
   SortingState,
   ColumnFiltersState,
   VisibilityState,
   PaginationState,
+  Updater,
 } from '@tanstack/vue-table'
 import {
   getCoreRowModel,
@@ -17,26 +18,36 @@ import {
 } from '@tanstack/vue-table'
 import { valueUpdater } from '@/shared/utils/general'
 
-type SortingOption = {
-  id: string
-  desc: boolean
-}
-
 type UseDataTableOptions<TData, TValue> = {
   data: () => TData[]
   columns: () => ColumnDef<TData, TValue>[]
-  defaultSorting?: SortingOption[]
+  // Optional controlled state
+  sorting?: Ref<SortingState>
+  columnFilters?: Ref<ColumnFiltersState>
+  onSortingChange?: (updater: Updater<SortingState>) => void
+  onColumnFiltersChange?: (updater: Updater<ColumnFiltersState>) => void
+  // Default values for internal state
+  defaultSorting?: SortingState
   defaultPageSize?: number
 }
 
 export function useDataTable<TData, TValue>({
   data,
   columns,
+  sorting: externalSorting,
+  columnFilters: externalColumnFilters,
+  onSortingChange: externalOnSortingChange,
+  onColumnFiltersChange: externalOnColumnFiltersChange,
   defaultSorting = [],
   defaultPageSize = 10,
 }: UseDataTableOptions<TData, TValue>) {
-  const sorting = ref<SortingState>(defaultSorting ?? [])
-  const columnFilters = ref<ColumnFiltersState>([])
+  // Use external state if provided, otherwise create internal state
+  const internalSorting = ref<SortingState>(defaultSorting)
+  const internalColumnFilters = ref<ColumnFiltersState>([])
+
+  const sorting = externalSorting || internalSorting
+  const columnFilters = externalColumnFilters || internalColumnFilters
+
   const columnVisibility = ref<VisibilityState>({})
   const rowSelection = ref({})
   const pagination = ref<PaginationState>({
@@ -57,8 +68,11 @@ export function useDataTable<TData, TValue>({
     getFilteredRowModel: getFilteredRowModel(),
     getFacetedRowModel: getFacetedRowModel(),
     getFacetedUniqueValues: getFacetedUniqueValues(),
-    onSortingChange: updaterOrValue => valueUpdater(updaterOrValue, sorting),
-    onColumnFiltersChange: updaterOrValue => valueUpdater(updaterOrValue, columnFilters),
+    onSortingChange:
+      externalOnSortingChange || (updaterOrValue => valueUpdater(updaterOrValue, internalSorting)),
+    onColumnFiltersChange:
+      externalOnColumnFiltersChange ||
+      (updaterOrValue => valueUpdater(updaterOrValue, internalColumnFilters)),
     onColumnVisibilityChange: updaterOrValue => valueUpdater(updaterOrValue, columnVisibility),
     onRowSelectionChange: updaterOrValue => valueUpdater(updaterOrValue, rowSelection),
     onPaginationChange: updaterOrValue => valueUpdater(updaterOrValue, pagination),
diff --git a/frontend/src/shared/composables/useDataTableUrlSync.ts b/frontend/src/shared/composables/useDataTableUrlSync.ts
new file mode 100644
index 0000000..288ae0c
--- /dev/null
+++ b/frontend/src/shared/composables/useDataTableUrlSync.ts
@@ -0,0 +1,104 @@
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import type { Updater, SortingState, ColumnFiltersState } from '@tanstack/vue-table'
+
+export interface SyncConfig {
+  columnFilters?: Record<string, { param: string; type?: 'string' | 'array' }> // Table Column ID -> URL Query Param Config
+  sorting?: {
+    sortParam: string
+    orderParam: string
+  }
+}
+
+export function useDataTableUrlSync(config: SyncConfig) {
+  const route = useRoute()
+  const router = useRouter()
+
+  const sorting = computed<SortingState>(() => {
+    if (!config.sorting) return []
+    const sort = route.query[config.sorting.sortParam] as string
+    const order = route.query[config.sorting.orderParam] as string
+    if (sort && order) {
+      return [{ id: sort, desc: order === 'desc' }]
+    }
+    return []
+  })
+
+  const columnFilters = computed<ColumnFiltersState>(() => {
+    if (!config.columnFilters) return []
+    return Object.entries(config.columnFilters)
+      .map(([columnId, filterConfig]) => {
+        const value = route.query[filterConfig.param]
+        if (value === undefined || value === null || value === '') return null
+
+        let filterValue: unknown = value
+        if (filterConfig.type === 'array') {
+          filterValue = String(value).split(',').filter(Boolean)
+        }
+
+        return {
+          id: columnId,
+          value: filterValue,
+        }
+      })
+      .filter((filter): filter is { id: string; value: unknown } => filter !== null)
+  })
+
+  const onSortingChange = (updaterOrValue: Updater<SortingState>) => {
+    const newSorting =
+      typeof updaterOrValue === 'function' ? updaterOrValue(sorting.value) : updaterOrValue
+
+    const query = { ...route.query }
+    if (config.sorting) {
+      if (newSorting.length > 0) {
+        query[config.sorting.sortParam] = newSorting[0].id
+        query[config.sorting.orderParam] = newSorting[0].desc ? 'desc' : 'asc'
+      } else {
+        delete query[config.sorting.sortParam]
+        delete query[config.sorting.orderParam]
+      }
+    }
+    router.replace({ query })
+  }
+
+  const onColumnFiltersChange = (updaterOrValue: Updater<ColumnFiltersState>) => {
+    const newFilters =
+      typeof updaterOrValue === 'function' ? updaterOrValue(columnFilters.value) : updaterOrValue
+
+    const query = { ...route.query }
+    if (config.columnFilters) {
+      Object.values(config.columnFilters).forEach(filterConfig => {
+        delete query[filterConfig.param]
+      })
+      newFilters.forEach(filter => {
+        const filterConfig = config.columnFilters![filter.id]
+        if (
+          filterConfig &&
+          filter.value !== undefined &&
+          filter.value !== null &&
+          filter.value !== ''
+        ) {
+          if (Array.isArray(filter.value)) {
+            if (filter.value.length > 0) {
+              query[filterConfig.param] = filter.value.join(',')
+            }
+          } else {
+            query[filterConfig.param] = String(filter.value)
+          }
+        }
+      })
+    }
+    router.replace({ query })
+  }
+
+  return {
+    state: {
+      sorting,
+      columnFilters,
+    },
+    updaters: {
+      onSortingChange,
+      onColumnFiltersChange,
+    },
+  }
+}

From 3dc94aad9c7c33c210acbbb4dbc732f6ceda0616 Mon Sep 17 00:00:00 2001
From: Ivan Skvortsov <ivanskv2000@gmail.com>
Date: Fri, 15 May 2026 11:38:38 +0200
Subject: [PATCH 2/7] refactor(frontend): migrate Tags module to new URL
 synchronization

---
 .../modules/tags/components/TagsDataGrid.vue  | 33 ++++++++++++++++---
 frontend/src/modules/tags/pages/TagsPage.vue  | 20 ++++++++---
 2 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/frontend/src/modules/tags/components/TagsDataGrid.vue b/frontend/src/modules/tags/components/TagsDataGrid.vue
index 4ee1705..abd65fd 100644
--- a/frontend/src/modules/tags/components/TagsDataGrid.vue
+++ b/frontend/src/modules/tags/components/TagsDataGrid.vue
@@ -1,25 +1,49 @@
 <script setup lang="ts">
+import { ref, watch } from 'vue'
 import TagItem from './TagItem.vue'
 import type { Tag } from '@/modules/tags/types'
-import type { UrlFiltersReturn, TagsUrlFilters } from '@/shared/types/urlFilters'
 import { Input } from '@/shared/ui/input'
 import { Button } from '@/shared/ui/button'
 import { Icon } from '@iconify/vue'
 import ItemSkeleton from '@/shared/components/skeletons/ItemSkeleton.vue'
 import { RouterLink } from 'vue-router'
+import { useDebounceFn } from '@vueuse/core'
+
 interface TagsDataGridProps {
   filteredData: Tag[]
   isLoading: boolean
-  urlFilters: UrlFiltersReturn<TagsUrlFilters>
+  searchValue: string
   onEdit: (tag: Tag) => void
   onDelete: (tag: Tag) => void
 }
 
 const props = defineProps<TagsDataGridProps>()
+const emit = defineEmits<{
+  'update:searchValue': [value: string]
+}>()
+
+const localSearchValue = ref(props.searchValue)
+
+const debouncedEmit = useDebounceFn((value: string) => {
+  emit('update:searchValue', value)
+}, 300)
+
+watch(localSearchValue, newValue => {
+  debouncedEmit(newValue)
+})
+
+watch(
+  () => props.searchValue,
+  newValue => {
+    if (newValue !== localSearchValue.value) {
+      localSearchValue.value = newValue
+    }
+  }
+)
 
 const handleSearchKeydown = (event: KeyboardEvent) => {
   if (event.key === 'Escape') {
-    props.urlFilters.clearFilters()
+    localSearchValue.value = ''
   }
 }
 </script>
@@ -30,8 +54,7 @@ const handleSearchKeydown = (event: KeyboardEvent) => {
     <div class="mb-6 flex flex-wrap items-center justify-between gap-4">
       <div class="flex-1">
         <Input
-          :model-value="urlFilters.filters.search"
-          @update:model-value="(value: string | number) => urlFilters.updateSearch?.(String(value))"
+          v-model="localSearchValue"
           placeholder="Search tags..."
           class="max-w-xs"
           @keydown="handleSearchKeydown"
diff --git a/frontend/src/modules/tags/pages/TagsPage.vue b/frontend/src/modules/tags/pages/TagsPage.vue
index d608620..2eb1b5f 100644
--- a/frontend/src/modules/tags/pages/TagsPage.vue
+++ b/frontend/src/modules/tags/pages/TagsPage.vue
@@ -7,7 +7,7 @@ import { ref, defineAsyncComponent, computed } from 'vue'
 import type { TagFormValues } from '@/modules/tags/validation/tagSchema'
 import Header from '@/shared/components/layout/PageHeader.vue'
 import { useEnhancedToast } from '@/shared/composables/useEnhancedToast'
-import { useUrlFilters, tagsFiltersConfig } from '@/shared/composables/useUrlFilters'
+import { useDataTableUrlSync } from '@/shared/composables/useDataTableUrlSync'
 import { filterTags } from '@/shared/utils/tableFilters'
 
 const DeleteModal = defineAsyncComponent(() => import('@/shared/components/modals/DeleteModal.vue'))
@@ -24,7 +24,18 @@ const editedTag = ref<Tag | null>(null)
 const showEditModal = ref(false)
 const showDeleteModal = ref(false)
 
-const urlFilters = useUrlFilters(tagsFiltersConfig)
+const { state, updaters } = useDataTableUrlSync({
+  columnFilters: { search: { param: 'search' } },
+})
+
+const searchValue = computed(() => {
+  const filter = state.columnFilters.value.find(f => f.id === 'search')
+  return (filter?.value as string) || ''
+})
+
+const handleSearchUpdate = (value: string) => {
+  updaters.onColumnFiltersChange([{ id: 'search', value }])
+}
 
 const { data: tags, isLoading } = useQuery({
   queryKey: ['tags'],
@@ -70,7 +81,7 @@ const selectDeleteTag = (tag: Tag) => {
 }
 
 const filteredTags = computed(() => {
-  return filterTags(tags.value ?? [], urlFilters.filters.search)
+  return filterTags(tags.value ?? [], searchValue.value)
 })
 </script>
 
@@ -81,7 +92,8 @@ const filteredTags = computed(() => {
     <TagsDataGrid
       :filtered-data="filteredTags"
       :isLoading="isLoading"
-      :url-filters="urlFilters"
+      :search-value="searchValue"
+      @update:search-value="handleSearchUpdate"
       :onEdit="selectEditTag"
       :onDelete="selectDeleteTag"
     />

From 8f720dbe279c191c8a5a9643e9d0c265c289cc2d Mon Sep 17 00:00:00 2001
From: Ivan Skvortsov <ivanskv2000@gmail.com>
Date: Fri, 15 May 2026 11:38:42 +0200
Subject: [PATCH 3/7] refactor(frontend): migrate Events module to new URL
 synchronization

---
 .../events/components/EventsDataTable.vue     | 23 +++++++++----------
 .../src/modules/events/pages/EventsPage.vue   | 15 +++++++++---
 2 files changed, 23 insertions(+), 15 deletions(-)

diff --git a/frontend/src/modules/events/components/EventsDataTable.vue b/frontend/src/modules/events/components/EventsDataTable.vue
index 60df1f7..2122283 100644
--- a/frontend/src/modules/events/components/EventsDataTable.vue
+++ b/frontend/src/modules/events/components/EventsDataTable.vue
@@ -6,11 +6,11 @@ import { Button } from '@/shared/ui/button'
 import DataTablePagination from '@/shared/components/data/DataTablePagination.vue'
 import DataTable from '@/shared/components/data/DataTable.vue'
 import DataTableLayout from '@/shared/components/data/DataTableLayout.vue'
-import { useDataTableWithUrlQuery } from '@/shared/composables/useDataTableWithUrlQuery'
+import { useDataTable } from '@/shared/composables/useDataTable'
 import DataTableSkeleton from '@/shared/components/skeletons/DataTableSkeleton.vue'
 import DataTableSingleSelectFilter from '@/shared/components/data/DataTableSingleSelectFilter.vue'
 import type { Tag } from '@/modules/tags/types'
-import type { UrlFiltersReturn, EventsUrlFilters } from '@/shared/types/urlFilters'
+import type { useDataTableUrlSync } from '@/shared/composables/useDataTableUrlSync'
 
 const props = defineProps<{
   columns: ColumnDef<TData, TValue>[]
@@ -18,18 +18,17 @@ const props = defineProps<{
   tags: Tag[]
   isLoading: boolean
   isLoadingTags: boolean
-  urlFilters: UrlFiltersReturn<EventsUrlFilters>
+  urlSync: ReturnType<typeof useDataTableUrlSync>
 }>()
 
-const { table } = useDataTableWithUrlQuery(
-  {
-    data: () => props.data,
-    columns: () => props.columns,
-    defaultSorting: [{ id: 'id', desc: true }],
-  },
-  props.urlFilters,
-  'events'
-)
+const { table } = useDataTable({
+  data: () => props.data,
+  columns: () => props.columns,
+  sorting: props.urlSync.state.sorting,
+  columnFilters: props.urlSync.state.columnFilters,
+  onSortingChange: props.urlSync.updaters.onSortingChange,
+  onColumnFiltersChange: props.urlSync.updaters.onColumnFiltersChange,
+})
 </script>
 
 <template>
diff --git a/frontend/src/modules/events/pages/EventsPage.vue b/frontend/src/modules/events/pages/EventsPage.vue
index a7c0ef1..b0aac25 100644
--- a/frontend/src/modules/events/pages/EventsPage.vue
+++ b/frontend/src/modules/events/pages/EventsPage.vue
@@ -9,7 +9,7 @@ import Header from '@/shared/components/layout/PageHeader.vue'
 import { getEventColumns } from '@/modules/events/components/eventColumns'
 import { useEnhancedToast } from '@/shared/composables/useEnhancedToast'
 import type { EventFormValues } from '@/modules/events/validation/eventSchema'
-import { useUrlFilters, eventsFiltersConfig } from '@/shared/composables/useUrlFilters'
+import { useDataTableUrlSync } from '@/shared/composables/useDataTableUrlSync'
 
 const DeleteModal = defineAsyncComponent(() => import('@/shared/components/modals/DeleteModal.vue'))
 const EventEditModal = defineAsyncComponent(
@@ -25,7 +25,16 @@ const editedEvent = ref<Event | null>(null)
 const showEditModal = ref(false)
 const showDeleteModal = ref(false)
 
-const urlFilters = useUrlFilters(eventsFiltersConfig)
+const urlSync = useDataTableUrlSync({
+  columnFilters: {
+    name: { param: 'search' },
+    tags: { param: 'tag' },
+  },
+  sorting: {
+    sortParam: 'sort',
+    orderParam: 'order',
+  },
+})
 
 const { data: tags, isLoading: isLoadingTags } = useQuery({
   queryKey: ['tags'],
@@ -90,7 +99,7 @@ const columns = getEventColumns(selectEditEvent, selectDeleteEvent)
         :tags="tags ?? []"
         :isLoading="isLoading"
         :isLoadingTags="isLoadingTags"
-        :url-filters="urlFilters"
+        :url-sync="urlSync"
       />
     </div>
 

From 432d31375ff7b91232a64db5387fefe43ccf4cb1 Mon Sep 17 00:00:00 2001
From: Ivan Skvortsov <ivanskv2000@gmail.com>
Date: Fri, 15 May 2026 11:38:46 +0200
Subject: [PATCH 4/7] refactor(frontend): migrate Fields module to new URL
 synchronization

---
 .../fields/components/FieldsDataTable.vue     | 23 +++++++++----------
 .../src/modules/fields/pages/FieldsPage.vue   | 15 +++++++++---
 2 files changed, 23 insertions(+), 15 deletions(-)

diff --git a/frontend/src/modules/fields/components/FieldsDataTable.vue b/frontend/src/modules/fields/components/FieldsDataTable.vue
index c21ac93..234aa21 100644
--- a/frontend/src/modules/fields/components/FieldsDataTable.vue
+++ b/frontend/src/modules/fields/components/FieldsDataTable.vue
@@ -9,25 +9,24 @@ import DataTable from '@/shared/components/data/DataTable.vue'
 import DataTableLayout from '@/shared/components/data/DataTableLayout.vue'
 import DataTableSkeleton from '@/shared/components/skeletons/DataTableSkeleton.vue'
 import DataTableMultiSelectFilter from '@/shared/components/data/DataTableMultiSelectFilter.vue'
-import type { UrlFiltersReturn, FieldsUrlFilters } from '@/shared/types/urlFilters'
-import { useDataTableWithUrlQuery } from '@/shared/composables/useDataTableWithUrlQuery'
+import { useDataTable } from '@/shared/composables/useDataTable'
+import type { useDataTableUrlSync } from '@/shared/composables/useDataTableUrlSync'
 
 const props = defineProps<{
   columns: ColumnDef<TData, TValue>[]
   data: TData[]
   isLoading: boolean
-  urlFilters: UrlFiltersReturn<FieldsUrlFilters>
+  urlSync: ReturnType<typeof useDataTableUrlSync>
 }>()
 
-const { table } = useDataTableWithUrlQuery(
-  {
-    data: () => props.data,
-    columns: () => props.columns,
-    defaultSorting: [{ id: 'id', desc: true }],
-  },
-  props.urlFilters,
-  'fields'
-)
+const { table } = useDataTable({
+  data: () => props.data,
+  columns: () => props.columns,
+  sorting: props.urlSync.state.sorting,
+  columnFilters: props.urlSync.state.columnFilters,
+  onSortingChange: props.urlSync.updaters.onSortingChange,
+  onColumnFiltersChange: props.urlSync.updaters.onColumnFiltersChange,
+})
 
 const fieldTypes = Object.values(FieldType)
 </script>
diff --git a/frontend/src/modules/fields/pages/FieldsPage.vue b/frontend/src/modules/fields/pages/FieldsPage.vue
index 5a7a8f8..c0938dd 100644
--- a/frontend/src/modules/fields/pages/FieldsPage.vue
+++ b/frontend/src/modules/fields/pages/FieldsPage.vue
@@ -8,7 +8,7 @@ import Header from '@/shared/components/layout/PageHeader.vue'
 import { getFieldColumns } from '@/modules/fields/components/fieldColumns'
 import { useEnhancedToast } from '@/shared/composables/useEnhancedToast'
 import type { FieldFormValues } from '@/modules/fields/validation/fieldSchema'
-import { useUrlFilters, fieldsFiltersConfig } from '@/shared/composables/useUrlFilters'
+import { useDataTableUrlSync } from '@/shared/composables/useDataTableUrlSync'
 
 const DeleteModal = defineAsyncComponent(() => import('@/shared/components/modals/DeleteModal.vue'))
 const FieldEditModal = defineAsyncComponent(
@@ -24,7 +24,16 @@ const editedField = ref<Field | null>(null)
 const showEditModal = ref(false)
 const showDeleteModal = ref(false)
 
-const urlFilters = useUrlFilters(fieldsFiltersConfig)
+const urlSync = useDataTableUrlSync({
+  columnFilters: {
+    name: { param: 'search' },
+    field_type: { param: 'type', type: 'array' },
+  },
+  sorting: {
+    sortParam: 'sort',
+    orderParam: 'order',
+  },
+})
 
 const { data: fields, isLoading } = useQuery({
   queryKey: ['fields'],
@@ -81,7 +90,7 @@ const columns = getFieldColumns(selectEditField, selectDeleteField)
         :columns="columns"
         :data="fields ?? []"
         :isLoading="isLoading"
-        :url-filters="urlFilters"
+        :url-sync="urlSync"
       />
     </div>
 

From e40ac5e6042ab254104bbc208f68a29cb558ad2e Mon Sep 17 00:00:00 2001
From: Ivan Skvortsov <ivanskv2000@gmail.com>
Date: Fri, 15 May 2026 11:39:00 +0200
Subject: [PATCH 5/7] refactor(frontend): remove legacy URL synchronization
 logic

---
 .../shared/composables/useDataTableSync.ts    | 186 ---------------
 .../composables/useDataTableWithUrlQuery.ts   |  41 ----
 .../src/shared/composables/useUrlFilters.ts   | 225 ------------------
 frontend/src/shared/types/urlFilters.ts       |  47 ----
 4 files changed, 499 deletions(-)
 delete mode 100644 frontend/src/shared/composables/useDataTableSync.ts
 delete mode 100644 frontend/src/shared/composables/useDataTableWithUrlQuery.ts
 delete mode 100644 frontend/src/shared/composables/useUrlFilters.ts
 delete mode 100644 frontend/src/shared/types/urlFilters.ts

diff --git a/frontend/src/shared/composables/useDataTableSync.ts b/frontend/src/shared/composables/useDataTableSync.ts
deleted file mode 100644
index 64b954c..0000000
--- a/frontend/src/shared/composables/useDataTableSync.ts
+++ /dev/null
@@ -1,186 +0,0 @@
-import { watch } from 'vue'
-import type { Table } from '@tanstack/vue-table'
-import type { UrlFiltersReturn } from '@/shared/types/urlFilters'
-
-// Configuration for field synchronization
-export interface FieldSyncConfig {
-  columnId: string
-  transform?: {
-    urlToTable?: (value: unknown) => unknown
-    tableToUrl?: (value: unknown) => unknown
-  }
-}
-
-// Configuration for sort synchronization
-export interface SortSyncConfig<T> {
-  sortField: keyof T
-  orderField: keyof T
-  defaultSort?: { column: string; order: 'asc' | 'desc' }
-}
-
-// Complete sync configuration
-/* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-export interface DataTableSyncConfig<T extends Record<string, any>> {
-  mapping: Record<keyof T, FieldSyncConfig>
-  sortConfig?: SortSyncConfig<T>
-}
-
-// Utility function to capitalize first letter
-function capitalize(str: string): string {
-  return str.charAt(0).toUpperCase() + str.slice(1)
-}
-
-// Setup synchronization for a single field
-/* eslint-disable @typescript-eslint/no-explicit-any */
-function setupFieldSync<T extends Record<string, any>>(
-  urlField: keyof T,
-  fieldConfig: FieldSyncConfig,
-  table: Table<any>,
-  urlFilters: UrlFiltersReturn<T>
-) {
-  const { columnId, transform } = fieldConfig
-
-  // URL → Table synchronization
-  watch(
-    () => urlFilters.filters[urlField],
-    newValue => {
-      const transformedValue = transform?.urlToTable?.(newValue) ?? newValue
-      table.getColumn(columnId)?.setFilterValue(transformedValue || undefined)
-    },
-    { immediate: true }
-  )
-
-  // Table → URL synchronization
-  watch(
-    () => table.getColumn(columnId)?.getFilterValue(),
-    newValue => {
-      const transformedValue = transform?.tableToUrl?.(newValue) ?? newValue
-      const updateMethodName = `update${capitalize(String(urlField))}` as keyof UrlFiltersReturn<T>
-
-      if (typeof urlFilters[updateMethodName] === 'function') {
-        const currentValue = urlFilters.filters[urlField]
-        if (transformedValue !== currentValue) {
-          /* eslint-disable-next-line @typescript-eslint/no-unsafe-function-type */
-          ;(urlFilters[updateMethodName] as Function)(transformedValue || '')
-        }
-      }
-    }
-  )
-}
-/* eslint-enable @typescript-eslint/no-explicit-any */
-
-// Setup sort synchronization
-/* eslint-disable @typescript-eslint/no-explicit-any */
-function setupSortSync<T extends Record<string, any>>(
-  sortConfig: SortSyncConfig<T>,
-  table: Table<any>,
-  urlFilters: UrlFiltersReturn<T>
-) {
-  const { sortField, orderField, defaultSort } = sortConfig
-
-  // URL → Table sort synchronization
-  watch(
-    [() => urlFilters.filters[sortField], () => urlFilters.filters[orderField]],
-    ([newSort, newOrder]) => {
-      if (newSort && newOrder) {
-        const currentSorting = table.getState().sorting
-        const targetSorting = [{ id: String(newSort), desc: newOrder === 'desc' }]
-
-        if (JSON.stringify(currentSorting) !== JSON.stringify(targetSorting)) {
-          table.setSorting(targetSorting)
-        }
-      }
-    },
-    { immediate: true }
-  )
-
-  // Table → URL sort synchronization
-  watch(
-    () => table.getState().sorting,
-    newSorting => {
-      if (newSorting.length > 0) {
-        const sort = newSorting[0]
-        const newSortColumn = sort.id
-        const newSortOrder = sort.desc ? 'desc' : 'asc'
-
-        const isDefaultSort =
-          defaultSort && newSortColumn === defaultSort.column && newSortOrder === defaultSort.order
-
-        if (!isDefaultSort) {
-          const currentSort = urlFilters.filters[sortField]
-          const currentOrder = urlFilters.filters[orderField]
-
-          if (newSortColumn !== currentSort || newSortOrder !== currentOrder) {
-            urlFilters.updateSort?.(newSortColumn, newSortOrder)
-          }
-        } else if (urlFilters.filters[sortField] || urlFilters.filters[orderField]) {
-          // Clear URL parameters when returning to default sort
-          urlFilters.updateSort?.('', 'asc')
-        }
-      }
-    },
-    { deep: true }
-  )
-}
-/* eslint-enable @typescript-eslint/no-explicit-any */
-
-// Main function to setup table synchronization
-/* eslint-disable @typescript-eslint/no-explicit-any */
-export function useDataTableSync<T extends Record<string, any>>(
-  table: Table<any>,
-  urlFilters: UrlFiltersReturn<T>,
-  config: DataTableSyncConfig<T>
-) {
-  // Setup field synchronization
-  Object.entries(config.mapping).forEach(([urlField, fieldConfig]) => {
-    setupFieldSync(urlField as keyof T, fieldConfig as FieldSyncConfig, table, urlFilters)
-  })
-
-  // Setup sort synchronization if configured
-  if (config.sortConfig) {
-    setupSortSync(config.sortConfig, table, urlFilters)
-  }
-}
-/* eslint-enable @typescript-eslint/no-explicit-any */
-
-// Predefined transformation functions for common use cases
-export const transforms = {
-  // For comma-separated strings to arrays
-  stringToArray: {
-    urlToTable: (value: string) => (value ? value.split(',').filter(Boolean) : undefined),
-    tableToUrl: (value: string[]) => (Array.isArray(value) ? value.join(',') : ''),
-  },
-
-  // For simple string filters
-  string: {
-    urlToTable: (value: string) => value || undefined,
-    tableToUrl: (value: string) => value || '',
-  },
-}
-
-// Preset configurations for common table types
-export const tableSyncPresets = {
-  events: {
-    mapping: {
-      search: { columnId: 'name', transform: transforms.string },
-      tag: { columnId: 'tags', transform: transforms.string },
-    },
-    sortConfig: {
-      sortField: 'sort' as const,
-      orderField: 'order' as const,
-      defaultSort: { column: 'id', order: 'desc' as const },
-    },
-  },
-
-  fields: {
-    mapping: {
-      search: { columnId: 'name', transform: transforms.string },
-      type: { columnId: 'field_type', transform: transforms.stringToArray },
-    },
-    sortConfig: {
-      sortField: 'sort' as const,
-      orderField: 'order' as const,
-      defaultSort: { column: 'id', order: 'desc' as const },
-    },
-  },
-}
diff --git a/frontend/src/shared/composables/useDataTableWithUrlQuery.ts b/frontend/src/shared/composables/useDataTableWithUrlQuery.ts
deleted file mode 100644
index a59715b..0000000
--- a/frontend/src/shared/composables/useDataTableWithUrlQuery.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import type { ColumnDef } from '@tanstack/vue-table'
-import { useDataTable } from './useDataTable'
-import type { UrlFiltersReturn } from '@/shared/types/urlFilters'
-import { useDataTableSync, tableSyncPresets } from './useDataTableSync'
-
-type SortingOption = {
-  id: string
-  desc: boolean
-}
-
-type UseDataTableOptions<TData, TValue> = {
-  data: () => TData[]
-  columns: () => ColumnDef<TData, TValue>[]
-  defaultSorting?: SortingOption[]
-  defaultPageSize?: number
-}
-
-export type TableType = 'events' | 'fields'
-
-export function useDataTableWithUrlQuery<TData, TValue>(
-  tableOptions: UseDataTableOptions<TData, TValue>,
-  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-  urlFilters: UrlFiltersReturn<any>,
-  tableType: TableType
-) {
-  const { table, sorting, columnFilters, pagination } = useDataTable(tableOptions)
-
-  // Use predefined configuration for the table type
-  const syncConfig = tableSyncPresets[tableType]
-
-  // Setup synchronization using the preset configuration
-  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-  useDataTableSync(table, urlFilters, syncConfig as any)
-
-  return {
-    table,
-    sorting,
-    columnFilters,
-    pagination,
-  }
-}
diff --git a/frontend/src/shared/composables/useUrlFilters.ts b/frontend/src/shared/composables/useUrlFilters.ts
deleted file mode 100644
index 3217676..0000000
--- a/frontend/src/shared/composables/useUrlFilters.ts
+++ /dev/null
@@ -1,225 +0,0 @@
-import { ref, watch, onMounted, reactive, type Ref } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
-import { useDebounceFn } from '@vueuse/core'
-import type {
-  UrlFiltersConfig,
-  UrlFiltersReturn,
-  EventsUrlFilters,
-  FieldsUrlFilters,
-  TagsUrlFilters,
-} from '@/shared/types/urlFilters'
-
-// Utility function to capitalize first letter
-function capitalize(str: string): string {
-  return str.charAt(0).toUpperCase() + str.slice(1)
-}
-
-// Utility function to get default value
-function getDefaultValue(filterConfig: { defaultValue?: unknown; type?: string }): unknown {
-  if (filterConfig.defaultValue !== undefined) {
-    return filterConfig.defaultValue
-  }
-
-  // Default values based on type
-  if (filterConfig.type === 'array') return []
-  if (filterConfig.type === 'boolean') return false
-  return ''
-}
-
-/* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-export function useUrlFilters<T extends Record<string, any>>(
-  config: UrlFiltersConfig<T>
-): UrlFiltersReturn<T> {
-  const route = useRoute()
-  const router = useRouter()
-
-  // Create reactive state for all filters using refs
-  const filtersRefs: Record<string, Ref<unknown>> = {}
-
-  // Initialize all filters with default values
-  Object.keys(config).forEach(key => {
-    const filterConfig = config[key as keyof T]
-    filtersRefs[key] = ref(getDefaultValue(filterConfig))
-  })
-
-  // Create debounced update functions for search fields
-  const debouncedUpdaters: Record<string, (value: unknown) => void> = {}
-  Object.entries(config).forEach(([key, filterConfig]) => {
-    if (filterConfig.debounce) {
-      debouncedUpdaters[key] = useDebounceFn((value: unknown) => {
-        updateUrl({ [filterConfig.param]: value } as Record<
-          string,
-          string | string[] | boolean | null
-        >)
-      }, filterConfig.debounce)
-    }
-  })
-
-  // Initialize filters from URL on mount
-  const initializeFromUrl = () => {
-    Object.entries(config).forEach(([key, filterConfig]) => {
-      const urlValue = route.query[filterConfig.param] as string
-      if (urlValue) {
-        if (filterConfig.type === 'array') {
-          filtersRefs[key].value = urlValue.split(',')
-        } else if (filterConfig.type === 'boolean') {
-          filtersRefs[key].value = urlValue === 'true'
-        } else {
-          filtersRefs[key].value = urlValue
-        }
-      }
-    })
-  }
-
-  // Update URL with new query parameters
-  const updateUrl = (newQuery: Record<string, string | string[] | boolean | null>) => {
-    const currentQuery = { ...route.query }
-
-    Object.entries(newQuery).forEach(([param, value]) => {
-      if (
-        value === null ||
-        value === '' ||
-        value === false ||
-        (Array.isArray(value) && value.length === 0)
-      ) {
-        delete currentQuery[param]
-      } else if (Array.isArray(value)) {
-        currentQuery[param] = value.join(',')
-      } else {
-        currentQuery[param] = String(value)
-      }
-    })
-
-    const currentQueryStr = JSON.stringify(route.query)
-    const newQueryStr = JSON.stringify(currentQuery)
-
-    if (currentQueryStr !== newQueryStr) {
-      router.replace({
-        path: route.path,
-        query: currentQuery,
-      })
-    }
-  }
-
-  /* eslint-disable-next-line @typescript-eslint/no-unsafe-function-type */
-  const updateMethods: Record<string, Function> = {}
-
-  Object.entries(config).forEach(([key, filterConfig]) => {
-    const methodName = `update${capitalize(key)}`
-
-    if (filterConfig.debounce) {
-      // For debounced fields (like search)
-      updateMethods[methodName] = (value: unknown) => {
-        filtersRefs[key].value = value
-        debouncedUpdaters[key](value)
-      }
-    } else {
-      // For immediate update fields
-      updateMethods[methodName] = (value: unknown) => {
-        filtersRefs[key].value = value
-        updateUrl({ [filterConfig.param]: value } as Record<
-          string,
-          string | string[] | boolean | null
-        >)
-      }
-    }
-  })
-
-  // Special method for sort that updates both sort and order
-  if ('sort' in config && 'order' in config) {
-    updateMethods.updateSort = (column: string, direction: 'asc' | 'desc') => {
-      filtersRefs.sort.value = column
-      filtersRefs.order.value = direction
-
-      const sortConfig = config.sort as { param: string }
-      const orderConfig = config.order as { param: string }
-
-      updateUrl({
-        [sortConfig.param]: column || null,
-        [orderConfig.param]: column ? direction : null,
-      })
-    }
-  }
-
-  // Clear all filters
-  const clearFilters = () => {
-    const clearQuery: Record<string, null> = {}
-
-    Object.entries(config).forEach(([key, filterConfig]) => {
-      filtersRefs[key].value = getDefaultValue(filterConfig)
-      clearQuery[filterConfig.param] = null
-    })
-
-    updateUrl(clearQuery)
-  }
-
-  // Update filters method for bulk updates
-  const updateFilters = (newFilters: Record<string, string | null>) => {
-    updateUrl(newFilters)
-  }
-
-  // Watch for route changes to update filters
-  watch(
-    () => route.query,
-    newQuery => {
-      Object.entries(config).forEach(([key, filterConfig]) => {
-        const urlValue = (newQuery[filterConfig.param] as string) || ''
-        let newValue: unknown
-
-        if (filterConfig.type === 'array') {
-          newValue = urlValue ? urlValue.split(',') : []
-        } else if (filterConfig.type === 'boolean') {
-          newValue = urlValue === 'true'
-        } else {
-          newValue = urlValue
-        }
-
-        if (JSON.stringify(filtersRefs[key].value) !== JSON.stringify(newValue)) {
-          filtersRefs[key].value = newValue
-        }
-      })
-    },
-    { deep: true }
-  )
-
-  onMounted(() => {
-    initializeFromUrl()
-  })
-
-  // Create filters object from refs for return
-  const filters = reactive({}) as T
-  Object.keys(config).forEach(key => {
-    Object.defineProperty(filters, key, {
-      get: () => filtersRefs[key].value,
-      set: value => {
-        filtersRefs[key].value = value
-      },
-    })
-  })
-
-  return {
-    filters,
-    ...updateMethods,
-    updateFilters,
-    clearFilters,
-  } as UrlFiltersReturn<T>
-}
-
-// Preset configurations for common use cases
-export const eventsFiltersConfig: UrlFiltersConfig<EventsUrlFilters> = {
-  search: { param: 'search', debounce: 300, defaultValue: '' },
-  tag: { param: 'tag', defaultValue: '' },
-  sort: { param: 'sort', defaultValue: '' },
-  order: { param: 'order', defaultValue: '' },
-}
-
-export const fieldsFiltersConfig: UrlFiltersConfig<FieldsUrlFilters> = {
-  search: { param: 'search', debounce: 300, defaultValue: '' },
-  type: { param: 'type', defaultValue: '' },
-  sort: { param: 'sort', defaultValue: '' },
-  order: { param: 'order', defaultValue: '' },
-}
-
-export const tagsFiltersConfig: UrlFiltersConfig<TagsUrlFilters> = {
-  search: { param: 'search', debounce: 300, defaultValue: '' },
-}
diff --git a/frontend/src/shared/types/urlFilters.ts b/frontend/src/shared/types/urlFilters.ts
deleted file mode 100644
index fffbae6..0000000
--- a/frontend/src/shared/types/urlFilters.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-// URL Filter type definitions for each page
-
-export interface EventsUrlFilters {
-  search: string
-  tag: string
-  sort: string
-  order: 'asc' | 'desc' | ''
-}
-
-export interface FieldsUrlFilters {
-  search: string
-  type: string
-  sort: string
-  order: 'asc' | 'desc' | ''
-}
-
-export interface TagsUrlFilters {
-  search: string
-}
-
-// Configuration for each filter
-export interface FilterConfig<T = string> {
-  param: string // URL parameter name
-  debounce?: number // debounce delay for search inputs
-  defaultValue?: T // default value
-  type?: 'string' | 'array' | 'boolean'
-}
-
-// Configuration object for URL filters
-/* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-export type UrlFiltersConfig<T extends Record<string, any>> = {
-  [K in keyof T]: FilterConfig<T[K]>
-}
-
-// Return type for useUrlFilters
-/* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-export interface UrlFiltersReturn<T extends Record<string, any>> {
-  // All filter values as reactive refs
-  filters: T
-  // Update methods for each filter
-  updateSearch?: (value: string) => void
-  updateTag?: (value: string) => void
-  updateType?: (value: string) => void
-  updateSort?: (column: string, direction: 'asc' | 'desc') => void
-  updateFilters?: (filters: Record<string, string | null>) => void
-  clearFilters: () => void
-}

From 1734e068cfb87cd56dc3844d3de441afb19c4eea Mon Sep 17 00:00:00 2001
From: Ivan Skvortsov <ivanskv2000@gmail.com>
Date: Fri, 15 May 2026 11:56:02 +0200
Subject: [PATCH 6/7] test(frontend): add unit tests for useDataTableUrlSync

---
 .../composables/useDataTableUrlSync.spec.ts   | 147 ++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 frontend/src/shared/composables/useDataTableUrlSync.spec.ts

diff --git a/frontend/src/shared/composables/useDataTableUrlSync.spec.ts b/frontend/src/shared/composables/useDataTableUrlSync.spec.ts
new file mode 100644
index 0000000..a387cfd
--- /dev/null
+++ b/frontend/src/shared/composables/useDataTableUrlSync.spec.ts
@@ -0,0 +1,147 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { useDataTableUrlSync, type SyncConfig } from './useDataTableUrlSync'
+import { useRoute, useRouter } from 'vue-router'
+
+// Mock vue-router to control route state and spy on navigation
+vi.mock('vue-router', () => ({
+  useRoute: vi.fn(),
+  useRouter: vi.fn(),
+}))
+
+describe('useDataTableUrlSync', () => {
+  const mockRouter = {
+    replace: vi.fn(),
+  }
+
+  const defaultConfig: SyncConfig = {
+    columnFilters: {
+      name: { param: 'search' },
+      tags: { param: 'tag', type: 'array' },
+    },
+    sorting: {
+      sortParam: 'sort',
+      orderParam: 'order',
+    },
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // Default setup for each test
+    /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+    ;(useRouter as any).mockReturnValue(mockRouter)
+  })
+
+  describe('URL-to-Table State', () => {
+    it('should correctly parse sorting state from mocked route query', () => {
+      // GIVEN the URL has sort and order params
+      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+      ;(useRoute as any).mockReturnValue({
+        query: { sort: 'name', order: 'desc' },
+      })
+
+      // WHEN we initialize the sync
+      const { state } = useDataTableUrlSync(defaultConfig)
+
+      // THEN it should return TanStack compatible sorting state
+      expect(state.sorting.value).toEqual([{ id: 'name', desc: true }])
+    })
+
+    it('should correctly parse string and array column filters from URL', () => {
+      // GIVEN a search string and a comma-separated list in the URL
+      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+      ;(useRoute as any).mockReturnValue({
+        query: { search: 'test-query', tag: 'frontend,testing' },
+      })
+
+      const { state } = useDataTableUrlSync(defaultConfig)
+
+      // THEN it should split the array and keep the string intact
+      expect(state.columnFilters.value).toEqual([
+        { id: 'name', value: 'test-query' },
+        { id: 'tags', value: ['frontend', 'testing'] },
+      ])
+    })
+  })
+
+  describe('Table-to-URL Updaters', () => {
+    it('should invoke router.replace with mapped parameters on sorting change', () => {
+      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+      ;(useRoute as any).mockReturnValue({ query: {} })
+
+      const { updaters } = useDataTableUrlSync(defaultConfig)
+
+      // WHEN the table triggers a sorting change
+      updaters.onSortingChange([{ id: 'id', desc: false }])
+
+      // THEN it should push the correct params to the URL
+      expect(mockRouter.replace).toHaveBeenCalledWith({
+        query: { sort: 'id', order: 'asc' },
+      })
+    })
+
+    it('should join array filters into a comma-separated string when updating URL', () => {
+      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+      ;(useRoute as any).mockReturnValue({ query: {} })
+
+      const { updaters } = useDataTableUrlSync(defaultConfig)
+
+      // WHEN the table triggers a filter change
+      updaters.onColumnFiltersChange([
+        { id: 'name', value: 'vuejs' },
+        { id: 'tags', value: ['refactor', 'clean-code'] },
+      ])
+
+      // THEN it should map them back to the query params
+      expect(mockRouter.replace).toHaveBeenCalledWith({
+        query: { search: 'vuejs', tag: 'refactor,clean-code' },
+      })
+    })
+
+    it('should support functional updaters (standard TanStack pattern)', () => {
+      // GIVEN an existing state in the URL
+      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+      ;(useRoute as any).mockReturnValue({
+        query: { sort: 'name', order: 'asc' },
+      })
+
+      const { updaters } = useDataTableUrlSync(defaultConfig)
+
+      // WHEN we use a functional updater to toggle the direction
+      updaters.onSortingChange((old) => [{ id: old[0].id, desc: !old[0].desc }])
+
+      // THEN it should calculate the new state based on old and update URL
+      expect(mockRouter.replace).toHaveBeenCalledWith({
+        query: { sort: 'name', order: 'desc' },
+      })
+    })
+  })
+
+  describe('Empty States', () => {
+    it('should return safe empty arrays when URL query is empty', () => {
+      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+      ;(useRoute as any).mockReturnValue({ query: {} })
+
+      const { state } = useDataTableUrlSync(defaultConfig)
+      expect(state.sorting.value).toEqual([])
+      expect(state.columnFilters.value).toEqual([])
+    })
+
+    it('should remove parameters from URL when state is cleared (empty array provided)', () => {
+      // GIVEN there are existing params
+      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+      ;(useRoute as any).mockReturnValue({
+        query: { sort: 'name', search: 'test' },
+      })
+
+      const { updaters } = useDataTableUrlSync(defaultConfig)
+
+      // WHEN we clear the sorting
+      updaters.onSortingChange([])
+
+      // THEN the sort params should be deleted from the final query
+      expect(mockRouter.replace).toHaveBeenCalledWith({
+        query: { search: 'test' },
+      })
+    })
+  })
+})

From b580e62150211cd0ede668bb462617b83e173acb Mon Sep 17 00:00:00 2001
From: Ivan Skvortsov <ivanskv2000@gmail.com>
Date: Fri, 15 May 2026 11:56:55 +0200
Subject: [PATCH 7/7] format

---
 frontend/src/shared/composables/useDataTableUrlSync.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend/src/shared/composables/useDataTableUrlSync.spec.ts b/frontend/src/shared/composables/useDataTableUrlSync.spec.ts
index a387cfd..1f32532 100644
--- a/frontend/src/shared/composables/useDataTableUrlSync.spec.ts
+++ b/frontend/src/shared/composables/useDataTableUrlSync.spec.ts
@@ -107,7 +107,7 @@ describe('useDataTableUrlSync', () => {
       const { updaters } = useDataTableUrlSync(defaultConfig)
 
       // WHEN we use a functional updater to toggle the direction
-      updaters.onSortingChange((old) => [{ id: old[0].id, desc: !old[0].desc }])
+      updaters.onSortingChange(old => [{ id: old[0].id, desc: !old[0].desc }])
 
       // THEN it should calculate the new state based on old and update URL
       expect(mockRouter.replace).toHaveBeenCalledWith({