feat: add timeline chart

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/useSettings.ts

@@ -50,6 +50,9 @@ export interface AppSettings {
     anomaliesFixed: boolean
     predictionPoints: number
   }
+  timelineChart: {
+    isZeroBased: boolean
+  }
 }
 
 const DEFAULT_SETTINGS: AppSettings = {
@@ -77,6 +80,9 @@ const DEFAULT_SETTINGS: AppSettings = {
     anomaliesFixed: true,
     predictionPoints: 4,
   },
+  timelineChart: {
+    isZeroBased: 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'
 
@@ -143,13 +144,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 +302,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,6 +321,14 @@ useSeoMeta({
       page="timeline"
     />
 
+    <div class="sticky top-24 z-10 bg-bg mt-8">
+      <div class="container w-full">
+        <div class="mx-auto">
+          <PackageTimelineChart :sizeCache :versionSubEvents :timelineEntries :selectedVersion />
+        </div>
+      </div>
+    </div>
+
     <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">
@@ -346,6 +350,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>

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

@@ -587,7 +587,16 @@
       "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",
+        "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

@@ -575,7 +575,16 @@
       "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",
+        "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})",

i18n/schema.json

@@ -1767,6 +1767,33 @@
             },
             "provenance_removed": {
               "type": "string"
+            },
+            "chart": {
+              "type": "object",
+              "properties": {
+                "tab_aria_label": {
+                  "type": "string"
+                },
+                "base_scale": {
+                  "type": "string"
+                },
+                "copy_alt": {
+                  "type": "object",
+                  "properties": {
+                    "key_changes": {
+                      "type": "string"
+                    },
+                    "version_events": {
+                      "type": "string"
+                    },
+                    "general_description": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "additionalProperties": false
             }
           },
           "additionalProperties": false

server/api/registry/timeline/[...pkg].get.ts

@@ -18,6 +18,13 @@ export interface TimelineResponse {
   total: number
 }
 
+export interface SubEvent {
+  key: string
+  positive: boolean
+  icon: string
+  text: string
+}
+
 /**
  * Returns paginated version timeline data for a package.
  *

test/nuxt/a11y.spec.ts

@@ -268,6 +268,7 @@ import SearchProviderToggleServer from '~/components/SearchProviderToggle.server
 import PackageTrendsChart from '~/components/Package/TrendsChart.vue'
 import FacetBarChart from '~/components/Compare/FacetBarChart.vue'
 import FacetScatterChart from '~/components/Compare/FacetScatterChart.vue'
+import PackageTimelineChart from '~/components/Package/TimelineChart.vue'
 import PackageLikeCard from '~/components/Package/LikeCard.vue'
 import SizeIncrease from '~/components/Package/SizeIncrease.vue'
 import SizeDecrease from '~/components/Package/SizeDecrease.vue'
@@ -1000,6 +1001,21 @@ describe('component accessibility audits', () => {
       expect(results.violations).toEqual([])
     })
 
+    describe('PackageTimelineChart', () => {
+      it('should have no accessibility violations', async () => {
+        const wrapper = await mountSuspended(PackageTimelineChart, {
+          props: {
+            sizeCache: new Map(),
+            versionSubEvents: new Map(),
+            timelineEntries: [],
+            selectedVersion: null,
+          },
+        })
+        const results = await runAxe(wrapper)
+        expect(results.violations).toEqual([])
+      })
+    })
+
     describe('FacetBarChart', () => {
       it('should have no accessibility violations', async () => {
         const wrapper = await mountSuspended(FacetBarChart, {