@datagouv/components-next 1.3.0 → 1.4.0

package/src/functions/dates.ts

@@ -2,6 +2,26 @@ import { useTranslation } from '../composables/useTranslation'
 
 const SECONDS_IN_A_DAY = 3600 * 24
 
+/**
+ * `2026`, `2026-04` and `2026-04-24` carry no time of day. `new Date()` reads them as
+ * midnight UTC, an instant they never claimed, and then converts it: a reader west of
+ * UTC gets the day before — and with it the month, and sometimes the year.
+ */
+export const PLAIN_DATE = /^(\d{4})(?:-(\d{2}))?(?:-(\d{2}))?$/
+
+/**
+ * A date value read as the day it names. A plain date is built in local time, where no
+ * conversion can move it; anything else is an instant and keeps being read as one.
+ */
+export function parseDateValue(value: Date | string | null | undefined): Date | null {
+  if (!value) return null
+  const plain = typeof value === 'string' ? value.match(PLAIN_DATE) : null
+  const date = plain
+    ? new Date(Number(plain[1]), Number(plain[2] ?? 1) - 1, Number(plain[3] ?? 1))
+    : new Date(value)
+  return isNaN(date.getTime()) ? null : date
+}
+
 export function useFormatDate() {
   const { t, locale } = useTranslation()
 
@@ -9,11 +29,9 @@ export function useFormatDate() {
     if (!date) {
       return ''
     }
-    date = new Date(date)
-    if (!('dateStyle' in options)) {
-      options.dateStyle = 'long'
-    }
-    return new Intl.DateTimeFormat(locale, options).format(date)
+    // An explicit `dateStyle: undefined` overrides the default, which is how callers ask
+    // for `year`/`month` components — `dateStyle` and those cannot be combined.
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'long', ...options }).format(new Date(date))
   }
 
   /**
@@ -77,8 +95,9 @@ export function useFormatDate() {
     dateWithoutTime.setHours(0)
     dateWithoutTime.setMinutes(0)
     dateWithoutTime.setSeconds(0)
-    const diff = Math.abs(dateWithoutTime.getTime() - today.getTime())
-    if (Math.round(diff / (SECONDS_IN_A_DAY * 30)) >= 1) {
+    // `getTime()` returns milliseconds, `SECONDS_IN_A_DAY` is in seconds
+    const diffInSeconds = Math.abs(dateWithoutTime.getTime() - today.getTime()) / 1000
+    if (diffInSeconds >= SECONDS_IN_A_DAY * 30) {
       return t('le {date}', { date: formatDate(date, options) })
     }
     return formatFromNow(date)

package/src/functions/helpers.ts

@@ -38,6 +38,21 @@ export const summarize = (val: number, fractionDigits = 0) => {
   return `${toFixedIfNotZero(val)}Y`
 }
 
+// Guards any value that ends up in an `href`: only absolute http(s) URLs are allowed.
+// Some of these URLs come from resource extras, which are freely writable by the
+// resource owner, so an unguarded value could carry a `javascript:` or `data:` scheme
+// and execute in the platform origin when a visitor clicks the link.
+export const isSafeHttpUrl = (value: unknown): value is string => {
+  if (typeof value !== 'string') return false
+  try {
+    const { protocol } = new URL(value)
+    return protocol === 'http:' || protocol === 'https:'
+  }
+  catch {
+    return false
+  }
+}
+
 export const escapeCsvValue = (value: string | number | null | undefined): string => {
   if (value === null || value === undefined || value === '') {
     return ''

package/src/functions/metrics.ts

@@ -31,49 +31,73 @@ export type ReuseMetrics = {
   visitsTotal: number
 }
 
+type MonthlyVisitsRow = { metric_month: string, monthly_visit: number }
+type MonthlyDatasetRow = MonthlyVisitsRow & { monthly_download_resource: number }
+type MonthlyOrganizationRow = {
+  metric_month: string
+  monthly_download_resource: number
+  monthly_visit_dataservice: number
+  monthly_visit_dataset: number
+  monthly_visit_reuse: number
+}
+
+type TotalVisitsRow = { visit: number }
+type TotalDatasetRow = TotalVisitsRow & { download_resource: number }
+type TotalOrganizationRow = {
+  download_resource: number
+  visit_dataservice: number
+  visit_dataset: number
+  visit_reuse: number
+}
+
+/**
+ * The metrics API is a separate service that answers over the network, so a call fails in
+ * three ways: the request itself, an error status, or a body that isn't the expected page
+ * of rows. Rejecting on the last two turns them into the same failure as the first, which
+ * callers already hand to `useAsyncData` — reading `page.data` straight would instead throw
+ * a `TypeError` a few lines later, naming a symptom rather than the service.
+ */
+async function fetchMetrics<Row>(url: string): Promise<Array<Row>> {
+  const response = await fetch(url)
+  if (!response.ok) throw new Error(`The metrics API answered ${response.status} for ${url}`)
+
+  const page: { data?: Array<Row> } = await response.json()
+  if (!Array.isArray(page?.data)) throw new Error(`The metrics API answered an unexpected body for ${url}`)
+
+  return page.data
+}
+
 /**
  * There is only one metrics API endpoint to get these 3 values.
  * The rest of the metrics aren't stored yet at the organization level
  */
 export async function getOrganizationMetrics(oid: string, metricsApi: string): Promise<OrganizationMetrics> {
   // Fetching last 12 months
-  const response = await fetch(`${metricsApi}/api/organizations/data/?organization_id__exact=${oid}&metric_month__sort=desc&page_size=12`)
-  const page = await response.json()
+  const rows = await fetchMetrics<MonthlyOrganizationRow>(`${metricsApi}/api/organizations/data/?organization_id__exact=${oid}&metric_month__sort=desc&page_size=12`)
 
   const dataservicesViews: Record<string, number> = {}
   const datasetsViews: Record<string, number> = {}
   const downloads: Record<string, number> = {}
   const reusesViews: Record<string, number> = {}
 
-  for (const { metric_month, monthly_download_resource, monthly_visit_dataservice, monthly_visit_dataset, monthly_visit_reuse } of page.data) {
+  for (const { metric_month, monthly_download_resource, monthly_visit_dataservice, monthly_visit_dataset, monthly_visit_reuse } of rows) {
     dataservicesViews[metric_month] = monthly_visit_dataservice
     datasetsViews[metric_month] = monthly_visit_dataset
     downloads[metric_month] = monthly_download_resource
     reusesViews[metric_month] = monthly_visit_reuse
   }
   // Fetching totals
-  const totalResponse = await fetch(`${metricsApi}/api/organizations_total/data/?organization_id__exact=${oid}`)
-  const totalPage = await totalResponse.json()
-
-  let dataservicesViewsTotal = 0
-  let datasetsViewsTotal = 0
-  let downloadsTotal = 0
-  let reusesViewsTotal = 0
-  if (page.data[0]) {
-    dataservicesViewsTotal = totalPage.data[0].visit_dataservice
-    datasetsViewsTotal = totalPage.data[0].visit_dataset
-    downloadsTotal = totalPage.data[0].download_resource
-    reusesViewsTotal = totalPage.data[0].visit_reuse
-  }
+  const total = (await fetchMetrics<TotalOrganizationRow>(`${metricsApi}/api/organizations_total/data/?organization_id__exact=${oid}`))[0]
+
   return {
     downloads,
-    downloadsTotal,
+    downloadsTotal: total?.download_resource ?? 0,
     reusesViews,
-    reusesViewsTotal,
+    reusesViewsTotal: total?.visit_reuse ?? 0,
     dataservicesViews,
-    dataservicesViewsTotal,
+    dataservicesViewsTotal: total?.visit_dataservice ?? 0,
     datasetsViews,
-    datasetsViewsTotal,
+    datasetsViewsTotal: total?.visit_dataset ?? 0,
   }
 }
 
@@ -89,33 +113,24 @@ export function createOrganizationMetricsUrl(datasetsViews: Record<string, numbe
 
 export async function getDatasetMetrics(datasetId: string, metricsApi: string): Promise<DatasetMetrics> {
   // Fetching last 12 months
-  const response = await fetch(`${metricsApi}/api/datasets/data/?dataset_id__exact=${datasetId}&metric_month__sort=desc&page_size=12`)
-  const page = await response.json()
+  const rows = await fetchMetrics<MonthlyDatasetRow>(`${metricsApi}/api/datasets/data/?dataset_id__exact=${datasetId}&metric_month__sort=desc&page_size=12`)
 
   const visits: Record<string, number> = {}
   const downloads: Record<string, number> = {}
 
-  for (const { metric_month, monthly_visit, monthly_download_resource } of page.data) {
+  for (const { metric_month, monthly_visit, monthly_download_resource } of rows) {
     visits[metric_month] = monthly_visit
     downloads[metric_month] = monthly_download_resource
   }
 
   // Fetching totals
-  const totalResponse = await fetch(`${metricsApi}/api/datasets_total/data/?dataset_id__exact=${datasetId}`)
-  const totalPage = await totalResponse.json()
-
-  let visitsTotal = 0
-  let downloadsTotal = 0
-  if (totalPage.data[0]) {
-    visitsTotal = totalPage.data[0].visit
-    downloadsTotal = totalPage.data[0].download_resource
-  }
+  const total = (await fetchMetrics<TotalDatasetRow>(`${metricsApi}/api/datasets_total/data/?dataset_id__exact=${datasetId}`))[0]
 
   return {
     visits,
-    visitsTotal,
+    visitsTotal: total?.visit ?? 0,
     downloads,
-    downloadsTotal,
+    downloadsTotal: total?.download_resource ?? 0,
   }
 }
 
@@ -151,52 +166,38 @@ export async function createDatasetsForOrganizationMetricsUrl(organizationId: st
 
 export async function getDataserviceMetrics(dataserviceId: string, metricsApi: string): Promise<DataserviceMetrics> {
   // Fetching last 12 months
-  const response = await fetch(`${metricsApi}/api/dataservices/data/?dataservice_id__exact=${dataserviceId}&metric_month__sort=desc&page_size=12`)
-  const page = await response.json()
+  const rows = await fetchMetrics<MonthlyVisitsRow>(`${metricsApi}/api/dataservices/data/?dataservice_id__exact=${dataserviceId}&metric_month__sort=desc&page_size=12`)
 
   const visits: Record<string, number> = {}
 
-  for (const { metric_month, monthly_visit } of page.data) {
+  for (const { metric_month, monthly_visit } of rows) {
     visits[metric_month] = monthly_visit
   }
 
   // Fetching totals
-  const totalResponse = await fetch(`${metricsApi}/api/dataservices_total/data/?dataservice_id__exact=${dataserviceId}`)
-  const totalPage = await totalResponse.json()
-
-  let visitsTotal = 0
-  if (totalPage.data[0]) {
-    visitsTotal = totalPage.data[0].visit
-  }
+  const total = (await fetchMetrics<TotalVisitsRow>(`${metricsApi}/api/dataservices_total/data/?dataservice_id__exact=${dataserviceId}`))[0]
 
   return {
     visits,
-    visitsTotal,
+    visitsTotal: total?.visit ?? 0,
   }
 }
 
 export async function getReuseMetrics(reuseId: string, metricsApi: string): Promise<ReuseMetrics> {
   // Fetching last 12 months
-  const response = await fetch(`${metricsApi}/api/reuses/data/?reuse_id__exact=${reuseId}&metric_month__sort=desc&page_size=12`)
-  const page = await response.json()
+  const rows = await fetchMetrics<MonthlyVisitsRow>(`${metricsApi}/api/reuses/data/?reuse_id__exact=${reuseId}&metric_month__sort=desc&page_size=12`)
 
   const visits: Record<string, number> = {}
 
-  for (const { metric_month, monthly_visit } of page.data) {
+  for (const { metric_month, monthly_visit } of rows) {
     visits[metric_month] = monthly_visit
   }
 
   // Fetching totals
-  const totalResponse = await fetch(`${metricsApi}/api/reuses_total/data/?reuse_id__exact=${reuseId}`)
-  const totalPage = await totalResponse.json()
-
-  let visitsTotal = 0
-  if (totalPage.data[0]) {
-    visitsTotal = totalPage.data[0].visit
-  }
+  const total = (await fetchMetrics<TotalVisitsRow>(`${metricsApi}/api/reuses_total/data/?reuse_id__exact=${reuseId}`))[0]
 
   return {
     visits,
-    visitsTotal,
+    visitsTotal: total?.visit ?? 0,
   }
 }

package/src/functions/owned.ts

@@ -19,3 +19,24 @@ export function getOwnerPage(owned: Owned): string | null {
   }
   return null // Not supposed to exist but it does...
 }
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+export function getMapAttribution(owned: Owned): string {
+  const name = getOwnerName(owned)
+  const page = getOwnerPage(owned)
+  if (!name && !page)
+    return ''
+  // The owner name is free text any user controls (organization name, or a
+  // profile's first/last name). maplibre-gl injects this attribution string
+  // into the DOM as HTML, and its own attribution sanitizer is bypassable via
+  // mutation XSS, so every interpolated value has to be escaped here.
+  return `© <a href="${escapeHtml(page ?? '')}" target="_blank">${escapeHtml(name)}</a>`
+}

package/src/functions/paginate.ts

@@ -0,0 +1,46 @@
+export const PAGES_AROUND = 3
+
+function range(size: number, startAt: number) {
+  return [...Array(size).keys()].map(i => i + startAt)
+}
+
+/**
+ * Brings whatever the caller holds as a current page back to a page that exists.
+ * The page number usually comes from a query string, so it can be anything:
+ * `?page=abc` (NaN), `?page=-5`, `?page=1.5`, or a stale link to a page far past
+ * the last one.
+ */
+export function clampPage(page: number, pageCount: number) {
+  if (!Number.isFinite(page)) {
+    return 1
+  }
+  return Math.min(Math.max(Math.trunc(page), 1), Math.max(pageCount, 1))
+}
+
+/**
+ * The middle window of the pagination: the pages around the current one, with
+ * `null` marking an ellipsis. The first and last pages are rendered by the
+ * component itself and are never part of this window.
+ */
+export function getVisiblePages(currentPage: number, pageCount: number) {
+  if (pageCount <= 2) {
+    return []
+  }
+
+  const page = clampPage(currentPage, pageCount)
+  const size = Math.min(
+    PAGES_AROUND * 2 + 1,
+    pageCount - 2, // the first and last pages are rendered outside of the window
+    PAGES_AROUND + page - 1, // don't reach below page 2
+    PAGES_AROUND + pageCount - page, // don't reach past the last page
+  )
+  const pagination: Array<number | null> = range(size, Math.max(page - PAGES_AROUND, 2))
+
+  if (!pagination.includes(2)) {
+    pagination.unshift(null)
+  }
+  if (!pagination.includes(pageCount - 1)) {
+    pagination.push(null)
+  }
+  return pagination
+}

package/src/functions/resourceCapabilities.ts

@@ -1,4 +1,35 @@
 import type { Resource, WfsMetadata, OgcLayerInfo } from '../types/resources'
+import { isSafeHttpUrl } from './helpers'
+
+const GENERATED_FORMATS = ['parquet', 'pmtiles', 'geojson']
+
+export type GeneratedFormat = {
+  url: string
+  size: number | undefined
+  format: string
+}
+
+export function getGeneratedFormats(resource: Pick<Resource, 'extras' | 'id'>, tabularApiUrl: string | undefined): GeneratedFormat[] {
+  const formats: GeneratedFormat[] = GENERATED_FORMATS.flatMap((format) => {
+    const url = resource.extras[`analysis:parsing:${format}_url`]
+    // The URL is read verbatim from owner-writable extras: drop any entry that is not
+    // a plain http(s) URL so a `javascript:`/`data:` value never reaches an href.
+    if (!isSafeHttpUrl(url)) return []
+    return [{
+      url,
+      size: resource.extras[`analysis:parsing:${format}_size`] as number | undefined,
+      format,
+    }]
+  })
+  if ('analysis:parsing:parsing_table' in resource.extras) {
+    formats.push({
+      url: `${tabularApiUrl}/api/resources/${resource.id}/data/json/`,
+      size: undefined,
+      format: 'json',
+    })
+  }
+  return formats
+}
 
 const WFS_EXPORT_FORMATS = [
   {
@@ -46,6 +77,9 @@ export function getWfsExportFormats(resource: Pick<Resource, 'extras' | 'url'>)
   const outputFormats = wfsMetadata.output_formats.map((format: string) => format.toLowerCase())
   const layer = wfsMetadata.detected_layer
   if (!layer) return []
+  // Every download URL below is built on top of `resource.url`, so its scheme is the one
+  // of `resource.url`: guard it once here rather than on each of the built URLs.
+  if (!isSafeHttpUrl(resource.url)) return []
   const formats = WFS_EXPORT_FORMATS.filter(format => outputFormats.includes(format.mimetype.toLowerCase()))
     .map(format => ({
       url: buildWfsDownloadUrl(resource.url, wfsMetadata, format, layer),

package/src/functions/resources.ts

@@ -84,6 +84,25 @@ export function getResourceFormatIcon(format: string): Component | null {
   }
 }
 
+// Badge colors for the resource icon, keyed on the same format categorization as
+// getResourceFormatIcon so tabular/geo/code/documentation stay consistent with the icon.
+export function getResourceIconColor(format?: string | null): string {
+  const icon = format ? getResourceFormatIcon(format) : null
+  switch (icon) {
+    case Table:
+      return 'bg-[#c3fad5] text-[#18753c]'
+    case RiMap2Line:
+    case RiEarthLine:
+      return 'bg-[#e6eefe] text-[#0063cb]'
+    case Code:
+      return 'bg-[#fce164] text-[#716043]'
+    case Documentation:
+      return 'bg-[#fee7fc] text-[#6e445a]'
+    default:
+      return 'bg-gray-100 text-gray-plain'
+  }
+}
+
 export function getResourceTitleId(resource: Resource) {
   return 'resource-' + resource.id + '-title'
 }
@@ -105,14 +124,29 @@ export const getResourceLabel = (type: ResourceType, count?: number) => {
       }
       return t('Fichiers principaux')
     case 'documentation':
+      if (typeof count === 'number') {
+        return t('Aucun fichier de documentation | 1 fichier de documentation | {n} fichiers de documentation', count)
+      }
       return t('Documentation')
     case 'update':
+      if (typeof count === 'number') {
+        return t('Aucune mise à jour | 1 mise à jour | {n} mises à jour', count)
+      }
       return t('Mise à jour')
     case 'api':
+      if (typeof count === 'number') {
+        return t('Aucune API | 1 API | {n} API', count)
+      }
       return t('API')
     case 'code':
+      if (typeof count === 'number') {
+        return t('Aucun fichier de code source | 1 fichier de code source | {n} fichiers de code source', count)
+      }
       return t('Code source')
     case 'other':
+      if (typeof count === 'number') {
+        return t('Aucun autre fichier | 1 autre fichier | {n} autres fichiers', count)
+      }
       return t('Autre')
   }
 }
@@ -145,6 +179,14 @@ export function getResourceExternalUrl(dataset: Dataset | DatasetV2 | Omit<Datas
   return `${dataset.page}${isCommunityResource(resource) ? '/community-resources' : ''}?resource_id=${resource.id}`
 }
 
+export function resolveResourceExternalUrl<R extends Resource | CommunityResource>(
+  dataset: Dataset | DatasetV2 | Omit<Dataset, 'resources' | 'community_resources'>,
+  resource: R,
+  override?: (resource: R) => string,
+): string {
+  return override ? override(resource) : getResourceExternalUrl(dataset, resource)
+}
+
 export function getResourceFilesize(resource: Resource): null | number {
   if (resource.filesize) return resource.filesize
   if ('analysis:content-length' in resource.extras) return resource.extras['analysis:content-length'] as number
@@ -152,6 +194,47 @@ export function getResourceFilesize(resource: Resource): null | number {
   return null
 }
 
+const IMAGE_PREVIEW_FORMATS = ['png', 'jpg', 'jpeg', 'jpe', 'gif', 'webp'] as const
+
+export function isImagePreviewFormat(format: string | undefined | null): boolean {
+  if (!format) return false
+  return IMAGE_PREVIEW_FORMATS.includes(format.toLowerCase() as typeof IMAGE_PREVIEW_FORMATS[number])
+}
+
+// Parsing errors are stored as `<step>:<message>`, where `<step>` names the
+// analysis step that failed (e.g. `pmtiles_export`, `geojson_export`).
+
+/** The analysis step that failed, or null when there is no parsing error. */
+export function getParsingErrorStep(resource: Resource): string | null {
+  const error = resource.extras['analysis:parsing:error']
+  if (typeof error !== 'string' || !error) return null
+  const [step] = error.split(':', 1)
+  return step ?? null
+}
+
+/** The parsing error message without its `<step>:` prefix, or null when there is none. */
+export function getParsingErrorMessage(resource: Resource): string | null {
+  const error = resource.extras['analysis:parsing:error']
+  if (typeof error !== 'string' || !error) return null
+  const colon = error.indexOf(':')
+  return colon === -1 ? error : error.slice(colon + 1)
+}
+
+// Geo/format export steps run *after* the tabular table has been built, so a
+// failure here (e.g. a huge geometry timing out the pmtiles export) leaves the
+// tabular data fully usable and must not disable the tabular explorer.
+const NON_TABULAR_PARSING_ERROR_STEPS = ['pmtiles_export', 'geojson_export']
+
+/**
+ * Whether the resource's parsing error prevents reading its tabular data.
+ * Only errors from the tabular parsing itself are fatal; downstream geo/format
+ * export failures are not.
+ */
+export function hasTabularParsingError(resource: Resource): boolean {
+  const step = getParsingErrorStep(resource)
+  return step !== null && !NON_TABULAR_PARSING_ERROR_STEPS.includes(step)
+}
+
 type CorsStatus = 'allowed' | 'blocked' | 'unknown'
 
 export const getResourceCorsStatus = (resource: Resource): CorsStatus => {

package/src/functions/schemas.ts

@@ -31,6 +31,33 @@ export function getSchemaVersion(schema: RegisteredSchema | null) {
   }
 }
 
+// Accents and separators must not stand between a query and a schema: people type
+// "lave linge" for « Lave-linge », or « reparabilite » without its accents
+function normalizeForSearch(value: string): string {
+  return value
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/\p{Diacritic}/gu, '')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim()
+}
+
+// The name is searched along with the title and the description: it is the identifier
+// people know and paste, such as `etalab/indice-durabilite-lave-linge`
+const searchableText = (schema: RegisteredSchema) => normalizeForSearch(`${schema.name} ${schema.title ?? ''} ${schema.description ?? ''}`)
+
+const queryTokens = (query: string) => normalizeForSearch(query).split(' ').filter(Boolean)
+
+export function schemaMatchesQuery(schema: RegisteredSchema, query: string): boolean {
+  // A query made only of punctuation holds no word to match. Callers short-circuit the
+  // empty query, so matching everything here would only ever answer that case.
+  const tokens = queryTokens(query)
+  if (!tokens.length) return false
+
+  const haystack = searchableText(schema)
+  return tokens.every(token => haystack.includes(token))
+}
+
 export function findSchemaInCatalog(catalog: Array<RegisteredSchema>, schema: Schema | null): RegisteredSchema | null {
   if (!schema) return null
   return catalog.find(registeredSchema => schema.name === registeredSchema.name) || null

package/src/functions/scroll.ts

@@ -0,0 +1,20 @@
+// Leaves room for the sticky elements sitting at the top of the viewport.
+const SCROLL_MARGIN = 100
+
+/**
+ * Bring the top of a block back into view after its content changed (paging,
+ * searching, filtering), so the reader restarts at the first result.
+ *
+ * Does nothing when the top of the block is already on screen: aligning the
+ * viewport on a block the reader is already looking at moves the page under
+ * them for no reason.
+ */
+export function scrollToBlockTop(block: HTMLElement | null | undefined) {
+  if (!block) return
+
+  const { top } = block.getBoundingClientRect()
+  if (top >= 0 && top <= window.innerHeight) return
+
+  block.style.scrollMarginTop = `${SCROLL_MARGIN}px`
+  block.scrollIntoView({ behavior: 'smooth', block: 'start' })
+}