@nuxt-customer-portal/timesheets 0.3.0

package/app/components/TimesheetsSubmissionTimeline.vue

@@ -0,0 +1,89 @@
+<script setup lang="ts">
+import type { SubmissionHistoryEventDto } from '@nuxt-customer-portal/timesheets/shared/types/timesheet'
+
+defineProps<{ events: readonly Readonly<SubmissionHistoryEventDto>[] }>()
+const { t, locale } = useI18n()
+const userStore = useUserStore()
+const isOwnEvent = (event: Readonly<SubmissionHistoryEventDto>) =>
+  !!event.actorUserId && event.actorUserId === userStore.currentUser?.id
+const formatHistoryDate = (date: string) =>
+  new Intl.DateTimeFormat(locale.value, { dateStyle: 'medium', timeStyle: 'short' }).format(new Date(date))
+</script>
+
+<template>
+  <section v-if="events?.length" class="border-t border-default pt-3">
+    <ol
+      class="relative w-full space-y-4 py-2 text-sm before:absolute before:inset-y-0 before:left-2 before:w-px before:bg-accented sm:before:left-1/2"
+    >
+      <li
+        v-for="event in events"
+        :key="event.id"
+        class="relative grid grid-cols-[1rem_minmax(0,1fr)] gap-x-4 sm:grid-cols-[minmax(0,1fr)_1rem_minmax(0,1fr)]"
+      >
+        <span
+          class="z-10 col-start-1 row-start-1 mt-4 size-4 rounded-full border-4 border-default sm:col-start-2"
+          :class="
+            ['APPROVED', 'AUTO_APPROVED'].includes(event.action)
+              ? 'bg-success'
+              : ['REJECTED', 'DISPUTED'].includes(event.action)
+                ? 'bg-error'
+                : ['SUBMITTED', 'CLIENT_SUBMITTED'].includes(event.action)
+                  ? 'bg-primary'
+                  : 'bg-warning'
+          "
+          aria-hidden="true"
+        />
+        <div
+          class="col-start-2 row-start-1 rounded-lg border p-3"
+          :class="
+            isOwnEvent(event)
+              ? 'border-primary/25 bg-primary/10 sm:col-start-3'
+              : 'border-default bg-elevated sm:col-start-1 sm:text-right'
+          "
+        >
+          <div
+            class="flex flex-wrap items-center gap-x-2 gap-y-1 text-xs"
+            :class="!isOwnEvent(event) ? 'sm:justify-end' : ''"
+          >
+            <p
+              class="shrink-0 font-medium"
+              :class="
+                ['APPROVED', 'AUTO_APPROVED'].includes(event.action)
+                  ? 'text-success'
+                  : ['REJECTED', 'DISPUTED'].includes(event.action)
+                    ? 'text-error'
+                    : 'text-default'
+              "
+            >
+              {{ t(`features.timesheets.submissions.events.${event.action}`) }}
+            </p>
+            <div class="flex items-center gap-1.5 text-default">
+              <UAvatar :src="event.actorImage ?? undefined" :alt="event.actorName ?? undefined" size="xs" />
+              <span
+                >{{ event.actorName }}<template v-if="event.clientName"> · {{ event.clientName }}</template></span
+              >
+            </div>
+            <time :datetime="event.createdAt" class="shrink-0 text-xs text-muted">{{
+              formatHistoryDate(event.createdAt)
+            }}</time>
+          </div>
+          <blockquote
+            v-if="event.comment"
+            class="mt-3 rounded-r-md border-l-2 bg-default/50 px-3 py-2 text-left italic text-default"
+            :class="
+              ['APPROVED', 'AUTO_APPROVED'].includes(event.action)
+                ? 'border-success/50'
+                : ['REJECTED', 'DISPUTED'].includes(event.action)
+                  ? 'border-error/50'
+                  : ['SUBMITTED', 'CLIENT_SUBMITTED'].includes(event.action)
+                    ? 'border-primary/50'
+                    : 'border-warning/50'
+            "
+          >
+            <p class="whitespace-pre-line break-words leading-relaxed">{{ event.comment }}</p>
+          </blockquote>
+        </div>
+      </li>
+    </ol>
+  </section>
+</template>

package/app/components/TimesheetsWorkspaceSettingsForm.vue

