@datagouv/components-next 1.0.2-dev.232 → 1.0.2-dev.233

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datagouv/components-next",
-  "version": "1.0.2-dev.232",
+  "version": "1.0.2-dev.233",
   "private": false,
   "type": "module",
   "engines": {

package/src/components/ResourceExplorer/ResourceExplorer.vue

@@ -112,6 +112,7 @@ import { useRoute } from 'vue-router'
 import type { RouteLocationRaw } from 'vue-router'
 import { useTranslation } from '../../composables/useTranslation'
 import { useDatasetResources } from '../../composables/useDatasetResources'
+import { TABULAR_FILTERS_PARAM, TABULAR_SEARCH_PARAM, TABULAR_SORT_PARAM } from '../../functions/tabular'
 import type { DatasetV2 } from '../../types/datasets'
 import type { Resource } from '../../types/resources'
 import ResourceExplorerSidebar from './ResourceExplorerSidebar.vue'
@@ -161,7 +162,11 @@ watch(selectedResource, resource => emit('select', resource), { immediate: true
 const sidebarCollapsed = ref(false)
 const resourceListExpanded = ref(false)
 
-const resourceTo = (resource: Resource): RouteLocationRaw => ({
-  query: { ...route.query, resource_id: resource.id },
-})
+// The filters and sort of the table name the columns of the resource they were
+// set on: carried over, they would query columns the next one may not have. The
+// search goes with them: it was typed for the content of the previous resource.
+const resourceTo = (resource: Resource): RouteLocationRaw => {
+  const { [TABULAR_FILTERS_PARAM]: _filters, [TABULAR_SORT_PARAM]: _sort, [TABULAR_SEARCH_PARAM]: _search, ...query } = route.query
+  return { query: { ...query, resource_id: resource.id } }
+}
 </script>

package/src/components/ResourceExplorer/ResourceExplorerViewer.vue

@@ -63,9 +63,12 @@
                 v-if="previewKind === 'tabular'"
                 :timeout="200"
               >
+                <!-- Fullscreen, the explorer owns the page and its URL: the filters
+                     can live there. Inline, the URL belongs to the dataset page. -->
                 <TabularExplorer
                   v-model:global-search="search"
                   :resource-id="resource.id"
+                  :sync-url="fullscreen"
                 >
                   <TabularToolbar class="shrink-0 border-b border-gray-default p-2" />
                   <div class="hidden shrink-0 md:block">

package/src/components/TabularExplorer/TabularActiveFilters.vue

@@ -93,13 +93,13 @@
       </BrandedButton>
       <!-- Clear all -->
       <BrandedButton
-        v-if="withClear"
+        v-if="withClear && canReset"
         color="tertiary"
         size="2xs"
         :icon="RiCloseLine"
-        @click="clearAllFilters(); sort = null"
+        @click="reset"
       >
-        {{ t('Tout effacer') }}
+        {{ t('Tout réinitialiser') }}
       </BrandedButton>
     </div>
   </div>
@@ -115,5 +115,5 @@ import { useTabularContext } from './useTabularContext'
 defineProps<{ withClear?: boolean }>()
 
 const { t } = useTranslation()
-const { tableData, activeFilters, sort, globalSearch, removeFilter, clearAllFilters, getColumnDisplay, filteredDownloadUrl } = useTabularContext()
+const { tableData, activeFilters, sort, globalSearch, removeFilter, canReset, reset, getColumnDisplay, filteredDownloadUrl } = useTabularContext()
 </script>

package/src/components/TabularExplorer/TabularExplorer.vue

@@ -30,12 +30,13 @@ import { useFetch } from '../../functions/api'
 import { useComponentsConfig } from '../../config'
 import { useTranslation } from '../../composables/useTranslation'
 import { injectTabularProfile } from '../../composables/useTabularProfile'
-import { hasFilterForColumn as _hasFilterForColumn, buildDateFilterParams, buildGlobalSearchConditions, useFormatTabular } from '../../functions/tabular'
+import { hasFilterForColumn as _hasFilterForColumn, buildDateFilterParams, buildGlobalSearchConditions, isSameSort, useFormatTabular } from '../../functions/tabular'
 import PreviewUnavailable from '../ResourceAccordion/PreviewUnavailable.vue'
 import TabularSkeleton from './TabularSkeleton.vue'
-import type { TabularDataResponse, TabularRow, SortConfig, ColumnFilters, DateFilter } from './types'
+import type { TabularDataResponse, TabularRow, SortConfig, ColumnFilters, DateFilter, TabularUrlAlias } from './types'
 import { provideTabularContext, type ActiveFilter } from './useTabularContext'
 import { useColumnMetadata } from './useColumnMetadata'
+import { useTabularUrlState } from './useTabularUrlState'
 
 const props = withDefaults(defineProps<{
   resourceId: string
@@ -45,11 +46,21 @@ const props = withDefaults(defineProps<{
   // Filters seeded on mount, e.g. { 'Administration': { contains: 'Ministère' } }.
   // The explorer owns them afterwards: later changes to this prop are ignored,
   // so pass a fresh instance (or remount) to reset them.
+  // Ignored with `syncUrl`: the filters come from the URL then.
   initialFilters?: Record<string, ColumnFilters>
   // Sort seeded on mount, e.g. { column: 'Séance', direction: 'desc' }.
   // Same ownership rule as `initialFilters`: the explorer owns it afterwards,
   // and the user can drop it from the active-sort chip.
+  // With `syncUrl`, it is the sort applied when the URL names none.
   initialSort?: SortConfig
+  // Keeps sort, filters and global search in the URL, so that going back to the
+  // page restores them. Only for an explorer that owns its page: the params are
+  // not namespaced.
+  syncUrl?: boolean
+  // With `syncUrl`, readable params for the simple filters of some columns,
+  // e.g. { administration: { column: 'Administration', operator: 'contains' } }.
+  // Any other filter goes into a JSON `filters` param.
+  urlAliases?: Record<string, TabularUrlAlias>
 }>(), {
   searchInput: true,
 })
@@ -61,7 +72,7 @@ const props = withDefaults(defineProps<{
 // Combined via AND with any column-specific `contains` filter, so it acts as an
 // additional narrowing constraint, not a replacement.
 // Owned here like the filters; a parent binds it to drive or keep it.
-const globalSearch = defineModel<string>('globalSearch', { default: '' })
+const globalSearchModel = defineModel<string>('globalSearch', { default: '' })
 
 const { t } = useTranslation()
 const config = useComponentsConfig()
@@ -91,9 +102,29 @@ const {
   getBooleanCounts,
 } = useColumnMetadata(profileData, allColumns, t)
 
-// Sort & filter state
-const sort = ref<SortConfig | null>(props.initialSort ? { ...props.initialSort } : null)
-const filters = ref<Record<string, ColumnFilters>>({ ...props.initialFilters })
+// Sort, filter & search state
+const urlState = props.syncUrl
+  ? useTabularUrlState(props.urlAliases ?? {}, props.initialSort ?? null, allColumns)
+  : null
+const { sort, filters, globalSearch } = urlState ?? {
+  sort: ref<SortConfig | null>(props.initialSort ? { ...props.initialSort } : null),
+  filters: ref<Record<string, ColumnFilters>>({ ...props.initialFilters }),
+  globalSearch: globalSearchModel,
+}
+
+// With `syncUrl` the search lives in the URL, and a bound `v-model` mirrors it.
+// A search the parent already holds at mount wins: it was typed while the
+// explorer was loading, after the URL was read.
+if (urlState) {
+  if (globalSearchModel.value) urlState.globalSearch.value = globalSearchModel.value
+  else globalSearchModel.value = urlState.globalSearch.value
+  watch(urlState.globalSearch, (value) => {
+    globalSearchModel.value = value
+  })
+  watch(globalSearchModel, (value) => {
+    urlState.globalSearch.value = value
+  })
+}
 
 const PAGE_SIZE = 50
 
@@ -310,9 +341,14 @@ const filteredDownloadUrl = computed(() => {
   return `${config.tabularApiUrl}/api/resources/${props.resourceId}/data/csv/?${params}`
 })
 
-function clearAllFilters() {
+// Resetting goes back to how the table opened: no filter nor search, but the
+// initial sort — it is the table's default order, not a criterion the user added.
+const canReset = computed(() => activeFilters.value.length > 0 || !!globalSearch.value || !isSameSort(sort.value, props.initialSort))
+
+function reset() {
   filters.value = {}
   globalSearch.value = ''
+  sort.value = props.initialSort ? { ...props.initialSort } : null
 }
 
 function hasFilterForColumn(col: string): boolean {
@@ -335,7 +371,8 @@ provideTabularContext({
   filters,
   activeFilters,
   removeFilter,
-  clearAllFilters,
+  canReset,
+  reset,
   globalSearch,
   searchInput: computed(() => props.searchInput),
   queryFailed,

package/src/components/TabularExplorer/TabularFilterContent.vue

@@ -250,7 +250,8 @@ watchDebounced(search, (q) => {
   const existing = filters.value[props.column] ?? {}
   const operator = isNumeric.value ? 'exact' : 'contains'
   if (q) {
-    filters.value = { ...filters.value, [props.column]: { ...existing, [operator]: q } }
+    // v-model on a `type="number"` input hands over a number, both criteria are strings
+    filters.value = { ...filters.value, [props.column]: { ...existing, [operator]: String(q) } }
   }
   else {
     const { [operator]: _, ...rest } = existing

package/src/components/TabularExplorer/TabularMobileFilters.vue

@@ -96,14 +96,14 @@
             </div>
             <!-- Reset all -->
             <div
-              v-if="activeFilters.length > 0 || sort"
+              v-if="canReset"
               class="border-t border-gray-default px-4 py-3"
             >
               <BrandedButton
                 color="secondary"
                 size="xs"
                 class="w-full"
-                @click="clearAllFilters(); sort = null; mobileFilterOpen = false"
+                @click="reset(); mobileFilterOpen = false"
               >
                 {{ t('Tout réinitialiser') }}
               </BrandedButton>
@@ -132,7 +132,8 @@ const {
   sort,
   filters,
   hasFilterForColumn,
-  clearAllFilters,
+  canReset,
+  reset,
   totalLines,
   getColumnDisplay,
   getColumnType,

package/src/components/TabularExplorer/TabularSearchInput.vue

@@ -33,7 +33,7 @@ watch(debounced, (value) => {
   globalSearch.value = value.trim()
 })
 
-// Cleared from elsewhere (its chip, "Tout effacer"): the field follows.
+// Cleared from elsewhere (its chip, "Tout réinitialiser"): the field follows.
 watch(globalSearch, (value) => {
   if (value !== text.value.trim()) text.value = value
 })

package/src/components/TabularExplorer/types.ts

@@ -67,7 +67,8 @@ export type TabularTopValue = {
 
 export type ColumnType = 'number' | 'categorical' | 'text' | 'date' | 'boolean' | 'year'
 
-export type DateFilterOperator = 'is' | 'before' | 'after' | 'between'
+export const DATE_FILTER_OPERATORS = ['is', 'before', 'after', 'between'] as const
+export type DateFilterOperator = typeof DATE_FILTER_OPERATORS[number]
 
 export type DateFilter = {
   operator: DateFilterOperator
@@ -87,6 +88,13 @@ export type ColumnFilters = {
   date?: DateFilter
 }
 
+// A short URL param standing for a single-operator filter on one column, e.g.
+// `?administration=Mairie` for `{ Administration: { contains: 'Mairie' } }`.
+export type TabularUrlAlias = {
+  column: string
+  operator: 'contains' | 'exact'
+}
+
 export type SortDirection = 'asc' | 'desc'
 
 export type SortConfig = {

package/src/components/TabularExplorer/useTabularContext.ts

@@ -42,8 +42,9 @@ export type TabularContext = {
   filters: Ref<Record<string, ColumnFilters>>
   activeFilters: ComputedRef<ActiveFilter[]>
   removeFilter: (column: string) => void
-  // Also empties the global search.
-  clearAllFilters: () => void
+  // Back to how the table opened: no filter nor search, the initial sort
+  canReset: ComputedRef<boolean>
+  reset: () => void
 
   // Global search across all columns, and whether the toolbar shows its field
   globalSearch: Ref<string>

package/src/components/TabularExplorer/useTabularUrlState.ts

@@ -0,0 +1,69 @@
+import { computed, toValue } from 'vue'
+import type { MaybeRefOrGetter, Ref } from 'vue'
+import { useRouteQuery } from '@vueuse/router'
+import { useRoute } from 'vue-router'
+import type { LocationQueryValue } from 'vue-router'
+import { useComponentsConfig } from '../../config'
+import {
+  TABULAR_FILTERS_PARAM,
+  TABULAR_SEARCH_PARAM,
+  TABULAR_SORT_PARAM,
+  filtersFromUrlQuery,
+  filtersToUrlQuery,
+  searchFromUrlParam,
+  sortFromUrlParam,
+  sortToUrlParam,
+} from '../../functions/tabular'
+import type { ColumnFilters, SortConfig, TabularUrlAlias } from './types'
+
+type QueryRef = Ref<LocationQueryValue | LocationQueryValue[] | undefined>
+
+/**
+ * Sort, filters and global search of the explorer, stored in the URL: going back
+ * to the page finds them again, and a link to it shares them. Only the `columns`
+ * of the resource are read from it.
+ *
+ * Every param goes through `useRouteQuery`, which batches the writes of a tick
+ * into a single `router.replace`: a change never stacks history entries, and
+ * moving a filter from an alias to the JSON param is one navigation, not two.
+ */
+export function useTabularUrlState(
+  aliases: Record<string, TabularUrlAlias>,
+  defaultSort: SortConfig | null,
+  columns: MaybeRefOrGetter<readonly string[]>,
+) {
+  const config = useComponentsConfig()
+  const route = (config.useRoute ?? useRoute)()
+  const filterRefs = [...Object.keys(aliases), TABULAR_FILTERS_PARAM]
+    .map(param => [param, useRouteQuery(param, undefined, { route }) as QueryRef] as const)
+  const sortRef = useRouteQuery(TABULAR_SORT_PARAM, undefined, { route }) as QueryRef
+  const searchRef = useRouteQuery(TABULAR_SEARCH_PARAM, undefined, { route }) as QueryRef
+
+  const filters = computed<Record<string, ColumnFilters>>({
+    get: () => filtersFromUrlQuery(
+      Object.fromEntries(filterRefs.map(([param, ref]) => [param, ref.value])),
+      aliases,
+      toValue(columns),
+    ),
+    set: (value) => {
+      const query = filtersToUrlQuery(value, aliases)
+      for (const [param, ref] of filterRefs) ref.value = query[param]
+    },
+  })
+
+  const sort = computed<SortConfig | null>({
+    get: () => sortFromUrlParam(sortRef.value, defaultSort, toValue(columns)),
+    set: (value) => {
+      sortRef.value = sortToUrlParam(value, defaultSort)
+    },
+  })
+
+  const globalSearch = computed<string>({
+    get: () => searchFromUrlParam(searchRef.value),
+    set: (value) => {
+      searchRef.value = value || undefined
+    },
+  })
+
+  return { filters, sort, globalSearch }
+}

package/src/config.ts

@@ -1,6 +1,7 @@
 import { inject, type Component, type InjectionKey } from 'vue'
 import type { UseFetchFunction } from './functions/api.types'
 import type { $Fetch, FetchOptions } from 'ofetch'
+import type { RouteLocationNormalizedLoaded } from 'vue-router'
 
 export type PluginConfig = {
   name: string // Name of the application (ex: data.gouv.fr)
@@ -43,6 +44,12 @@ export type PluginConfig = {
   textClamp?: string | Component | null
   appLink?: Component | null
   clientOnly?: Component | null
+  /**
+   * The route of the page a component is rendered in. vue-router's `useRoute` is the
+   * global one: while the next page loads, the page being left is still mounted and
+   * already sees the next URL. Nuxt's `useRoute` keeps each page on its own route.
+   */
+  useRoute?: () => RouteLocationNormalizedLoaded
   searchDebounce?: number
   forumUrl?: string
 }

package/src/functions/tabular.ts

@@ -23,7 +23,9 @@ import {
 } from '@remixicon/vue'
 import { useTranslation } from '../composables/useTranslation'
 import type { TranslationFunction } from '../composables/useTranslation'
-import type { ColumnFilters, ColumnType, DateFilter } from '../components/TabularExplorer/types'
+import type { LocationQueryValue } from 'vue-router'
+import { DATE_FILTER_OPERATORS } from '../components/TabularExplorer/types'
+import type { ColumnFilters, ColumnType, DateFilter, DateFilterOperator, SortConfig, TabularUrlAlias } from '../components/TabularExplorer/types'
 import { parseDateValue } from './dates'
 
 export function hasFilterForColumn(filters: Record<string, ColumnFilters>, column: string): boolean {
@@ -126,6 +128,137 @@ export function buildCellValueFilter(columnType: ColumnType, value: unknown, exi
   }
 }
 
+export const TABULAR_FILTERS_PARAM = 'filters'
+export const TABULAR_SORT_PARAM = 'sort'
+export const TABULAR_SEARCH_PARAM = 'q'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function firstQueryValue(value: LocationQueryValue | LocationQueryValue[] | undefined): string | undefined {
+  const first = Array.isArray(value) ? value[0] : value
+  return first ?? undefined
+}
+
+/**
+ * The criteria of a column filter that actually filter something, read from any
+ * value: the ones from the URL can be anything a user typed. Empty criteria are
+ * dropped too, so that a column left with none of them has no key left.
+ */
+export function normalizeColumnFilters(value: unknown): ColumnFilters {
+  if (!isRecord(value)) return {}
+  const filter: ColumnFilters = {}
+  if (Array.isArray(value.in) && value.in.length && value.in.every(v => typeof v === 'string')) filter.in = value.in
+  if (typeof value.exact === 'string' && value.exact) filter.exact = value.exact
+  if (typeof value.min === 'number' && Number.isFinite(value.min)) filter.min = value.min
+  if (typeof value.max === 'number' && Number.isFinite(value.max)) filter.max = value.max
+  if (typeof value.contains === 'string' && value.contains) filter.contains = value.contains
+  if (value.null === 'only' || value.null === 'exclude') filter.null = value.null
+  const date = value.date
+  if (isRecord(date) && DATE_FILTER_OPERATORS.includes(date.operator as DateFilterOperator) && typeof date.start === 'string') {
+    filter.date = { operator: date.operator as DateFilterOperator, start: date.start }
+    if (typeof date.end === 'string') filter.date.end = date.end
+  }
+  return filter
+}
+
+/**
+ * The URL params holding `filters`. A column whose only criterion is the one of
+ * an alias is written under that alias; every other column goes, whole, into a
+ * single JSON param.
+ */
+export function filtersToUrlQuery(
+  filters: Record<string, ColumnFilters>,
+  aliases: Record<string, TabularUrlAlias>,
+): Record<string, string> {
+  const query: Record<string, string> = {}
+  const rest: Record<string, ColumnFilters> = {}
+  for (const [column, raw] of Object.entries(filters)) {
+    const filter = normalizeColumnFilters(raw)
+    const criteria = Object.keys(filter)
+    if (!criteria.length) continue
+    const alias = criteria.length === 1
+      ? Object.entries(aliases).find(([, a]) => a.column === column && a.operator === criteria[0])
+      : undefined
+    const aliasValue = alias && filter[alias[1].operator]
+    if (alias && aliasValue) query[alias[0]] = aliasValue
+    else rest[column] = filter
+  }
+  if (Object.keys(rest).length) query[TABULAR_FILTERS_PARAM] = JSON.stringify(rest)
+  return query
+}
+
+/**
+ * The filters a URL holds, restricted to the `columns` of the resource: the
+ * Tabular API rejects a query naming any other column, and the explorer would be
+ * left without its controls to remove it. Such a column comes from a link to a
+ * resource since re-uploaded with other columns, or from a hand-edited URL.
+ */
+export function filtersFromUrlQuery(
+  query: Record<string, LocationQueryValue | LocationQueryValue[] | undefined>,
+  aliases: Record<string, TabularUrlAlias>,
+  columns: readonly string[],
+): Record<string, ColumnFilters> {
+  const filters: Record<string, ColumnFilters> = {}
+  for (const [param, { column, operator }] of Object.entries(aliases)) {
+    const value = firstQueryValue(query[param])
+    if (value && columns.includes(column)) filters[column] = { [operator]: value }
+  }
+  const json = firstQueryValue(query[TABULAR_FILTERS_PARAM])
+  if (!json) return filters
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(json)
+  }
+  catch {
+    return filters
+  }
+  if (!isRecord(parsed)) return filters
+  for (const [column, raw] of Object.entries(parsed)) {
+    const filter = normalizeColumnFilters(raw)
+    if (Object.keys(filter).length && columns.includes(column)) filters[column] = filter
+  }
+  return filters
+}
+
+export function searchFromUrlParam(param: LocationQueryValue | LocationQueryValue[] | undefined): string {
+  return firstQueryValue(param) ?? ''
+}
+
+export function isSameSort(a: SortConfig | null | undefined, b: SortConfig | null | undefined): boolean {
+  return a?.column === b?.column && a?.direction === b?.direction
+}
+
+/**
+ * The URL param holding `sort`, in the `-column` for descending convention of
+ * the udata API. The default sort stays out of the URL; dropping it is written as
+ * an empty value, since an absent param already means "the default sort".
+ */
+export function sortToUrlParam(sort: SortConfig | null, defaultSort: SortConfig | null): string | undefined {
+  if (isSameSort(sort, defaultSort)) return undefined
+  if (!sort) return ''
+  return sort.direction === 'desc' ? `-${sort.column}` : sort.column
+}
+
+/**
+ * The sort a URL holds. One on a column the resource does not have falls back to
+ * the default sort, for the same reason as in `filtersFromUrlQuery`.
+ */
+export function sortFromUrlParam(
+  param: LocationQueryValue | LocationQueryValue[] | undefined,
+  defaultSort: SortConfig | null,
+  columns: readonly string[],
+): SortConfig | null {
+  const value = firstQueryValue(param)
+  if (value === undefined) return defaultSort
+  if (value === '') return null
+  const sort: SortConfig = value.startsWith('-')
+    ? { column: value.slice(1), direction: 'desc' }
+    : { column: value, direction: 'asc' }
+  return columns.includes(sort.column) ? sort : defaultSort
+}
+
 export type TypeDisplay = {
   icon: Component
   label: string

package/src/main.ts

@@ -24,7 +24,7 @@ import type { Weight, WellType } from './types/ui'
 import type { User, UserReference } from './types/users'
 import type { Report, ReportSubject, ReportReason } from './types/reports'
 import type { Chart, ChartForm, ChartForApi, FilterCondition, Filter, AndFilters, OrFilters, GenericFilter, XAxisType, XAxisSortBy, SortDirection, XAxis, XAxisForm, UnitPosition, YAxis, DataSeriesType, DataSeries, DataSeriesForm, CombinedSort, ColumnDefinition, ColumnsDefinition } from './types/visualizations'
-import type { ColumnFilters, ColumnType, TabularRow } from './components/TabularExplorer/types'
+import type { ColumnFilters, ColumnType, TabularRow, TabularUrlAlias } from './components/TabularExplorer/types'
 import type { GlobalSearchConfig, SearchType, SearchTypeConfig, SortOption, HiddenFilter, BuiltInFilterKey, DatasetSearchConfig, DatasetSearchFilters, DataserviceSearchConfig, DataserviceSearchFilters, ReuseSearchConfig, ReuseSearchFilters, OrganizationSearchConfig, OrganizationSearchFilters, TopicSearchConfig, TopicSearchFilters } from './types/search'
 import { getDefaultDatasetConfig, getDefaultDataserviceConfig, getDefaultReuseConfig, getDefaultOrganizationConfig, getDefaultTopicConfig, getDefaultGlobalSearchConfig, defaultDatasetSortOptions, defaultDataserviceSortOptions, defaultReuseSortOptions, defaultOrganizationSortOptions } from './types/search'
 import { useSearchFilter } from './composables/useSearchFilter'
@@ -270,6 +270,7 @@ export type {
   ColumnType,
   ColumnsDefinition,
   TabularRow,
+  TabularUrlAlias,
   FilterCondition,
   Filter,
   AndFilters,