Improve chart tooltips

app/components/Package/TrendsChart.vue

@@ -25,6 +25,7 @@ import {
 } from '~/utils/chart-data-prediction'
 import { applyBlocklistCorrection, getAnomaliesForPackages } from '~/utils/download-anomalies'
 import { copyAltTextForTrendLineChart, sanitise, loadFile, applyEllipsis } from '~/utils/charts'
+import { useChartTooltipPosition } from '~/composables/useChartTooltipPosition'
 
 import('vue-data-ui/style.css')
 
@@ -71,6 +72,8 @@ function setIsZoom({ isZoom }: { isZoom: boolean }) {
   isZoomed.value = isZoom
 }
 
+const chartRef = useTemplateRef('chartRef')
+
 const { width } = useElementSize(rootEl)
 
 const compactNumberFormatter = useCompactNumberFormatter()
@@ -1385,6 +1388,8 @@ watch(
   { immediate: true },
 )
 
+const tooltipPosition = useChartTooltipPosition(chartRef)
+
 // VueUiXy chart component configuration
 const chartConfig = computed<VueUiXyConfig>(() => {
   return {
@@ -1518,6 +1523,9 @@ const chartConfig = computed<VueUiXyConfig>(() => {
       legend: { show: false, position: 'top' },
       tooltip: {
         teleportTo: props.inModal ? '#chart-modal' : undefined,
+        position: tooltipPosition.value,
+        offsetX: 24,
+        offsetY: isMultiPackageMode.value ? undefined : -24,
         borderColor: 'transparent',
         backdropFilter: false,
         backgroundColor: 'transparent',
@@ -1930,6 +1938,7 @@ const isSparklineLayout = computed({
           :aria-labelledby="isMultiPackageMode ? 'combined-chart-layout-tab' : undefined"
         >
           <VueUiXy
+            ref="chartRef"
             :dataset="normalisedDataset"
             :config="chartConfig"
             :class="{

app/components/SkeletonBlock.vue

@@ -1,3 +1,3 @@
 <template>
-  <div class="bg-bg-elevated rounded animate-skeleton-pulse" />
+  <div class="bg-bg-elevated rounded animate-skeleton-pulse"><slot /></div>
 </template>

app/components/Tab/Item.vue

@@ -8,10 +8,12 @@ const props = withDefaults(
     value: string
     icon?: IconClass
     tabId?: string
+    controlsPanel?: boolean
     variant?: 'primary' | 'secondary'
     size?: 'sm' | 'md'
   }>(),
   {
+    controlsPanel: true,
     variant: 'secondary',
     size: 'md',
   },
@@ -22,12 +24,13 @@ const attrs = useAttrs()
 const selected = inject<WritableComputedRef<string>>('tabs-selected')
 const getTabId = inject<(value: string) => string>('tabs-tab-id')
 const getPanelId = inject<(value: string) => string>('tabs-panel-id')
+
 if (!selected || !getTabId || !getPanelId) {
   throw new Error('TabItem must be used inside a TabRoot component')
 }
 const isSelected = computed(() => selected.value === props.value)
 const resolvedTabId = computed(() => props.tabId ?? getTabId(props.value))
-const resolvedPanelId = computed(() => getPanelId(props.value))
+const resolvedPanelId = computed(() => (props.controlsPanel ? getPanelId(props.value) : undefined))
 const select = () => {
   selected.value = props.value
 }

app/composables/useChartTooltipPosition.ts

@@ -0,0 +1,26 @@
+/**
+ * This composable returns a dynamic position to be fed to vue-data-ui components configugration for the `tooltip.position` attribute. Use it to position tooltips to the right or left side to free the view for datapoints, typically on line charts.
+ */
+
+import { useMouseInElement } from '@vueuse/core'
+
+type TooltipPosition = 'left' | 'right' | 'center'
+type TemplateRefValue = HTMLElement | { $el?: HTMLElement } | null | undefined
+
+export function useChartTooltipPosition(
+  chartRef: MaybeRefOrGetter<TemplateRefValue>,
+): ComputedRef<TooltipPosition> {
+  const target = computed<HTMLElement | null>(() => {
+    const value = toValue(chartRef)
+    if (!value) return null
+    if (value instanceof HTMLElement) return value
+    return value.$el || null
+  })
+
+  const { elementX, elementWidth, isOutside } = useMouseInElement(target)
+
+  return computed<TooltipPosition>(() => {
+    if (isOutside.value || elementWidth.value === 0) return 'center'
+    return elementX.value > elementWidth.value / 2 ? 'left' : 'right'
+  })
+}

app/composables/useSettings.ts

@@ -50,6 +50,10 @@ export interface AppSettings {
     anomaliesFixed: boolean
     predictionPoints: number
   }
+  timelineChart: {
+    isZeroBased: boolean
+    showZoom: boolean
+  }
 }
 
 const DEFAULT_SETTINGS: AppSettings = {
@@ -77,6 +81,10 @@ const DEFAULT_SETTINGS: AppSettings = {
     anomaliesFixed: true,
     predictionPoints: 4,
   },
+  timelineChart: {
+    isZeroBased: false,
+    showZoom: false,
+  },
 }
 
 const STORAGE_KEY = 'npmx-settings'

app/pages/package-timeline/[[org]]/[packageName].vue

@@ -4,6 +4,7 @@ import { compare } from 'semver'
 import type {
   TimelineResponse,
   TimelineVersion,
+  SubEvent,
 } from '~~/server/api/registry/timeline/[...pkg].get'
 import type { TimelineSizeResponse } from '~~/server/api/registry/timeline/sizes/[...pkg].get'
 
@@ -111,14 +112,17 @@ function sizeKey(ver: string) {
 }
 
 async function fetchSizes(offset: number) {
+  const requestedPackage = packageName.value
   sizeFetchesInFlight.value++
   try {
     const data = await $fetch<TimelineSizeResponse>(
-      `/api/registry/timeline/sizes/${packageName.value}`,
+      `/api/registry/timeline/sizes/${requestedPackage}`,
       { query: { offset, limit: PAGE_SIZE } },
     )
+    if (requestedPackage !== packageName.value) return
+
     for (const entry of data.sizes) {
-      sizeCache.set(sizeKey(entry.version), {
+      sizeCache.set(`${requestedPackage}@${entry.version}`, {
         totalSize: entry.totalSize,
         dependencyCount: entry.dependencyCount,
       })
@@ -143,13 +147,6 @@ if (import.meta.client) {
 
 const bytesFormatter = useBytesFormatter()
 
-interface SubEvent {
-  key: string
-  positive: boolean
-  icon: string
-  text: string
-}
-
 // Detect notable changes between consecutive versions (size, license, ESM, types)
 // Versions are compared against their semver predecessor, not chronological neighbor,
 // so interleaved legacy releases don't produce misleading cross-line diffs.
@@ -308,6 +305,8 @@ const versionSubEvents = computed(() => {
   return result
 })
 
+const selectedVersion = shallowRef<string | null>(null)
+
 useSeoMeta({
   title: () => `Timeline - ${packageName.value} - npmx`,
   description: () => `Version timeline for ${packageName.value}`,
@@ -325,12 +324,21 @@ useSeoMeta({
       page="timeline"
     />
 
-    <div class="container w-full py-8">
-      <!-- Sizes loading indicator -->
-      <div v-if="sizesLoading" class="h-0.5 mb-4 rounded-full bg-bg-muted overflow-hidden">
-        <div class="h-full w-1/3 bg-accent rounded-full animate-indeterminate" />
+    <div class="sticky top-24 z-1 bg-bg mt-8">
+      <div class="container w-full">
+        <div class="mx-auto">
+          <PackageTimelineChart
+            :sizeCache
+            :versionSubEvents
+            :timelineEntries
+            :selectedVersion
+            :loading="sizesLoading"
+          />
+        </div>
       </div>
+    </div>
 
+    <div class="container w-full py-8">
       <!-- Timeline -->
       <ol v-if="timelineEntries.length" class="relative border-s border-border ms-4">
         <li v-for="entry in timelineEntries" :key="entry.version" class="mb-6 ms-6">
@@ -346,6 +354,10 @@ useSeoMeta({
               class="text-sm font-medium"
               :class="entry.version === version ? 'text-accent' : ''"
               dir="ltr"
+              @mouseenter="selectedVersion = entry.version"
+              @mouseleave="selectedVersion = null"
+              @focus="selectedVersion = entry.version"
+              @blur="selectedVersion = null"
             >
               {{ entry.version }}
             </LinkBase>
@@ -427,18 +439,3 @@ useSeoMeta({
     </div>
   </main>
 </template>
-
-<style scoped>
-@keyframes indeterminate {
-  0% {
-    translate: -100%;
-  }
-  100% {
-    translate: 400%;
-  }
-}
-
-.animate-indeterminate {
-  animation: indeterminate 1.5s ease-in-out infinite;
-}
-</style>

app/utils/charts.ts

@@ -9,6 +9,7 @@ import type {
   VueUiXyDatasetLineItem,
 } from 'vue-data-ui'
 import type { ChartTimeGranularity } from '~/types/chart'
+import type { SubEvent } from '~~/server/api/registry/timeline/[...pkg].get'
 
 export function sum(numbers: number[]): number {
   return numbers.reduce((a, b) => a + b, 0)
@@ -451,6 +452,37 @@ export type FacetBarChartConfig = VueUiHorizontalBarConfig & {
   $t: TrendTranslateFunction
 }
 
+export type TimelineSizeCacheValue = {
+  totalSize: number
+  dependencyCount: number
+}
+
+export type ConvertedTimelineSizeCacheEntry = TimelineSizeCacheValue & {
+  name: string
+}
+
+export type EnrichedTimelineSizeCacheEntry = ConvertedTimelineSizeCacheEntry & {
+  version: string
+  time?: string
+  license?: string
+  type?: string
+  hasTypes?: boolean
+  hasTrustedPublisher?: boolean
+  hasProvenance?: boolean
+  tags: string[]
+  events: SubEvent[]
+  hasPositive: boolean
+  hasNegative: boolean
+}
+
+export type TimelineChartConfig = VueUiXyConfig & {
+  metric: 'totalSize' | 'dependencyCount'
+  packageName: string
+  copy: (text: string) => Promise<void>
+  $t: TrendTranslateFunction
+  numberFormatter: (value: number) => string
+}
+
 // Used for TrendsChart.vue
 export function createAltTextForTrendLineChart({
   dataset,
@@ -705,6 +737,68 @@ export async function copyAltTextForCompareScatterChart({
   await config.copy(altText)
 }
 
+// Used for TimelineChart.vue
+export function createAltTextForTimelineChart({
+  dataset,
+  config,
+}: AltCopyArgs<EnrichedTimelineSizeCacheEntry[], TimelineChartConfig>) {
+  if (!dataset) return ''
+  const metric =
+    config.metric === 'totalSize'
+      ? config.$t('package.stats.install_size')
+      : config.$t('compare.dependencies')
+  const withEvents = dataset.filter(d => d.events.length)
+  const first = dataset[0]
+  const last = dataset.at(-1)
+
+  if (!first || !last) return ''
+
+  const firstValue = config.metric === 'totalSize' ? first?.totalSize : first?.dependencyCount
+  const lastValue = config.metric === 'totalSize' ? last?.totalSize : last?.dependencyCount
+  const baseline = firstValue ?? 0
+  const current = lastValue ?? baseline
+  const overall_progress_percentage =
+    baseline > 0 ? Math.round(((current - baseline) / baseline) * 100) : 0
+
+  const version_events = withEvents
+    .map(item =>
+      config.$t('package.timeline.chart.copy_alt.version_events', {
+        version: item.version,
+        // eslint-disable-next-line @intlify/vue-i18n/no-dynamic-keys
+        events: item.events.map(e => config.$t(e.text).toLocaleLowerCase()).join(', '),
+      }),
+    )
+    .join('; ')
+
+  const key_changes = !withEvents.length
+    ? ''
+    : config.$t('package.timeline.chart.copy_alt.key_changes', {
+        version_events,
+      })
+
+  const altText = config.$t('package.timeline.chart.copy_alt.general_description', {
+    metric: metric.toLocaleLowerCase(),
+    package: config.packageName,
+    first: first?.version ?? '',
+    last: last?.version ?? '',
+    first_value: config.numberFormatter(firstValue ?? 0),
+    last_value: config.numberFormatter(lastValue ?? 0),
+    overall_progress_percentage,
+    key_changes,
+    watermark: config.$t('package.trends.copy_alt.watermark'),
+  })
+
+  return altText
+}
+
+export async function copyAltTextForTimelineChart({
+  dataset,
+  config,
+}: AltCopyArgs<EnrichedTimelineSizeCacheEntry[], TimelineChartConfig>) {
+  const altText = createAltTextForTimelineChart({ dataset, config })
+  await config.copy(altText)
+}
+
 // Used in chart context menu callbacks
 // @todo replace with downloadFileLink
 export function loadFile(link: string, filename: string) {

i18n/locales/en.json

@@ -591,7 +591,18 @@
       "trusted_publisher_added": "Trusted publishing enabled",
       "trusted_publisher_removed": "Trusted publishing removed",
       "provenance_added": "Provenance enabled",
-      "provenance_removed": "Provenance removed"
+      "provenance_removed": "Provenance removed",
+      "chart": {
+        "tab_aria_label": "Metric selection",
+        "base_scale": "start y-axis at zero",
+        "zoom": "zoom",
+        "reset_minimap": "reset minimap",
+        "copy_alt": {
+          "key_changes": "Key changes: {version_events}.",
+          "version_events": "version {version}: {events}",
+          "general_description": "Line chart showing the {metric} of the {package} package, from version {first} to {last}. The {metric} in version {first} is {first_value}, in version {last} is {last_value} ({overall_progress_percentage}% overall). {key_changes} {watermark}."
+        }
+      }
     },
     "dependencies": {
       "title": "Dependency ({count}) | Dependencies ({count})",

i18n/locales/fr-FR.json

@@ -579,7 +579,18 @@
       "trusted_publisher_added": "Vérification ajoutée",
       "trusted_publisher_removed": "Vérification enlevée",
       "provenance_added": "Preuve de provenance ajoutée",
-      "provenance_removed": "Preuve de provenance enlevée"
+      "provenance_removed": "Preuve de provenance enlevée",
+      "chart": {
+        "tab_aria_label": "Sélection de métrique",
+        "base_scale": "positionner les ordonnées à zéro",
+        "zoom": "zoom",
+        "reset_minimap": "Réinitialiser la mini-carte",
+        "copy_alt": {
+          "key_changes": "Principaux changements: {version_events}",
+          "version_events": "version {version}: {events}",
+          "general_description": "Graphique en ligne montrant la métrique {metric} pour le paquet {package}, depuis la version {first} à {last}. La valeur de la métrique {metric} pour la version {first} est {first_value}, et {last_value} pour la version {last} ({overall_progress_percentage}% dans l'ensemble). {key_changes} {watermark}."
+        }
+      }
     },
     "dependencies": {
       "title": "Dépendances ({count})",