@@ -0,0 +1,80 @@
+<script setup lang="ts">
+import { z } from 'zod'
+import type { TimesheetsAdminBootstrap } from '@nuxt-customer-portal/timesheets/app/composables/useTimesheets'
+
+const props = defineProps<{
+  settings: TimesheetsAdminBootstrap['settings']
+  refresh: () => Promise<unknown>
+}>()
+
+const { t } = useI18n()
+const toast = useToast()
+const timesheets = useTimesheets()
+const busy = ref(false)
+const draft = reactive({
+  timerRoundingMinutes: 1,
+  currency: 'EUR',
+  timezone: 'Europe/Amsterdam'
+})
+const timezoneOptions = computed(() =>
+  [...new Set(['UTC', ...Intl.supportedValuesOf('timeZone'), draft.timezone])].sort()
+)
+const schema = computed(() =>
+  z.object({
+    timerRoundingMinutes: z.number().int().min(1).max(60),
+    currency: z.string().trim().length(3, t('features.timesheets.validation.currencyLength')),
+    timezone: z.string().trim().min(3, t('features.timesheets.validation.required')).max(100)
+  })
+)
+
+watch(
+  () => props.settings,
+  (settings) => {
+    draft.timerRoundingMinutes = settings.timerRoundingMinutes ?? 1
+    draft.currency = settings.currency
+    draft.timezone = settings.timezone
+  },
+  { immediate: true }
+)
+
+const save = async () => {
+  busy.value = true
+  try {
+    await timesheets.updateSettings(draft)
+    await props.refresh()
+    toast.add({ title: t('features.timesheets.messages.settingsSaved'), color: 'success' })
+  } catch (error) {
+    toast.add({
+      title: t('features.timesheets.messages.saveError'),
+      description: String(error),
+      color: 'error'
+    })
+  } finally {
+    busy.value = false
+  }
+}
+</script>
+
+<template>
+  <UCard>
+    <UForm novalidate :state="draft" :schema="schema" class="max-w-xl space-y-4" @submit="save">
+      <UFormField name="currency" :label="t('features.timesheets.admin.currency')" required>
+        <UInput v-model="draft.currency" maxlength="3" class="w-full uppercase sm:w-28" />
+      </UFormField>
+      <UFormField name="timezone" :label="t('features.timesheets.admin.timezone')" required>
+        <USelectMenu v-model="draft.timezone" :items="timezoneOptions" class="w-full sm:w-80" />
+      </UFormField>
+      <UFormField
+        name="timerRoundingMinutes"
+        :label="t('features.timesheets.admin.timerRounding')"
+        :description="t('features.timesheets.admin.timerRoundingHelp')"
+        required
+      >
+        <UInput v-model.number="draft.timerRoundingMinutes" type="number" :min="1" :max="60" class="w-full sm:w-28" />
+      </UFormField>
+      <UButton type="submit" class="w-full justify-center sm:w-auto" icon="i-lucide-save" :loading="busy">
+        {{ t('features.timesheets.save') }}
+      </UButton>
+    </UForm>
+  </UCard>
+</template>

package/app/composables/useTimesheetMenu.ts

@@ -0,0 +1,69 @@
+export const useTimesheetMenu = () => {
+  const { activeOrganizationRole, isSystemAdmin } = usePortalSession()
+  const { t } = useI18n()
+  const route = useRoute()
+
+  const isOrganizationAdmin = computed(() => {
+    const role = activeOrganizationRole.value
+    return isSystemAdmin.value || role === 'owner' || role === 'admin'
+  })
+
+  const menuItems = computed(() => {
+    const items = [
+      {
+        label: t('features.timesheets.navigation.myTimesheet'),
+        to: '/timesheets',
+        icon: 'i-lucide-clock-3',
+        active: route.path === '/timesheets'
+      }
+    ]
+
+    if (isOrganizationAdmin.value) {
+      items.push(
+        {
+          label: t('features.timesheets.internalApprovals.manageTitle'),
+          to: '/admin/timesheets/internal-approvals',
+          icon: 'i-lucide-user-round-check',
+          active: route.path === '/admin/timesheets/internal-approvals'
+        },
+        {
+          label: t('features.timesheets.admin.projects'),
+          to: '/admin/timesheets/projects',
+          icon: 'i-lucide-folder-kanban',
+          active: route.path === '/admin/timesheets/projects'
+        },
+        {
+          label: t('features.timesheets.admin.activities'),
+          to: '/admin/timesheets/activities',
+          icon: 'i-lucide-tags',
+          active: route.path === '/admin/timesheets/activities'
+        },
+        {
+          label: t('features.timesheets.admin.teamRates'),
+          to: '/admin/timesheets/rates',
+          icon: 'i-lucide-badge-euro',
+          active: route.path === '/admin/timesheets/rates'
+        },
+        {
+          label: t('features.timesheets.admin.workspaceSettings'),
+          to: '/admin/timesheets/settings',
+          icon: 'i-lucide-settings-2',
+          active: route.path === '/admin/timesheets/settings'
+        },
+        {
+          label: t('features.timesheets.admin.reports'),
+          to: '/admin/timesheets/reports',
+          icon: 'i-lucide-chart-no-axes-combined',
+          active: route.path === '/admin/timesheets/reports'
+        }
+      )
+    }
+
+    return items
+  })
+
+  return {
+    menuItems: readonly(menuItems),
+    isOrganizationAdmin: readonly(isOrganizationAdmin)
+  }
+}

package/app/composables/useTimesheetMutationError.ts

@@ -0,0 +1,35 @@
+import { TIMESHEET_ERROR_CODES } from '@nuxt-customer-portal/timesheets/shared/timesheet-errors'
+
+type ApiErrorShape = {
+  data?: { code?: string; data?: { code?: string } }
+  message?: string
+}
+
+export const useTimesheetMutationError = () => {
+  const { t } = useI18n()
+  const toast = useToast()
+
+  const codeFor = (error: unknown) => {
+    const value = error as ApiErrorShape
+    return value?.data?.code ?? value?.data?.data?.code
+  }
+
+  const show = (error: unknown, titleKey = 'features.timesheets.messages.saveError') => {
+    const code = codeFor(error)
+    const descriptionKey =
+      code === 'TIMESHEET_PERIOD_LOCKED'
+        ? 'features.timesheets.validation.periodLocked'
+        : code === TIMESHEET_ERROR_CODES.tariffRequired
+          ? 'features.timesheets.errors.tariffRequired'
+          : code === TIMESHEET_ERROR_CODES.entryDisabled
+            ? 'features.timesheets.errors.entryDisabled'
+            : code === TIMESHEET_ERROR_CODES.runningTimer
+              ? 'features.timesheets.errors.runningTimer'
+              : code === TIMESHEET_ERROR_CODES.internalApproverRequired
+                ? 'features.timesheets.errors.internalApproverRequired'
+                : 'features.timesheets.errors.generic'
+    toast.add({ title: t(titleKey), description: t(descriptionKey), color: 'error' })
+  }
+
+  return { codeFor, show }
+}

package/app/composables/useTimesheets.ts

@@ -0,0 +1,248 @@
+import type {
+  ActivityTypeDto,
+  ApprovalQueueItemDto,
+  ClientOrganizationOptionDto,
+  ClientDto,
+  ProjectDto,
+  TeamMemberDto,
+  TimesheetBootstrapDto,
+  TimesheetReportDto,
+  TimeEntryDto,
+  ClientAccessMode,
+  ClientTimesheetsDto,
+  ClientWorkspaceDto,
+  ClientReviewerDto,
+  ClientReviewerSupplierDto,
+  ClientApprovalSupplierOptionDto,
+  TimesheetsDashboardDto,
+  TimesheetsSetupStatusDto,
+  InternalApprovalConfigurationDto,
+  InternalApprovalQueueDto
+} from '@nuxt-customer-portal/timesheets/shared/types/timesheet'
+
+export interface TimesheetsAdminBootstrap {
+  providerOrganization: { organizationId: string; name: string }
+  settings: {
+    timerRoundingMinutes?: number
+    currency: string
+    timezone: string
+    weekStartsOn: number
+    internalApprovalsEnabled: boolean
+  }
+  clients: ClientDto[]
+  availableClientOrganizations: ClientOrganizationOptionDto[]
+  projects: ProjectDto[]
+  activities: ActivityTypeDto[]
+  team: TeamMemberDto[]
+  approvals: ApprovalQueueItemDto[]
+  setupStatus: TimesheetsSetupStatusDto
+}
+export interface OrganizationTimesheetCapabilities {
+  workspaceEnabled: boolean
+  clientOf: Array<{ workspaceOrganizationId: string; workspaceName: string; accessMode: ClientAccessMode }>
+}
+
+export const useTimesheets = () => {
+  const refreshApprovalState = async () => {
+    if (import.meta.client) {
+      window.dispatchEvent(new Event('timesheets:capabilities-refresh'))
+    }
+    // Invalidate cached dashboard data even when its widgets are not mounted.
+    clearNuxtData('timesheets-dashboard')
+    await refreshNuxtData('timesheets-dashboard')
+  }
+  const bootstrap = (week?: string) => $fetch<TimesheetBootstrapDto>('/api/timesheets/bootstrap', { query: { week } })
+  const dashboard = () => $fetch<TimesheetsDashboardDto>('/api/timesheets/dashboard')
+  const internalApprovalQueue = (contextOnly = false) =>
+    $fetch<InternalApprovalQueueDto>('/api/timesheets/internal-approvals', { query: { contextOnly } })
+  const internalApprovalConfiguration = () =>
+    $fetch<InternalApprovalConfigurationDto>('/api/timesheets/admin/internal-approvals')
+  const updateInternalApprovalWorkspace = (enabled: boolean) =>
+    $fetch('/api/timesheets/admin/internal-approvals', { method: 'PATCH', body: { enabled } })
+  const updateInternalApprovalMember = (userId: string, input: { required: boolean; approverUserIds: string[] }) =>
+    $fetch(`/api/timesheets/admin/internal-approvals/${userId}`, { method: 'PUT', body: input })
+  const setupStatus = () => $fetch<TimesheetsSetupStatusDto>('/api/timesheets/setup-status')
+
+  const createEntry = (input: {
+    projectId: string
+    activityTypeId: string
+    entryDate: string
+    durationMinutes: number
+    note?: string | null
+  }) => $fetch<TimeEntryDto>('/api/timesheets/entries', { method: 'POST', body: input })
+
+  const updateEntry = (
+    id: string,
+    input: Partial<{
+      projectId: string
+      activityTypeId: string
+      entryDate: string
+      durationMinutes: number
+      note: string | null
+    }>
+  ) => $fetch<TimeEntryDto>(`/api/timesheets/entries/${id}`, { method: 'PATCH', body: input })
+
+  const deleteEntry = (id: string) => $fetch(`/api/timesheets/entries/${id}`, { method: 'DELETE' as never })
+
+  const startTimer = (input: { projectId: string; activityTypeId: string; entryDate: string; note?: string | null }) =>
+    $fetch<TimeEntryDto>('/api/timesheets/timer', { method: 'POST', body: input })
+
+  const stopTimer = () => $fetch<TimeEntryDto>('/api/timesheets/timer', { method: 'DELETE' as never })
+
+  const submitWeek = (id: string, cutoffDate: string, comment?: string) =>
+    $fetch(`/api/timesheets/weeks/${id}/submissions`, { method: 'POST', body: { cutoffDate, comment } })
+  const replyClientSubmission = (id: string, clientOrganizationId: string, expectedVersion: number, reply?: string) =>
+    $fetch(`/api/timesheets/submissions/${id}/client-reply`, {
+      method: 'POST',
+      body: { clientOrganizationId, expectedVersion, reply }
+    })
+  const resubmitSubmission = (id: string, reply?: string) =>
+    $fetch(`/api/timesheets/submissions/${id}/resubmit`, { method: 'POST', body: { reply } })
+
+  const adminBootstrap = (section?: string) =>
+    $fetch<TimesheetsAdminBootstrap>('/api/timesheets/admin/bootstrap', { query: section ? { section } : undefined })
+  const createClient = (
+    input: { mode: 'link'; organizationId: string } | { mode: 'create'; name: string; slug: string }
+  ) => $fetch('/api/timesheets/admin/clients', { method: 'POST', body: input })
+  const getClientDeletionEligibility = (id: string) =>
+    $fetch<{ clientId: string; clientName: string; canDelete: boolean }>(`/api/timesheets/admin/clients/${id}/deletion`)
+  const deleteClient = (id: string, clientName: string) =>
+    $fetch(`/api/timesheets/admin/clients/${id}`, {
+      method: 'DELETE' as never,
+      body: { clientName }
+    })
+  const updateClientAccess = (id: string, accessMode: ClientAccessMode) =>
+    $fetch(`/api/timesheets/admin/clients/${id}`, { method: 'PATCH', body: { accessMode } })
+  const getOrganizationTimesheetCapabilities = (organizationId: string) =>
+    $fetch<OrganizationTimesheetCapabilities>(`/api/timesheets/admin/organization-capabilities/${organizationId}`)
+  const updateOrganizationTimesheetCapabilities = (organizationId: string, input: { workspaceEnabled: boolean }) =>
+    $fetch(`/api/timesheets/admin/organization-capabilities/${organizationId}`, { method: 'PATCH', body: input })
+  const clientWorkspaces = () => $fetch<ClientWorkspaceDto[]>('/api/timesheets/client/workspaces')
+  const clientApprovalMembers = () =>
+    $fetch<Array<{ id: string; name: string }>>('/api/timesheets/client/approval-members')
+  const clientApprovalSuppliers = () =>
+    $fetch<ClientApprovalSupplierOptionDto[]>('/api/timesheets/client/approval-suppliers')
+  const clientSupplierOptions = () =>
+    $fetch<ClientApprovalSupplierOptionDto[]>('/api/timesheets/client/supplier-options')
+  const clientReviewerSuppliers = () => $fetch<ClientReviewerSupplierDto[]>('/api/timesheets/client/reviewer-suppliers')
+  const clientTimesheets = (workspaceClientId: string) =>
+    $fetch<ClientTimesheetsDto>(`/api/timesheets/client/${workspaceClientId}`)
+  const reviewClientSlice = async (
+    workspaceClientId: string,
+    submissionId: string,
+    input: { action: 'APPROVE' | 'DISPUTE'; expectedVersion: number; comment?: string | null }
+  ) => {
+    const result = await $fetch(`/api/timesheets/client/${workspaceClientId}/reviews/${submissionId}`, {
+      method: 'POST',
+      body: input
+    })
+    await refreshApprovalState()
+    return result
+  }
+  const clientReviewers = (workspaceClientId: string) =>
+    $fetch<ClientReviewerDto[]>(`/api/timesheets/client/${workspaceClientId}/reviewers`)
+  const setClientReviewer = (workspaceClientId: string, userId: string, assigned: boolean) =>
+    $fetch(`/api/timesheets/client/${workspaceClientId}/reviewers`, { method: 'PUT', body: { userId, assigned } })
+  const createActivity = (input: { name: string; billable: boolean }) =>
+    $fetch('/api/timesheets/admin/activities', { method: 'POST', body: input })
+  const updateActivity = (id: string, input: Partial<{ name: string; billable: boolean; active: boolean }>) =>
+    $fetch(`/api/timesheets/admin/activities/${id}`, { method: 'PATCH', body: input })
+  const getActivityDeletionEligibility = (id: string) =>
+    $fetch<{ activityId: string; activityName: string; canDelete: boolean }>(
+      `/api/timesheets/admin/activities/${id}/deletion`
+    )
+  const deleteActivity = (id: string, activityName: string) =>
+    $fetch(`/api/timesheets/admin/activities/${id}`, {
+      method: 'DELETE' as never,
+      body: { activityName }
+    })
+  const createProject = (input: {
+    clientOrganizationId: string
+    name: string
+    code?: string | null
+    budgetMinutes?: number | null
+    budgetMinor?: number | null
+    activityTypeIds: string[]
+  }) => $fetch<{ id: string }>('/api/timesheets/admin/projects', { method: 'POST', body: input })
+  const getProject = (id: string) => $fetch<ProjectDto>(`/api/timesheets/admin/projects/${id}`)
+  const updateProject = (id: string, input: Record<string, unknown>) =>
+    $fetch(`/api/timesheets/admin/projects/${id}`, { method: 'PATCH', body: input })
+  const getProjectDeletionEligibility = (id: string) =>
+    $fetch<{ projectId: string; projectName: string; canDelete: boolean }>(
+      `/api/timesheets/admin/projects/${id}/deletion`
+    )
+  const deleteProject = (id: string, projectName: string) =>
+    $fetch(`/api/timesheets/admin/projects/${id}`, {
+      method: 'DELETE' as never,
+      body: { projectName }
+    })
+  const setTeamTariff = (userId: string, hourlyRateMinor: number) =>
+    $fetch('/api/timesheets/admin/tariffs', {
+      method: 'PUT',
+      body: { userId, hourlyRateMinor }
+    })
+  const updateTeamMemberSettings = (
+    userId: string,
+    input: { canEnterTime: boolean; defaultHourlyRateMinor: number | null }
+  ) => $fetch(`/api/timesheets/admin/team/${userId}`, { method: 'PUT', body: input })
+  const updateSettings = (input: { currency?: string; timezone?: string; timerRoundingMinutes?: number }) =>
+    $fetch('/api/timesheets/admin/settings', { method: 'PATCH', body: input })
+  const reviewSubmission = async (id: string, action: 'APPROVE' | 'REJECT' | 'REOPEN', comment?: string | null) => {
+    const result = await $fetch(`/api/timesheets/internal-approvals/${id}`, {
+      method: 'POST',
+      body: { action, comment }
+    })
+    await refreshApprovalState()
+    return result
+  }
+  const getReport = (query: Record<string, string | undefined>) =>
+    $fetch<TimesheetReportDto>('/api/timesheets/admin/report', { query })
+
+  return {
+    bootstrap,
+    dashboard,
+    internalApprovalQueue,
+    internalApprovalConfiguration,
+    updateInternalApprovalWorkspace,
+    updateInternalApprovalMember,
+    setupStatus,
+    createEntry,
+    updateEntry,
+    deleteEntry,
+    startTimer,
+    stopTimer,
+    submitWeek,
+    resubmitSubmission,
+    replyClientSubmission,
+    adminBootstrap,
+    createClient,
+    getClientDeletionEligibility,
+    deleteClient,
+    updateClientAccess,
+    getOrganizationTimesheetCapabilities,
+    updateOrganizationTimesheetCapabilities,
+    clientWorkspaces,
+    clientApprovalSuppliers,
+    clientApprovalMembers,
+    clientSupplierOptions,
+    clientReviewerSuppliers,
+    clientTimesheets,
+    reviewClientSlice,
+    clientReviewers,
+    setClientReviewer,
+    createActivity,
+    updateActivity,
+    getActivityDeletionEligibility,
+    deleteActivity,
+    createProject,
+    getProject,
+    updateProject,
+    getProjectDeletionEligibility,
+    deleteProject,
+    setTeamTariff,
+    updateTeamMemberSettings,
+    updateSettings,
+    reviewSubmission,
+    getReport
+  }
+}

package/app/composables/useTimesheetsAdminList.ts

@@ -0,0 +1,165 @@
+import type { TimesheetsListResponse } from '@nuxt-customer-portal/timesheets/shared/types/timesheet'
+import { usePaginatedResource } from '@nuxt-customer-portal/core/app/composables/usePaginatedResource'
+
+export const useTimesheetsAdminList = <Item>(options: {
+  endpoint: string
+  filterKeys?: string[]
+  defaultFilters?: Record<string, string>
+  defaultSort: string
+  defaultSortDir?: 'asc' | 'desc'
+}) => {
+  const route = useRoute()
+  const router = useRouter()
+  const pageSize = 20
+  const defaultSortDir = options.defaultSortDir ?? 'asc'
+  const search = ref(String(route.query.search ?? ''))
+  const sortBy = ref(String(route.query.sortBy ?? options.defaultSort))
+  const sortDir = ref<'asc' | 'desc'>(
+    route.query.sortDir === 'asc' || route.query.sortDir === 'desc' ? route.query.sortDir : defaultSortDir
+  )
+  const currentPage = ref(Math.max(1, Number(route.query.page) || 1))
+  const filters = reactive<Record<string, string | undefined>>(
+    Object.fromEntries(
+      (options.filterKeys ?? []).map((key) => [
+        key,
+        route.query[key] ? String(route.query[key]) : options.defaultFilters?.[key]
+      ])
+    )
+  )
+  const resource = usePaginatedResource<Item, Record<string, string | undefined>>({
+    pageSize,
+    getKey: (item) => (item as { id: string }).id,
+    fetchPage: ({ filters: query, page, pageSize, signal }) =>
+      $fetch<TimesheetsListResponse<Item>>(options.endpoint, { query: { ...query, page, pageSize }, signal })
+  })
+  const query = () => ({
+    ...(search.value.trim() ? { search: search.value.trim() } : {}),
+    ...Object.fromEntries(Object.entries(filters).filter(([, value]) => value)),
+    ...(sortBy.value !== options.defaultSort ? { sortBy: sortBy.value } : {}),
+    ...(sortDir.value !== defaultSortDir ? { sortDir: sortDir.value } : {})
+  })
+  const routeQuery = () => ({
+    ...(search.value.trim() ? { search: search.value.trim() } : {}),
+    ...Object.fromEntries(
+      Object.entries(filters).filter(([key, value]) => value && value !== options.defaultFilters?.[key])
+    ),
+    ...(sortBy.value !== options.defaultSort ? { sortBy: sortBy.value } : {}),
+    ...(sortDir.value !== defaultSortDir ? { sortDir: sortDir.value } : {})
+  })
+  const syncRoute = (page = currentPage.value) =>
+    router.replace({ path: route.path, query: { ...routeQuery(), ...(page > 1 ? { page: String(page) } : {}) } })
+  const load = async (page = currentPage.value) => {
+    const result = await resource.loadPage(query(), { page, pageSize })
+    if (result) {
+      currentPage.value = result.pagination.page
+    }
+    return result
+  }
+  const resetAndLoad = async () => {
+    currentPage.value = 1
+    await syncRoute(1)
+    await load(1)
+  }
+  const loadNext = async () => {
+    const result = await resource.loadNextPage(query())
+    if (result) {
+      currentPage.value = result.pagination.page
+      await syncRoute(currentPage.value)
+    }
+  }
+  const loadPrevious = async () => {
+    const result = await resource.loadPreviousPage(query())
+    if (result) {
+      currentPage.value = result.pagination.page
+      await syncRoute(currentPage.value)
+    }
+    return result
+  }
+  const goToPage = async (page: number) => {
+    currentPage.value = page
+    await syncRoute(page)
+    await load(page)
+  }
+  const setFilter = (key: string, value: string | undefined) => {
+    filters[key] = value
+  }
+  const toggleSortDir = () => {
+    sortDir.value = sortDir.value === 'asc' ? 'desc' : 'asc'
+  }
+  let searchTimer: ReturnType<typeof setTimeout> | undefined
+  let applyingRoute = false
+  watch(
+    search,
+    () => {
+      if (applyingRoute) {
+        return
+      }
+      clearTimeout(searchTimer)
+      searchTimer = setTimeout(() => {
+        void resetAndLoad()
+      }, 300)
+    },
+    { flush: 'sync' }
+  )
+  watch(
+    [sortBy, sortDir, ...Object.keys(filters).map((key) => () => filters[key])],
+    () => {
+      if (applyingRoute) {
+        return
+      }
+      clearTimeout(searchTimer)
+      void resetAndLoad()
+    },
+    { flush: 'sync' }
+  )
+  watch(
+    () => route.query,
+    async (routeQuery) => {
+      const nextSearch = String(routeQuery.search ?? '')
+      const nextSort = String(routeQuery.sortBy ?? options.defaultSort)
+      const nextDir =
+        routeQuery.sortDir === 'asc' || routeQuery.sortDir === 'desc' ? routeQuery.sortDir : defaultSortDir
+      const nextPage = Math.max(1, Number(routeQuery.page) || 1)
+      const nextFilters = Object.fromEntries(
+        (options.filterKeys ?? []).map((key) => [
+          key,
+          routeQuery[key] ? String(routeQuery[key]) : options.defaultFilters?.[key]
+        ])
+      )
+      if (
+        nextSearch === search.value.trim() &&
+        nextSort === sortBy.value &&
+        nextDir === sortDir.value &&
+        nextPage === currentPage.value &&
+        Object.keys(nextFilters).every((key) => nextFilters[key] === filters[key])
+      ) {
+        return
+      }
+      clearTimeout(searchTimer)
+      applyingRoute = true
+      search.value = nextSearch
+      sortBy.value = nextSort
+      sortDir.value = nextDir
+      currentPage.value = nextPage
+      Object.assign(filters, nextFilters)
+      applyingRoute = false
+      await load(nextPage)
+    }
+  )
+  onScopeDispose(() => clearTimeout(searchTimer))
+  return {
+    ...resource,
+    search,
+    filters,
+    sortBy,
+    sortDir,
+    currentPage,
+    load,
+    refresh: load,
+    loadNext,
+    loadPrevious,
+    goToPage,
+    setFilter,
+    toggleSortDir
+  }
+}