feat(ui): community version distribution (#1245)

app/components/Package/ChartModal.vue

···
 <script setup lang="ts">
-defineProps<{
+const props = defineProps<{
   modalTitle?: string
+}>()
+
+const emit = defineEmits<{
+  (e: 'transitioned'): void
 }>()
 </script>
 
···
     :modalTitle="modalTitle ?? $t('package.trends.title')"
     id="chart-modal"
     class="h-full sm:h-min sm:border sm:border-border sm:rounded-lg shadow-xl sm:max-h-[90vh] sm:max-w-3xl"
+    @transitioned="emit('transitioned')"
   >
     <div class="font-mono text-sm">
       <slot />

app/components/Package/TrendsChart.vue

···
 import { useCssVariables } from '~/composables/useColors'
 import { OKLCH_NEUTRAL_FALLBACK, transparentizeOklch } from '~/utils/colors'
 import { getFrameworkColor, isListedFramework } from '~/utils/frameworks'
+import { drawNpmxLogoAndTaglineWatermark } from '~/composables/useChartWatermark'
 
 const props = defineProps<{
   // For single package downloads history
···
     ? (accentColorValueById.value[id] ?? colors.value.fgSubtle ?? OKLCH_NEUTRAL_FALLBACK)
     : (colors.value.fgSubtle ?? OKLCH_NEUTRAL_FALLBACK)
 })
+
+const watermarkColors = computed(() => ({
+  fg: colors.value.fg ?? OKLCH_NEUTRAL_FALLBACK,
+  bg: colors.value.bg ?? OKLCH_NEUTRAL_FALLBACK,
+  fgSubtle: colors.value.fgSubtle ?? OKLCH_NEUTRAL_FALLBACK,
+}))
 
 const mobileBreakpointWidth = 640
 const isMobile = computed(() => width.value > 0 && width.value < mobileBreakpointWidth)
···
   return seriesNames.join('\n')
 }
 
-/**
- * Build and return npmx svg logo and tagline, to be injected during PNG & SVG exports
- */
-function drawNpmxLogoAndTaglineWatermark(svg: Record<string, any>) {
-  if (!svg?.drawingArea) return ''
-  const npmxLogoWidthToHeight = 2.64
-  const npmxLogoWidth = 100
-  const npmxLogoHeight = npmxLogoWidth / npmxLogoWidthToHeight
-
-  return `
-    <svg x="${svg.drawingArea.left + svg.drawingArea.width / 2 - npmxLogoWidth / 2 - 3}" y="${svg.height - npmxLogoHeight}" width="${npmxLogoWidth}" height="${npmxLogoHeight}" viewBox="0 0 330 125" fill="none" xmlns="http://www.w3.org/2000/svg">
-      <path d="M22.848 97V85.288H34.752V97H22.848ZM56.4105 107.56L85.5945 25H93.2745L64.0905 107.56H56.4105ZM121.269 97V46.12H128.661L128.949 59.08L127.989 58.216C128.629 55.208 129.781 52.744 131.445 50.824C133.173 48.84 135.221 47.368 137.589 46.408C139.957 45.448 142.453 44.968 145.077 44.968C148.981 44.968 152.213 45.832 154.773 47.56C157.397 49.288 159.381 51.624 160.725 54.568C162.069 57.448 162.741 60.68 162.741 64.264V97H154.677V66.568C154.677 61.832 153.749 58.248 151.893 55.816C150.037 53.32 147.189 52.072 143.349 52.072C140.725 52.072 138.357 52.648 136.245 53.8C134.133 54.888 132.437 56.52 131.157 58.696C129.941 60.808 129.333 63.432 129.333 66.568V97H121.269ZM173.647 111.4V46.12H181.135L181.327 57.64L180.175 57.064C181.455 53.096 183.568 50.088 186.512 48.04C189.519 45.992 192.976 44.968 196.88 44.968C201.936 44.968 206.064 46.216 209.264 48.712C212.528 51.208 214.928 54.472 216.464 58.504C218 62.536 218.767 66.888 218.767 71.56C218.767 76.232 218 80.584 216.464 84.616C214.928 88.648 212.528 91.912 209.264 94.408C206.064 96.904 201.936 98.152 196.88 98.152C194.256 98.152 191.792 97.704 189.487 96.808C187.247 95.912 185.327 94.664 183.727 93.064C182.191 91.464 181.135 89.576 180.559 87.4L181.711 86.056V111.4H173.647ZM196.111 90.472C200.528 90.472 203.984 88.808 206.48 85.48C209.04 82.152 210.319 77.512 210.319 71.56C210.319 65.608 209.04 60.968 206.48 57.64C203.984 54.312 200.528 52.648 196.111 52.648C193.167 52.648 190.607 53.352 188.431 54.76C186.319 56.168 184.655 58.28 183.439 61.096C182.287 63.912 181.711 67.4 181.711 71.56C181.711 75.72 182.287 79.208 183.439 82.024C184.591 84.84 186.255 86.952 188.431 88.36C190.607 89.768 193.167 90.472 196.111 90.472ZM222.57 97V46.12H229.962L230.25 57.448L229.29 57.256C229.866 53.48 231.082 50.504 232.938 48.328C234.858 46.088 237.29 44.968 240.234 44.968C243.242 44.968 245.546 46.056 247.146 48.232C248.81 50.408 249.834 53.608 250.218 57.832H249.258C249.834 53.864 251.114 50.728 253.098 48.424C255.146 46.12 257.706 44.968 260.778 44.968C264.874 44.968 267.85 46.376 269.706 49.192C271.562 52.008 272.49 56.68 272.49 63.208V97H264.426V64.36C264.426 59.816 263.946 56.648 262.986 54.856C262.026 53 260.522 52.072 258.474 52.072C257.13 52.072 255.946 52.52 254.922 53.416C253.898 54.248 253.066 55.592 252.426 57.448C251.85 59.304 251.562 61.672 251.562 64.552V97H243.498V64.36C243.498 60.008 243.018 56.872 242.058 54.952C241.162 53.032 239.658 52.072 237.546 52.072C236.202 52.072 235.018 52.52 233.994 53.416C232.97 54.248 232.138 55.592 231.498 57.448C230.922 59.304 230.634 61.672 230.634 64.552V97H222.57ZM276.676 97L295.396 70.888L277.636 46.12H287.044L300.388 65.32L313.444 46.12H323.044L305.38 71.08L323.908 97H314.5L300.388 76.456L286.276 97H276.676Z" fill="${colors.value.fg}"/>
-    </svg>
-    <text
-      fill="${colors.value.fgMuted}"
-      x="${svg.drawingArea.left + svg.drawingArea.width / 2}"
-      y="${svg.height - npmxLogoHeight - 6}"
-      font-size="12"
-      text-anchor="middle"
-    >
-      ${$t('tagline')}
-    </text>
-  `
-}
-
 // VueUiXy chart component configuration
 const chartConfig = computed(() => {
   return {
···
               <!-- Inject npmx logo & tagline during SVG and PNG print -->
               <g
                 v-if="svg.isPrintingSvg || svg.isPrintingImg"
-                v-html="drawNpmxLogoAndTaglineWatermark(svg)"
+                v-html="drawNpmxLogoAndTaglineWatermark(svg, watermarkColors, $t, 'bottom')"
               />
 
               <!-- Overlay covering the chart area to hide line resizing when switching granularities recalculates VueUiXy scaleMax when estimation lines are necessary -->

app/components/Package/VersionDistribution.vue

···
+<script setup lang="ts">
+import { VueUiXy } from 'vue-data-ui/vue-ui-xy'
+import type {
+  VueUiXyDatasetItem,
+  VueUiXyDatasetBarItem,
+  VueUiXyDatapointItem,
+  MinimalCustomFormatParams,
+} from 'vue-data-ui'
+import { useElementSize } from '@vueuse/core'
+import { useCssVariables } from '~/composables/useColors'
+import { OKLCH_NEUTRAL_FALLBACK, transparentizeOklch } from '~/utils/colors'
+import {
+  drawSvgPrintLegend,
+  drawNpmxLogoAndTaglineWatermark,
+} from '~/composables/useChartWatermark'
+import TooltipApp from '~/components/Tooltip/App.vue'
+
+type TooltipParams = MinimalCustomFormatParams<VueUiXyDatapointItem[]> & {
+  bars: VueUiXyDatasetBarItem[]
+}
+
+const props = defineProps<{
+  packageName: string
+  inModal?: boolean
+}>()
+
+const { accentColors, selectedAccentColor } = useAccentColor()
+const colorMode = useColorMode()
+const resolvedMode = shallowRef<'light' | 'dark'>('light')
+const rootEl = shallowRef<HTMLElement | null>(null)
+
+onMounted(async () => {
+  rootEl.value = document.documentElement
+  resolvedMode.value = colorMode.value === 'dark' ? 'dark' : 'light'
+})
+
+const { colors } = useCssVariables(
+  ['--bg', '--fg', '--bg-subtle', '--bg-elevated', '--fg-subtle', '--border', '--border-subtle'],
+  {
+    element: rootEl,
+    watchHtmlAttributes: true,
+    watchResize: false,
+  },
+)
+
+watch(
+  () => colorMode.value,
+  value => {
+    resolvedMode.value = value === 'dark' ? 'dark' : 'light'
+  },
+  { flush: 'sync' },
+)
+
+const isDarkMode = computed(() => resolvedMode.value === 'dark')
+
+const accentColorValueById = computed<Record<string, string>>(() => {
+  const map: Record<string, string> = {}
+  for (const item of accentColors.value) {
+    map[item.id] = item.value
+  }
+  return map
+})
+
+const accent = computed(() => {
+  const id = selectedAccentColor.value
+  return id
+    ? (accentColorValueById.value[id] ?? colors.value.fgSubtle ?? OKLCH_NEUTRAL_FALLBACK)
+    : (colors.value.fgSubtle ?? OKLCH_NEUTRAL_FALLBACK)
+})
+
+const watermarkColors = computed(() => ({
+  fg: colors.value.fg ?? OKLCH_NEUTRAL_FALLBACK,
+  bg: colors.value.bg ?? OKLCH_NEUTRAL_FALLBACK,
+  fgSubtle: colors.value.fgSubtle ?? OKLCH_NEUTRAL_FALLBACK,
+}))
+
+const { width } = useElementSize(rootEl)
+const mobileBreakpointWidth = 640
+const isMobile = computed(() => width.value > 0 && width.value < mobileBreakpointWidth)
+
+const {
+  groupingMode,
+  showRecentOnly,
+  showLowUsageVersions,
+  pending,
+  error,
+  chartDataset,
+  hasData,
+} = useVersionDistribution(() => props.packageName)
+
+const compactNumberFormatter = useCompactNumberFormatter()
+
+// Show loading indicator immediately to maintain stable layout
+const showLoadingIndicator = computed(() => pending.value)
+
+const chartConfig = computed(() => {
+  return {
+    theme: isDarkMode.value ? 'dark' : 'default',
+    chart: {
+      height: isMobile.value ? 500 : 400,
+      backgroundColor: colors.value.bg,
+      padding: {
+        top: 24,
+        right: 24,
+        bottom: xAxisLabels.value.length > 10 ? 100 : 88, // Space for rotated labels + watermark
+        left: isMobile.value ? 60 : 80,
+      },
+      userOptions: {
+        buttons: {
+          pdf: false,
+          labels: false,
+          fullscreen: false,
+          table: false,
+          tooltip: false,
+        },
+      },
+      grid: {
+        stroke: colors.value.border,
+        labels: {
+          fontSize: isMobile.value ? 24 : 16,
+          color: pending.value ? colors.value.border : colors.value.fgSubtle,
+          axis: {
+            yLabel: 'Downloads',
+            yLabelOffsetX: 12,
+            fontSize: isMobile.value ? 32 : 24,
+          },
+          yAxis: {
+            formatter: ({ value }: { value: number }) => {
+              return compactNumberFormatter.value.format(Number.isFinite(value) ? value : 0)
+            },
+            useNiceScale: true,
+          },
+          xAxisLabels: {
+            show: xAxisLabels.value.length <= 25,
+            values: xAxisLabels.value,
+            fontSize: isMobile.value ? 16 : 14,
+            color: colors.value.fgSubtle,
+            rotation: xAxisLabels.value.length > 10 ? 45 : 0,
+          },
+        },
+      },
+      highlighter: { useLine: false },
+      legend: { show: false, position: 'top' },
+      bar: {
+        periodGap: 16,
+        innerGap: 8,
+        borderRadius: 4,
+      },
+      tooltip: {
+        teleportTo: props.inModal ? '#chart-modal' : undefined,
+        borderColor: 'transparent',
+        backdropFilter: false,
+        backgroundColor: 'transparent',
+        customFormat: (params: TooltipParams) => {
+          const { datapoint, absoluteIndex, bars } = params
+          if (!datapoint) return ''
+
+          // Use absoluteIndex to get the correct version from chartDataset
+          const index = Number(absoluteIndex)
+          if (!Number.isInteger(index) || index < 0 || index >= chartDataset.value.length) return ''
+          const chartItem = chartDataset.value[index]
+
+          if (!chartItem) return ''
+
+          const barSeries = Array.isArray(bars?.[0]?.series) ? bars[0].series : []
+          const barValue = index < barSeries.length ? barSeries[index] : undefined
+          const raw = Number(barValue ?? chartItem.downloads ?? 0)
+          const v = compactNumberFormatter.value.format(Number.isFinite(raw) ? raw : 0)
+
+          return `<div class="font-mono text-xs p-3 border border-border rounded-md bg-[var(--bg)]/10 backdrop-blur-md">
+            <div class="flex flex-col gap-2">
+              <div class="flex items-center justify-between gap-4">
+                <span class="text-3xs uppercase tracking-wide text-[var(--fg)]/70">
+                  ${chartItem.name}
+                </span>
+                <span class="text-base text-[var(--fg)] font-mono tabular-nums">
+                  ${v}
+                </span>
+              </div>
+            </div>
+          </div>`
+        },
+      },
+      zoom: {
+        maxWidth: isMobile.value ? 350 : 500,
+        highlightColor: colors.value.bgElevated,
+        minimap: {
+          show: true,
+          lineColor: '#FAFAFA',
+          selectedColor: accent.value,
+          selectedColorOpacity: 0.06,
+          frameColor: colors.value.border,
+        },
+        preview: {
+          fill: transparentizeOklch(accent.value, isDarkMode.value ? 0.95 : 0.92),
+          stroke: transparentizeOklch(accent.value, 0.5),
+          strokeWidth: 1,
+          strokeDasharray: 3,
+        },
+      },
+    },
+    table: {
+      show: false,
+    },
+  }
+})
+
+// VueUiXy expects one series with multiple values for bar charts
+const xyDataset = computed<VueUiXyDatasetItem[]>(() => {
+  if (!chartDataset.value.length) return []
+
+  return [
+    {
+      name: props.packageName,
+      series: chartDataset.value.map(item => item.downloads),
+      type: 'bar' as const,
+      color: accent.value,
+    },
+  ]
+})
+
+const xAxisLabels = computed(() => {
+  return chartDataset.value.map(item => item.name)
+})
+
+// Handle keyboard navigation for semver group toggle
+function handleGroupingKeydown(event: KeyboardEvent) {
+  if (pending.value) return
+  if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault()
+    // Toggle between major and minor
+    groupingMode.value = groupingMode.value === 'major' ? 'minor' : 'major'
+  } else if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
+    event.preventDefault()
+    // Arrow keys also toggle
+    groupingMode.value = groupingMode.value === 'major' ? 'minor' : 'major'
+  }
+}
+
+// Calculate last week date range (matches npm's "last-week" API)
+const startDate = computed(() => {
+  const today = new Date()
+  const yesterday = new Date(
+    Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate() - 1),
+  )
+  const startObj = new Date(yesterday)
+  startObj.setUTCDate(startObj.getUTCDate() - 6)
+  return startObj.toISOString().slice(0, 10)
+})
+
+const endDate = computed(() => {
+  const today = new Date()
+  const yesterday = new Date(
+    Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate() - 1),
+  )
+  return yesterday.toISOString().slice(0, 10)
+})
+</script>
+
+<template>
+  <div
+    class="w-full flex flex-col"
+    id="version-distribution"
+    :aria-busy="pending ? 'true' : 'false'"
+  >
+    <div class="w-full mb-4 flex flex-col gap-3">
+      <div class="flex flex-col sm:flex-row gap-3 sm:gap-2 sm:items-end">
+        <div class="flex flex-col gap-1 sm:shrink-0">
+          <label class="text-3xs font-mono text-fg-subtle tracking-wide uppercase">
+            {{ $t('package.versions.distribution_title') }}
+          </label>
+          <div
+            class="flex items-center bg-bg-subtle border border-border rounded-md"
+            role="group"
+            :aria-label="$t('package.versions.distribution_title')"
+            tabindex="0"
+            @keydown="handleGroupingKeydown"
+          >
+            <button
+              type="button"
+              :class="[
+                'px-4 py-1.75 font-mono text-sm transition-colors rounded-s-md',
+                groupingMode === 'major'
+                  ? 'bg-accent text-bg font-medium'
+                  : 'text-fg-subtle hover:text-fg hover:bg-bg-subtle/50',
+              ]"
+              :aria-pressed="groupingMode === 'major'"
+              :disabled="pending"
+              tabindex="-1"
+              @click="groupingMode = 'major'"
+            >
+              {{ $t('package.versions.grouping_major') }}
+            </button>
+            <button
+              type="button"
+              :class="[
+                'px-4 py-1.75 font-mono text-sm transition-colors rounded-e-md border-is border-border',
+                groupingMode === 'minor'
+                  ? 'bg-accent text-bg font-medium'
+                  : 'text-fg-subtle hover:text-fg hover:bg-bg-subtle/50',
+              ]"
+              :aria-pressed="groupingMode === 'minor'"
+              :disabled="pending"
+              tabindex="-1"
+              @click="groupingMode = 'minor'"
+            >
+              {{ $t('package.versions.grouping_minor') }}
+            </button>
+          </div>
+        </div>
+
+        <div class="grid grid-cols-2 gap-2 flex-1">
+          <TooltipApp
+            :text="$t('package.versions.date_range_tooltip')"
+            position="bottom"
+            :to="inModal ? '#chart-modal' : undefined"
+            :offset="8"
+            class="w-full"
+          >
+            <div class="flex flex-col gap-1 w-full">
+              <label
+                for="versionDistStartDate"
+                class="text-3xs font-mono text-fg-subtle tracking-wide uppercase"
+              >
+                {{ $t('package.trends.start_date') }}
+              </label>
+              <div class="relative flex items-center">
+                <span
+                  class="absolute inset-is-2 i-carbon:calendar w-4 h-4 text-fg-subtle shrink-0 pointer-events-none"
+                  aria-hidden="true"
+                />
+                <InputBase
+                  id="versionDistStartDate"
+                  :model-value="startDate"
+                  disabled
+                  type="date"
+                  class="w-full min-w-0 bg-transparent ps-7"
+                  size="medium"
+                />
+              </div>
+            </div>
+          </TooltipApp>
+
+          <TooltipApp
+            :text="$t('package.versions.date_range_tooltip')"
+            position="bottom"
+            :to="inModal ? '#chart-modal' : undefined"
+            :offset="8"
+            class="w-full"
+          >
+            <div class="flex flex-col gap-1 w-full">
+              <label
+                for="versionDistEndDate"
+                class="text-3xs font-mono text-fg-subtle tracking-wide uppercase"
+              >
+                {{ $t('package.trends.end_date') }}
+              </label>
+              <div class="relative flex items-center">
+                <span
+                  class="absolute inset-is-2 i-carbon:calendar w-4 h-4 text-fg-subtle shrink-0 pointer-events-none"
+                  aria-hidden="true"
+                />
+                <InputBase
+                  id="versionDistEndDate"
+                  :model-value="endDate"
+                  disabled
+                  type="date"
+                  class="w-full min-w-0 bg-transparent ps-7"
+                  size="medium"
+                />
+              </div>
+            </div>
+          </TooltipApp>
+        </div>
+      </div>
+
+      <div class="flex flex-col gap-4 w-full max-w-1/2">
+        <TooltipApp
+          :text="$t('package.versions.recent_versions_only_tooltip')"
+          position="bottom"
+          :to="inModal ? '#chart-modal' : undefined"
+          :offset="8"
+        >
+          <SettingsToggle
+            v-model="showRecentOnly"
+            :label="$t('package.versions.recent_versions_only')"
+            justify="start"
+            reverse-order
+            :class="pending ? 'opacity-50 pointer-events-none' : ''"
+          />
+        </TooltipApp>
+
+        <TooltipApp
+          :text="$t('package.versions.show_low_usage_tooltip')"
+          position="bottom"
+          :to="inModal ? '#chart-modal' : undefined"
+          :offset="8"
+        >
+          <SettingsToggle
+            v-model="showLowUsageVersions"
+            :label="$t('package.versions.show_low_usage')"
+            justify="start"
+            reverse-order
+            :class="pending ? 'opacity-50 pointer-events-none' : ''"
+          />
+        </TooltipApp>
+      </div>
+    </div>
+
+    <h2 id="version-distribution-title" class="sr-only">
+      {{ $t('package.versions.distribution_title') }}
+    </h2>
+
+    <div
+      role="region"
+      aria-labelledby="version-distribution-title"
+      class="relative"
+      :class="isMobile ? 'min-h-[500px]' : 'min-h-[400px]'"
+    >
+      <!-- Chart content -->
+      <ClientOnly v-if="xyDataset.length > 0 && !error">
+        <div class="chart-container w-full" :key="groupingMode">
+          <VueUiXy :dataset="xyDataset" :config="chartConfig" class="[direction:ltr]">
+            <!-- Injecting custom svg elements -->
+            <template #svg="{ svg }">
+              <!-- Inject legend during SVG print only -->
+              <g v-if="svg.isPrintingSvg" v-html="drawSvgPrintLegend(svg, watermarkColors)" />
+
+              <!-- Inject npmx logo & tagline during SVG and PNG print -->
+              <g
+                v-if="svg.isPrintingSvg || svg.isPrintingImg"
+                v-html="
+                  drawNpmxLogoAndTaglineWatermark(svg, watermarkColors, $t, 'belowDrawingArea')
+                "
+              />
+            </template>
+
+            <!-- Subtle gradient applied for area charts -->
+            <template #area-gradient="{ series: chartModalSeries, id: gradientId }">
+              <linearGradient :id="gradientId" x1="0" x2="0" y1="0" y2="1">
+                <stop offset="0%" :stop-color="chartModalSeries.color" stop-opacity="0.2" />
+                <stop offset="100%" :stop-color="colors.bg" stop-opacity="0" />
+              </linearGradient>
+            </template>
+
+            <!-- Custom legend for single series (non-interactive) -->
+            <template #legend="{ legend }">
+              <div class="flex gap-4 flex-wrap justify-center">
+                <template v-if="legend.length > 0">
+                  <div class="flex gap-1 place-items-center">
+                    <div class="h-3 w-3">
+                      <svg viewBox="0 0 2 2" class="w-full">
+                        <rect x="0" y="0" width="2" height="2" rx="0.3" :fill="legend[0]?.color" />
+                      </svg>
+                    </div>
+                    <span>
+                      {{ legend[0]?.name }}
+                    </span>
+                  </div>
+                </template>
+              </div>
+            </template>
+
+            <!-- Contextual menu icon -->
+            <template #menuIcon="{ isOpen }">
+              <span v-if="isOpen" class="i-carbon:close w-6 h-6" aria-hidden="true" />
+              <span v-else class="i-carbon:overflow-menu-vertical w-6 h-6" aria-hidden="true" />
+            </template>
+
+            <!-- Export options -->
+            <template #optionCsv>
+              <span
+                class="i-carbon:csv w-6 h-6 text-fg-subtle"
+                style="pointer-events: none"
+                aria-hidden="true"
+              />
+            </template>
+
+            <template #optionImg>
+              <span
+                class="i-carbon:png w-6 h-6 text-fg-subtle"
+                style="pointer-events: none"
+                aria-hidden="true"
+              />
+            </template>
+
+            <template #optionSvg>
+              <span
+                class="i-carbon:svg w-6 h-6 text-fg-subtle"
+                style="pointer-events: none"
+                aria-hidden="true"
+              />
+            </template>
+
+            <!-- Annotator action icons -->
+            <template #annotator-action-close>
+              <span
+                class="i-carbon:close w-6 h-6 text-fg-subtle"
+                style="pointer-events: none"
+                aria-hidden="true"
+              />
+            </template>
+
+            <template #annotator-action-color="{ color }">
+              <span class="i-carbon:color-palette w-6 h-6" :style="{ color }" aria-hidden="true" />
+            </template>
+
+            <template #annotator-action-undo>
+              <span
+                class="i-carbon:undo w-6 h-6 text-fg-subtle"
+                style="pointer-events: none"
+                aria-hidden="true"
+              />
+            </template>
+
+            <template #annotator-action-redo>
+              <span
+                class="i-carbon:redo w-6 h-6 text-fg-subtle"
+                style="pointer-events: none"
+                aria-hidden="true"
+              />
+            </template>
+
+            <template #annotator-action-delete>
+              <span
+                class="i-carbon:trash-can w-6 h-6 text-fg-subtle"
+                style="pointer-events: none"
+                aria-hidden="true"
+              />
+            </template>
+
+            <template #optionAnnotator="{ isAnnotator }">
+              <span
+                v-if="isAnnotator"
+                class="i-carbon:edit-off w-6 h-6 text-fg-subtle"
+                style="pointer-events: none"
+                aria-hidden="true"
+              />
+              <span
+                v-else
+                class="i-carbon:edit w-6 h-6 text-fg-subtle"
+                style="pointer-events: none"
+                aria-hidden="true"
+              />
+            </template>
+          </VueUiXy>
+        </div>
+
+        <template #fallback>
+          <div />
+        </template>
+      </ClientOnly>
+
+      <!-- No-data state -->
+      <div v-if="!hasData && !pending && !error" class="flex items-center justify-center h-full">
+        <div class="text-sm text-fg-subtle font-mono text-center flex flex-col items-center gap-2">
+          <span class="i-carbon:data-vis-4 w-8 h-8" />
+          <p>{{ $t('package.trends.no_data') }}</p>
+        </div>
+      </div>
+
+      <!-- Error state -->
+      <div v-if="error" class="flex items-center justify-center h-full" role="alert">
+        <div class="text-sm text-fg-subtle font-mono text-center flex flex-col items-center gap-2">
+          <span class="i-carbon:warning-hex w-8 h-8 text-red-400" />
+          <p>{{ error.message }}</p>
+          <p class="text-xs">Package: {{ packageName }}</p>
+        </div>
+      </div>
+
+      <!-- Loading indicator as true overlay -->
+      <div
+        v-if="showLoadingIndicator"
+        role="status"
+        aria-live="polite"
+        class="absolute top-1/2 inset-is-1/2 -translate-x-1/2 -translate-y-1/2"
+      >
+        <div
+          class="text-xs text-fg-subtle font-mono bg-bg/70 backdrop-blur px-3 py-2 rounded-md border border-border"
+        >
+          {{ $t('common.loading') }}
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* Disable all transitions on SVG elements to prevent repositioning animation */
+:deep(.vue-ui-xy) svg rect {
+  transition: none !important;
+}
+
+@keyframes fadeInUp {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.chart-container {
+  animation: fadeInUp 350ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+</style>
+
+<style>
+/* Override default placement of the refresh button to have it to the minimap's side */
+@media screen and (min-width: 767px) {
+  #version-distribution .vue-data-ui-refresh-button {
+    top: -0.6rem !important;
+    left: calc(100% + 2rem) !important;
+  }
+}
+</style>

app/components/Package/Versions.vue

···
   time: Record<string, string>
 }>()
 
+const chartModal = useModal('chart-modal')
+const hasDistributionModalTransitioned = shallowRef(false)
+const isDistributionModalOpen = shallowRef(false)
+let distributionModalFallbackTimer: ReturnType<typeof setTimeout> | null = null
+
+function clearDistributionModalFallbackTimer() {
+  if (distributionModalFallbackTimer) {
+    clearTimeout(distributionModalFallbackTimer)
+    distributionModalFallbackTimer = null
+  }
+}
+
+async function openDistributionModal() {
+  isDistributionModalOpen.value = true
+  hasDistributionModalTransitioned.value = false
+  // ensure the component renders before opening the dialog
+  await nextTick()
+  chartModal.open()
+
+  // Fallback: Force mount if transition event doesn't fire
+  clearDistributionModalFallbackTimer()
+  distributionModalFallbackTimer = setTimeout(() => {
+    if (!hasDistributionModalTransitioned.value) {
+      hasDistributionModalTransitioned.value = true
+    }
+  }, 500)
+}
+
+function closeDistributionModal() {
+  isDistributionModalOpen.value = false
+  hasDistributionModalTransitioned.value = false
+  clearDistributionModalFallbackTimer()
+}
+
+function handleDistributionModalTransitioned() {
+  hasDistributionModalTransitioned.value = true
+  clearDistributionModalFallbackTimer()
+}
+
 /** Maximum number of dist-tag rows to show before collapsing into "Other versions" */
 const MAX_VISIBLE_TAGS = 10
 
···
     id="versions"
   >
     <template #actions>
-      <LinkBase
-        variant="button-secondary"
-        :to="`https://majors.nullvoxpopuli.com/q?packages=${packageName}`"
+      <ButtonBase
+        variant="secondary"
+        class="text-fg-subtle hover:text-fg transition-colors duration-200 inline-flex items-center justify-center min-w-6 min-h-6 -m-1 p-1 rounded"
         :title="$t('package.downloads.community_distribution')"
         classicon="i-carbon:load-balancer-network"
+        @click="openDistributionModal"
       >
         <span class="sr-only">{{ $t('package.downloads.community_distribution') }}</span>
-      </LinkBase>
+      </ButtonBase>
     </template>
     <div class="space-y-0.5 min-w-0">
       <!-- Dist-tag rows (limited to MAX_VISIBLE_TAGS) -->
···
                   <div class="flex items-center gap-2 min-w-0">
                     <button
                       type="button"
-                      class="w-4 h-4 flex items-center justify-center text-fg-subtle hover:text-fg transition-colors shrink-0 focus-visible:outline-accent/70 rounded-sm"
+                      class="w-4 h-4 flex items-center justify-center text-fg-subtle hover:text-fg transition-colors shrink-0 rounded-sm"
                       :aria-expanded="expandedMajorGroups.has(group.groupKey)"
                       :aria-label="
                         expandedMajorGroups.has(group.groupKey)
···
       </div>
     </div>
   </CollapsibleSection>
+
+  <!-- Version Distribution Modal -->
+  <PackageChartModal
+    v-if="isDistributionModalOpen"
+    :title="$t('package.versions.distribution_modal_title')"
+    @close="closeDistributionModal"
+    @transitioned="handleDistributionModalTransitioned"
+  >
+    <!-- The Chart is mounted after the dialog has transitioned -->
+    <!-- This avoids flaky behavior and ensures proper modal lifecycle -->
+    <Transition name="opacity" mode="out-in">
+      <PackageVersionDistribution
+        v-if="hasDistributionModalTransitioned"
+        :package-name="packageName"
+        :in-modal="true"
+      />
+    </Transition>
+
+    <!-- This placeholder bears the same dimensions as the VersionDistribution component -->
+    <!-- Avoids CLS when the dialog has transitioned -->
+    <div
+      v-if="!hasDistributionModalTransitioned"
+      class="w-full aspect-[272/609] sm:aspect-[671/516]"
+    />
+  </PackageChartModal>
 </template>
+
+<style scoped>
+.opacity-enter-active,
+.opacity-leave-active {
+  transition: opacity 200ms ease;
+}
+
+.opacity-enter-from,
+.opacity-leave-to {
+  opacity: 0;
+}
+</style>

app/components/Package/WeeklyDownloadStats.vue

···
 
   <PackageChartModal
     v-if="isChartModalOpen && hasWeeklyDownloads"
+    :title="$t('package.downloads.modal_title')"
     @close="handleModalClose"
     @transitioned="handleModalTransitioned"
   >

app/components/Settings/Toggle.client.vue

···
 <script setup lang="ts">
-defineProps<{
-  label?: string
-  description?: string
-  class?: string
-}>()
+import TooltipApp from '~/components/Tooltip/App.vue'
+
+const props = withDefaults(
+  defineProps<{
+    label?: string
+    description?: string
+    class?: string
+    justify?: 'between' | 'start'
+    tooltip?: string
+    tooltipPosition?: 'top' | 'bottom' | 'left' | 'right'
+    tooltipTo?: string
+    tooltipOffset?: number
+    reverseOrder?: boolean
+  }>(),
+  {
+    justify: 'between',
+    reverseOrder: false,
+  },
+)
 
 const checked = defineModel<boolean>({
   default: false,
···
 <template>
   <button
     type="button"
-    class="w-full flex items-center justify-between gap-4 group focus-visible:outline-none py-1 -my-1"
+    class="w-full flex items-center gap-4 group focus-visible:outline-none py-1 -my-1"
+    :class="[justify === 'start' ? 'justify-start' : 'justify-between', $props.class]"
     role="switch"
     :aria-checked="checked"
     @click="checked = !checked"
-    :class="class"
   >
-    <span v-if="label" class="text-sm text-fg font-medium text-start">
-      {{ label }}
-    </span>
-    <span
-      class="inline-flex items-center h-6 w-11 shrink-0 rounded-full border p-0.25 transition-colors duration-200 shadow-sm ease-in-out motion-reduce:transition-none group-focus-visible:(outline-accent/70 outline-offset-2 outline-solid)"
-      :class="
-        checked
-          ? 'bg-accent border-accent group-hover:bg-accent/80'
-          : 'bg-fg/50 border-fg/50 group-hover:bg-fg/70'
-      "
-      aria-hidden="true"
-    >
+    <template v-if="props.reverseOrder">
+      <span
+        class="inline-flex items-center h-6 w-11 shrink-0 rounded-full border p-0.25 transition-colors duration-200 shadow-sm ease-in-out motion-reduce:transition-none group-focus-visible:(outline-accent/70 outline-offset-2 outline-solid)"
+        :class="
+          checked
+            ? 'bg-accent border-accent group-hover:bg-accent/80'
+            : 'bg-fg/50 border-fg/50 group-hover:bg-fg/70'
+        "
+        aria-hidden="true"
+      >
+        <span
+          class="block h-5 w-5 rounded-full bg-bg shadow-sm transition-transform duration-200 ease-in-out motion-reduce:transition-none"
+        />
+      </span>
+      <TooltipApp
+        v-if="tooltip && label"
+        :text="tooltip"
+        :position="tooltipPosition ?? 'top'"
+        :to="tooltipTo"
+        :offset="tooltipOffset"
+      >
+        <span class="text-sm text-fg font-medium text-start">
+          {{ label }}
+        </span>
+      </TooltipApp>
+      <span v-else-if="label" class="text-sm text-fg font-medium text-start">
+        {{ label }}
+      </span>
+    </template>
+    <template v-else>
+      <TooltipApp
+        v-if="tooltip && label"
+        :text="tooltip"
+        :position="tooltipPosition ?? 'top'"
+        :to="tooltipTo"
+        :offset="tooltipOffset"
+      >
+        <span class="text-sm text-fg font-medium text-start">
+          {{ label }}
+        </span>
+      </TooltipApp>
+      <span v-else-if="label" class="text-sm text-fg font-medium text-start">
+        {{ label }}
+      </span>
       <span
-        class="block h-5 w-5 rounded-full bg-bg shadow-sm transition-transform duration-200 ease-in-out motion-reduce:transition-none"
-      />
-    </span>
+        class="inline-flex items-center h-6 w-11 shrink-0 rounded-full border p-0.25 transition-colors duration-200 shadow-sm ease-in-out motion-reduce:transition-none group-focus-visible:(outline-accent/70 outline-offset-2 outline-solid)"
+        :class="
+          checked
+            ? 'bg-accent border-accent group-hover:bg-accent/80'
+            : 'bg-fg/50 border-fg/50 group-hover:bg-fg/70'
+        "
+        aria-hidden="true"
+      >
+        <span
+          class="block h-5 w-5 rounded-full bg-bg shadow-sm transition-transform duration-200 ease-in-out motion-reduce:transition-none"
+        />
+      </span>
+    </template>
   </button>
   <p v-if="description" class="text-sm text-fg-muted mt-2">
     {{ description }}
···
 </template>
 
 <style scoped>
+/* Default order: label first, toggle last */
 button[aria-checked='false'] > span:last-of-type > span {
   translate: 0;
 }
···
   translate: calc(-100%);
 }
 
+/* Reverse order: toggle first, label last */
+button[aria-checked='false'] > span:first-of-type > span {
+  translate: 0;
+}
+button[aria-checked='true'] > span:first-of-type > span {
+  translate: calc(100%);
+}
+html[dir='rtl'] button[aria-checked='true'] > span:first-of-type > span {
+  translate: calc(-100%);
+}
+
 @media (forced-colors: active) {
   /* make toggle tracks and thumb visible in forced colors. */
   button[role='switch'] {
-    & > span:last-of-type {
+    & > span:last-of-type,
+    & > span:first-of-type {
       forced-color-adjust: none;
     }
 
-    &[aria-checked='false'] > span:last-of-type {
+    &[aria-checked='false'] > span:last-of-type,
+    &[aria-checked='false'] > span:first-of-type {
       background: Canvas;
       border-color: CanvasText;
 
···
       }
     }
 
-    &[aria-checked='true'] > span:last-of-type {
+    &[aria-checked='true'] > span:last-of-type,
+    &[aria-checked='true'] > span:first-of-type {
       background: Highlight;
       border-color: Highlight;
 

app/components/Tooltip/App.vue

···
   interactive?: boolean
   /** Teleport target for the tooltip content (defaults to 'body') */
   to?: string | HTMLElement
+  /** Offset distance in pixels (default: 4) */
+  offset?: number
 }>()
 
 const isVisible = shallowRef(false)
···
     :isVisible
     :position
     :interactive
+    :to
+    :offset
     :tooltip-attr="tooltipAttrs"
-    :to="props.to"
     @mouseenter="show"
     @mouseleave="hide"
     @focusin="show"

app/components/Tooltip/Base.vue

···
     tooltipAttr?: HTMLAttributes
     /** Teleport target for the tooltip content (defaults to 'body') */
     to?: string | HTMLElement
+    /** Offset distance in pixels (default: 4) */
+    offset?: number
     /** Strategy for the tooltip - prefer fixed for sticky containers (defaults to 'absolute') */
     strategy?: Strategy
   }>(),
   {
     to: 'body',
+    offset: 4,
     strategy: 'absolute',
   },
 )
···
   placement,
   whileElementsMounted: autoUpdate,
   strategy: props.strategy,
-  middleware: [offset(4), flip(), shift({ padding: 8 })],
+  middleware: [offset(props.offset), flip(), shift({ padding: 8 })],
 })
 </script>
 

app/composables/useChartWatermark.ts

···
+/**
+ * Shared utilities for chart watermarks and legends in SVG/PNG exports
+ */
+
+interface WatermarkColors {
+  fg: string
+  bg: string
+  fgSubtle: string
+}
+
+/**
+ * Build and return legend as SVG for export
+ * Legend items are displayed in a column, on the top left of the chart.
+ */
+export function drawSvgPrintLegend(svg: Record<string, any>, colors: WatermarkColors) {
+  const data = Array.isArray(svg?.data) ? svg.data : []
+  if (!data.length) return ''
+
+  const seriesNames: string[] = []
+
+  data.forEach((serie, index) => {
+    seriesNames.push(`
+      <rect
+        x="${svg.drawingArea.left + 12}"
+        y="${svg.drawingArea.top + 24 * index - 7}"
+        width="12"
+        height="12"
+        fill="${serie.color}"
+        rx="3"
+      />
+      <text
+        text-anchor="start"
+        dominant-baseline="middle"
+        x="${svg.drawingArea.left + 32}"
+        y="${svg.drawingArea.top + 24 * index}"
+        font-size="16"
+        fill="${colors.fg}"
+        stroke="${colors.bg}"
+        stroke-width="1"
+        paint-order="stroke fill"
+      >
+        ${serie.name}
+      </text>
+  `)
+  })
+
+  return seriesNames.join('')
+}
+
+/**
+ * Build and return npmx svg logo and tagline, to be injected during PNG & SVG exports
+ */
+export function drawNpmxLogoAndTaglineWatermark(
+  svg: Record<string, any>,
+  colors: WatermarkColors,
+  translateFn: (key: string) => string,
+  positioning: 'bottom' | 'belowDrawingArea' = 'bottom',
+) {
+  if (!svg?.drawingArea) return ''
+  const npmxLogoWidthToHeight = 2.64
+  const npmxLogoWidth = 100
+  const npmxLogoHeight = npmxLogoWidth / npmxLogoWidthToHeight
+
+  // Position watermark based on the positioning strategy
+  const watermarkY =
+    positioning === 'belowDrawingArea'
+      ? svg.drawingArea.top + svg.drawingArea.height + 48
+      : svg.height - npmxLogoHeight
+
+  const taglineY =
+    positioning === 'belowDrawingArea' ? watermarkY - 6 : svg.height - npmxLogoHeight - 6
+
+  // Center the watermark horizontally relative to the full SVG width
+  const watermarkX = svg.width / 2 - npmxLogoWidth / 2
+
+  return `
+    <svg x="${watermarkX}" y="${watermarkY}" width="${npmxLogoWidth}" height="${npmxLogoHeight}" viewBox="0 0 330 125" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <path d="M22.848 97V85.288H34.752V97H22.848ZM56.4105 107.56L85.5945 25H93.2745L64.0905 107.56H56.4105ZM121.269 97V46.12H128.661L128.949 59.08L127.989 58.216C128.629 55.208 129.781 52.744 131.445 50.824C133.173 48.84 135.221 47.368 137.589 46.408C139.957 45.448 142.453 44.968 145.077 44.968C148.981 44.968 152.213 45.832 154.773 47.56C157.397 49.288 159.381 51.624 160.725 54.568C162.069 57.448 162.741 60.68 162.741 64.264V97H154.677V66.568C154.677 61.832 153.749 58.248 151.893 55.816C150.037 53.32 147.189 52.072 143.349 52.072C140.725 52.072 138.357 52.648 136.245 53.8C134.133 54.888 132.437 56.52 131.157 58.696C129.941 60.808 129.333 63.432 129.333 66.568V97H121.269ZM173.647 111.4V46.12H181.135L181.327 57.64L180.175 57.064C181.455 53.096 183.568 50.088 186.512 48.04C189.519 45.992 192.976 44.968 196.88 44.968C201.936 44.968 206.064 46.216 209.264 48.712C212.528 51.208 214.928 54.472 216.464 58.504C218 62.536 218.767 66.888 218.767 71.56C218.767 76.232 218 80.584 216.464 84.616C214.928 88.648 212.528 91.912 209.264 94.408C206.064 96.904 201.936 98.152 196.88 98.152C194.256 98.152 191.792 97.704 189.487 96.808C187.247 95.912 185.327 94.664 183.727 93.064C182.191 91.464 181.135 89.576 180.559 87.4L181.711 86.056V111.4H173.647ZM196.111 90.472C200.528 90.472 203.984 88.808 206.48 85.48C209.04 82.152 210.319 77.512 210.319 71.56C210.319 65.608 209.04 60.968 206.48 57.64C203.984 54.312 200.528 52.648 196.111 52.648C193.167 52.648 190.607 53.352 188.431 54.76C186.319 56.168 184.655 58.28 183.439 61.096C182.287 63.912 181.711 67.4 181.711 71.56C181.711 75.72 182.287 79.208 183.439 82.024C184.591 84.84 186.255 86.952 188.431 88.36C190.607 89.768 193.167 90.472 196.111 90.472ZM222.57 97V46.12H229.962L230.25 57.448L229.29 57.256C229.866 53.48 231.082 50.504 232.938 48.328C234.858 46.088 237.29 44.968 240.234 44.968C243.242 44.968 245.546 46.056 247.146 48.232C248.81 50.408 249.834 53.608 250.218 57.832H249.258C249.834 53.864 251.114 50.728 253.098 48.424C255.146 46.12 257.706 44.968 260.778 44.968C264.874 44.968 267.85 46.376 269.706 49.192C271.562 52.008 272.49 56.68 272.49 63.208V97H264.426V64.36C264.426 59.816 263.946 56.648 262.986 54.856C262.026 53 260.522 52.072 258.474 52.072C257.13 52.072 255.946 52.52 254.922 53.416C253.898 54.248 253.066 55.592 252.426 57.448C251.85 59.304 251.562 61.672 251.562 64.552V97H243.498V64.36C243.498 60.008 243.018 56.872 242.058 54.952C241.162 53.032 239.658 52.072 237.546 52.072C236.202 52.072 235.018 52.52 233.994 53.416C232.97 54.248 232.138 55.592 231.498 57.448C230.922 59.304 230.634 61.672 230.634 64.552V97H222.57ZM276.676 97L295.396 70.888L277.636 46.12H287.044L300.388 65.32L313.444 46.12H323.044L305.38 71.08L323.908 97H314.5L300.388 76.456L286.276 97H276.676Z" fill="${colors.fg}"/>
+    </svg>
+    <text
+      fill="${colors.fgSubtle}"
+      x="${svg.width / 2}"
+      y="${taglineY}"
+      font-size="12"
+      text-anchor="middle"
+    >
+      ${translateFn('tagline')}
+    </text>
+  `
+}

app/composables/useVersionDistribution.ts

···
+import type { MaybeRefOrGetter } from 'vue'
+import { toValue } from 'vue'
+import type {
+  VersionDistributionResponse,
+  VersionGroupDownloads,
+  VersionGroupingMode,
+} from '#shared/types/version-downloads'
+
+interface ChartDataItem {
+  name: string
+  downloads: number
+}
+
+/**
+ * Composable for managing version download distribution data and state.
+ *
+ * Fetches version download statistics from the API, manages grouping/filtering state,
+ * and formats data for chart visualization.
+ *
+ * @param packageName - The package name to fetch version downloads for
+ * @returns Reactive state and computed chart data
+ */
+export function useVersionDistribution(packageName: MaybeRefOrGetter<string>) {
+  const groupingMode = ref<VersionGroupingMode>('major')
+  const showRecentOnly = ref(false)
+  const showLowUsageVersions = ref(false)
+  const pending = ref(false)
+  const error = ref<Error | null>(null)
+  const data = ref<VersionDistributionResponse | null>(null)
+
+  /**
+   * Fetches version download distribution from the API
+   */
+  async function fetchDistribution() {
+    const pkgName = toValue(packageName)
+    if (!pkgName) {
+      data.value = null
+      return
+    }
+
+    pending.value = true
+    error.value = null
+
+    try {
+      const mode = groupingMode.value
+      const response = await $fetch<VersionDistributionResponse>(
+        `/api/registry/downloads/${encodeURIComponent(pkgName)}/versions`,
+        {
+          query: {
+            mode,
+            filterOldVersions: showRecentOnly.value ? 'true' : 'false',
+            filterThreshold: showLowUsageVersions.value ? '0' : '1',
+          },
+          cache: 'default', // Don't force-cache since query params change frequently
+        },
+      )
+
+      data.value = response
+    } catch (err) {
+      error.value = err instanceof Error ? err : new Error('Failed to fetch version distribution')
+      data.value = null
+    } finally {
+      pending.value = false
+    }
+  }
+
+  /**
+   * Applies filtering to version groups based on current filter settings
+   * Sorts groups from oldest to newest version
+   */
+  const filteredGroups = computed<VersionGroupDownloads[]>(() => {
+    if (!data.value) return []
+
+    let groups = data.value.groups
+
+    // Filter using server-provided recent versions list
+    if (showRecentOnly.value && data.value.recentVersions) {
+      const recentVersionsSet = new Set(data.value.recentVersions)
+
+      groups = groups.filter(group => {
+        return group.versions.some(v => {
+          // Check exact version match
+          if (recentVersionsSet.has(v.version)) return true
+
+          // Also check base version (strip prerelease suffix)
+          if (v.version.includes('-')) {
+            const baseVersion = v.version.split('-')[0]
+            if (baseVersion && recentVersionsSet.has(baseVersion)) return true
+          }
+
+          return false
+        })
+      })
+    }
+
+    // Sort groups from oldest to newest by parsing version numbers
+    return groups.slice().sort((a, b) => {
+      // Extract version numbers from groupKey (e.g., "1.x" or "1.2.x")
+      const aParts = a.groupKey.replace(/\.x$/, '').split('.').map(Number)
+      const bParts = b.groupKey.replace(/\.x$/, '').split('.').map(Number)
+
+      for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+        const aPart = aParts[i] ?? 0
+        const bPart = bParts[i] ?? 0
+        if (aPart !== bPart) {
+          return aPart - bPart
+        }
+      }
+      return 0
+    })
+  })
+
+  const chartDataset = computed<ChartDataItem[]>(() => {
+    const groups = filteredGroups.value
+    if (!groups.length) return []
+
+    return groups.map(group => ({
+      name: group.label,
+      downloads: group.downloads,
+    }))
+  })
+
+  const totalDownloads = computed(() => {
+    const groups = filteredGroups.value
+    if (!groups || !groups.length) return 0
+    return groups.reduce((sum, group) => sum + group.downloads, 0)
+  })
+
+  const hasData = computed(() => {
+    return data.value !== null && filteredGroups.value.length > 0
+  })
+
+  // Refetch when filter changes - no immediate since we already have data
+  watch(showRecentOnly, () => {
+    fetchDistribution()
+  })
+
+  watch(showLowUsageVersions, () => {
+    fetchDistribution()
+  })
+
+  // Refetch when grouping mode changes - immediate to load initial data
+  watch(
+    groupingMode,
+    () => {
+      fetchDistribution()
+    },
+    { immediate: true },
+  )
+
+  // Refetch when package name changes - not immediate since parent component controls initialization
+  watch(
+    () => toValue(packageName),
+    () => {
+      fetchDistribution()
+    },
+    { immediate: false },
+  )
+
+  return {
+    // State
+    groupingMode,
+    showRecentOnly,
+    showLowUsageVersions,
+    pending,
+    error,
+    // Computed
+    filteredGroups,
+    chartDataset,
+    totalDownloads,
+    hasData,
+    // Methods
+    fetchDistribution,
+  }
+}

i18n/locales/en.json

···
       "more_tagged": "{count} more tagged",
       "all_covered": "All versions are covered by tags above",
       "deprecated_title": "{version} (deprecated)",
-      "view_all": "View {count} version | View all {count} versions"
+      "view_all": "View {count} version | View all {count} versions",
+      "distribution_title": "Semver Group",
+      "distribution_modal_title": "Versions",
+      "grouping_major": "Major",
+      "grouping_minor": "Minor",
+      "recent_versions_only": "Recent versions only",
+      "recent_versions_only_tooltip": "Show only versions published within the last year.",
+      "show_low_usage": "Show low usage versions",
+      "show_low_usage_tooltip": "Include version groups with less than 1% of total downloads",
+      "date_range_tooltip": "Last week of version distributions only"
     },
     "dependencies": {
       "title": "Dependency ({count}) | Dependencies ({count})",
···
     },
     "downloads": {
       "title": "Weekly Downloads",
+      "modal_title": "Weekly Downloads",
       "analyze": "Analyze downloads",
       "community_distribution": "View community adoption distribution"
     },

i18n/schema.json

···
             },
             "view_all": {
               "type": "string"
+            },
+            "distribution_title": {
+              "type": "string"
+            },
+            "distribution_modal_title": {
+              "type": "string"
+            },
+            "grouping_major": {
+              "type": "string"
+            },
+            "grouping_minor": {
+              "type": "string"
+            },
+            "recent_versions_only": {
+              "type": "string"
+            },
+            "recent_versions_only_tooltip": {
+              "type": "string"
+            },
+            "show_low_usage": {
+              "type": "string"
+            },
+            "show_low_usage_tooltip": {
+              "type": "string"
+            },
+            "date_range_tooltip": {
+              "type": "string"
             }
           },
           "additionalProperties": false
···
           "type": "object",
           "properties": {
             "title": {
+              "type": "string"
+            },
+            "modal_title": {
               "type": "string"
             },
             "analyze": {

lunaria/files/en-GB.json

···
       "more_tagged": "{count} more tagged",
       "all_covered": "All versions are covered by tags above",
       "deprecated_title": "{version} (deprecated)",
-      "view_all": "View {count} version | View all {count} versions"
+      "view_all": "View {count} version | View all {count} versions",
+      "distribution_title": "Semver Group",
+      "distribution_modal_title": "Versions",
+      "grouping_major": "Major",
+      "grouping_minor": "Minor",
+      "recent_versions_only": "Recent versions only",
+      "recent_versions_only_tooltip": "Show only versions published within the last year.",
+      "show_low_usage": "Show low usage versions",
+      "show_low_usage_tooltip": "Include version groups with less than 1% of total downloads",
+      "date_range_tooltip": "Last week of version distributions only"
     },
     "dependencies": {
       "title": "Dependency ({count}) | Dependencies ({count})",
···
     },
     "downloads": {
       "title": "Weekly Downloads",
+      "modal_title": "Weekly Downloads",
       "analyze": "Analyze downloads",
       "community_distribution": "View community adoption distribution"
     },

lunaria/files/en-US.json

···
       "more_tagged": "{count} more tagged",
       "all_covered": "All versions are covered by tags above",
       "deprecated_title": "{version} (deprecated)",
-      "view_all": "View {count} version | View all {count} versions"
+      "view_all": "View {count} version | View all {count} versions",
+      "distribution_title": "Semver Group",
+      "distribution_modal_title": "Versions",
+      "grouping_major": "Major",
+      "grouping_minor": "Minor",
+      "recent_versions_only": "Recent versions only",
+      "recent_versions_only_tooltip": "Show only versions published within the last year.",
+      "show_low_usage": "Show low usage versions",
+      "show_low_usage_tooltip": "Include version groups with less than 1% of total downloads",
+      "date_range_tooltip": "Last week of version distributions only"
     },
     "dependencies": {
       "title": "Dependency ({count}) | Dependencies ({count})",
···
     },
     "downloads": {
       "title": "Weekly Downloads",
+      "modal_title": "Weekly Downloads",
       "analyze": "Analyze downloads",
       "community_distribution": "View community adoption distribution"
     },

nuxt.config.ts

···
         allowQuery: ['color', 'labelColor', 'label', 'name'],
       },
     },
+    '/api/registry/downloads/**': {
+      isr: {
+        expiration: 60 * 60 /* one hour */,
+        passQuery: true,
+        allowQuery: ['mode', 'filterOldVersions', 'filterThreshold'],
+      },
+    },
     '/api/registry/docs/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
     '/api/registry/file/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
     '/api/registry/provenance/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },

server/api/registry/downloads/[...slug].get.ts

···
+import { getQuery } from 'h3'
+import * as v from 'valibot'
+import { hash } from 'ohash'
+import type { VersionDistributionResponse } from '#shared/types'
+import { CACHE_MAX_AGE_ONE_HOUR } from '#shared/utils/constants'
+import { groupVersionDownloads } from '#server/utils/version-downloads'
+
+/**
+ * Raw response from npm downloads API
+ * GET https://api.npmjs.org/versions/{package}/last-week
+ */
+interface NpmVersionDownloadsResponse {
+  package: string
+  downloads: Record<string, number>
+}
+
+/**
+ * Query parameter validation schema
+ */
+const QuerySchema = v.object({
+  mode: v.optional(v.picklist(['major', 'minor'] as const), 'major'),
+  filterThreshold: v.optional(
+    v.pipe(
+      v.string(),
+      v.toNumber(), // Fails validation on invalid conversion (e.g., "abc") instead of producing NaN
+      v.minValue(0), // Ensure non-negative values
+    ),
+  ),
+  filterOldVersions: v.optional(v.picklist(['true', 'false'] as const), 'false'),
+})
+
+/**
+ * GET /api/registry/downloads/:name/versions or /api/registry/downloads/@scope/name/versions
+ *
+ * Fetch per-version download statistics and group by major or minor version.
+ * Data is cached for 1 hour with stale-while-revalidate.
+ *
+ * Query parameters:
+ * - mode: 'major' | 'minor' (default: 'major')
+ * - filterThreshold: minimum percentage to include (default: 1)
+ * - filterOldVersions: 'true' to include only versions published in last year (default: 'false')
+ */
+export default defineCachedEventHandler(
+  async event => {
+    // Supports: /downloads/lodash/versions, /downloads/@scope/name/versions
+    const slugParam = getRouterParam(event, 'slug')
+    const pkgParamSegments = slugParam?.split('/') ?? []
+
+    const lastSegment = pkgParamSegments.at(-1)
+    if (!lastSegment || lastSegment !== 'versions') {
+      throw createError({
+        statusCode: 404,
+        message: 'Invalid endpoint. Expected /versions',
+      })
+    }
+
+    const segments = pkgParamSegments.slice(0, -1)
+
+    const { rawPackageName } = parsePackageParams(segments)
+
+    if (!rawPackageName) {
+      throw createError({
+        statusCode: 404,
+        message: 'Package name is required',
+      })
+    }
+
+    try {
+      const query = getQuery(event)
+      const parsed = v.parse(QuerySchema, query)
+      const mode = parsed.mode
+      const filterThreshold = parsed.filterThreshold ?? 1
+      const filterOldVersionsBool = parsed.filterOldVersions === 'true'
+
+      const url = `https://api.npmjs.org/versions/${rawPackageName}/last-week`
+      const npmResponse = await fetch(url)
+
+      if (!npmResponse.ok) {
+        if (npmResponse.status === 404) {
+          throw createError({
+            statusCode: 404,
+            message: 'Package not found',
+          })
+        }
+        throw createError({
+          statusCode: 502,
+          message: 'Failed to fetch version download data from npm API',
+        })
+      }
+
+      const data: NpmVersionDownloadsResponse = await npmResponse.json()
+
+      let groups = groupVersionDownloads(data.downloads, mode)
+
+      if (filterThreshold > 0) {
+        groups = groups.filter(group => group.percentage >= filterThreshold)
+      }
+
+      const totalDownloads = Object.values(data.downloads).reduce((sum, count) => sum + count, 0)
+
+      const apiResponse: VersionDistributionResponse = {
+        package: rawPackageName,
+        mode,
+        totalDownloads,
+        groups,
+        timestamp: new Date().toISOString(),
+      }
+
+      if (filterOldVersionsBool) {
+        try {
+          const oneYearAgo = new Date()
+          oneYearAgo.setFullYear(oneYearAgo.getFullYear() - 1)
+          const afterDate = oneYearAgo.toISOString()
+
+          // Decode package name in case it's URL-encoded (e.g., %40prisma%2Fclient -> @prisma/client)
+          const decodedPackageName = decodeURIComponent(rawPackageName)
+
+          // Fetch directly from npm-fast-meta HTTP API
+          const fastMetaUrl = `https://npm.antfu.dev/versions/${encodeURIComponent(decodedPackageName)}?after=${encodeURIComponent(afterDate)}`
+          const fastMetaResponse = await fetch(fastMetaUrl)
+
+          if (!fastMetaResponse.ok) {
+            throw new Error(`npm-fast-meta returned ${fastMetaResponse.status}`)
+          }
+
+          const versionData = (await fastMetaResponse.json()) as { versions: string[] }
+          apiResponse.recentVersions = versionData.versions
+        } catch {
+          // Graceful degradation - don't fail entire request if npm-fast-meta fails
+        }
+      }
+
+      return apiResponse
+    } catch (error: unknown) {
+      handleApiError(error, {
+        statusCode: 502,
+        message: 'Failed to fetch version download distribution',
+      })
+    }
+  },
+  {
+    maxAge: CACHE_MAX_AGE_ONE_HOUR,
+    swr: true,
+    getKey: event => {
+      const slug = getRouterParam(event, 'slug') ?? ''
+      const query = getQuery(event)
+      // Use ohash to create deterministic cache key from query params
+      // This ensures different param combinations = different cache entries
+      return `version-downloads:v5:${slug}:${hash(query)}`
+    },
+  },
+)

server/utils/version-downloads.ts

···
+import semver from 'semver'
+import type {
+  VersionDownloadPoint,
+  VersionGroupDownloads,
+  VersionGroupingMode,
+} from '#shared/types'
+
+/**
+ * Intermediate data structure for version processing
+ */
+interface ProcessedVersion {
+  version: string
+  downloads: number
+  major: number
+  minor: number
+  parsed: semver.SemVer
+}
+
+/**
+ * Filter out versions below a usage threshold
+ * @param versions Array of version download points
+ * @param thresholdPercent Minimum percentage to include (default: 0.1%)
+ * @returns Filtered array of versions
+ */
+export function filterLowUsageVersions(
+  versions: VersionDownloadPoint[],
+  thresholdPercent: number = 0.1,
+): VersionDownloadPoint[] {
+  return versions.filter(v => v.percentage >= thresholdPercent)
+}
+
+/**
+ * Parse and validate version strings, calculating total downloads
+ * @param rawDownloads Raw download data from npm API
+ * @returns Array of processed versions with parsed semver data
+ */
+function parseVersions(rawDownloads: Record<string, number>): ProcessedVersion[] {
+  const processed: ProcessedVersion[] = []
+
+  for (const [version, downloads] of Object.entries(rawDownloads)) {
+    const parsed = semver.parse(version)
+    if (!parsed) continue
+
+    processed.push({
+      version,
+      downloads,
+      major: parsed.major,
+      minor: parsed.minor,
+      parsed,
+    })
+  }
+
+  processed.sort((a, b) => semver.rcompare(a.version, b.version))
+
+  return processed
+}
+
+/**
+ * Calculate percentage for each version
+ * @param versions Processed versions
+ * @param totalDownloads Total download count
+ * @returns Array of version download points with percentages
+ */
+function addPercentages(
+  versions: ProcessedVersion[],
+  totalDownloads: number,
+): VersionDownloadPoint[] {
+  return versions.map(v => ({
+    version: v.version,
+    downloads: v.downloads,
+    percentage: totalDownloads > 0 ? (v.downloads / totalDownloads) * 100 : 0,
+  }))
+}
+
+/**
+ * Group versions by major version (e.g., 1.x, 2.x)
+ * @param rawDownloads Raw download data from npm API
+ * @returns Array of version groups sorted by downloads descending
+ */
+export function groupByMajor(rawDownloads: Record<string, number>): VersionGroupDownloads[] {
+  const processed = parseVersions(rawDownloads)
+  const totalDownloads = processed.reduce((sum, v) => sum + v.downloads, 0)
+
+  const groups = new Map<number, ProcessedVersion[]>()
+  for (const version of processed) {
+    const existing = groups.get(version.major) || []
+    existing.push(version)
+    groups.set(version.major, existing)
+  }
+
+  const result: VersionGroupDownloads[] = []
+  for (const [major, versions] of groups.entries()) {
+    const groupDownloads = versions.reduce((sum, v) => sum + v.downloads, 0)
+    const percentage = totalDownloads > 0 ? (groupDownloads / totalDownloads) * 100 : 0
+
+    result.push({
+      groupKey: `${major}.x`,
+      label: `v${major}.x`,
+      downloads: groupDownloads,
+      percentage,
+      versions: addPercentages(versions, totalDownloads),
+    })
+  }
+
+  result.sort((a, b) => b.downloads - a.downloads)
+
+  return result
+}
+
+/**
+ * Group versions by major.minor (e.g., 1.2.x, 1.3.x)
+ * Special handling for 0.x versions - treat them as separate majors
+ * @param rawDownloads Raw download data from npm API
+ * @returns Array of version groups sorted by downloads descending
+ */
+export function groupByMinor(rawDownloads: Record<string, number>): VersionGroupDownloads[] {
+  const processed = parseVersions(rawDownloads)
+  const totalDownloads = processed.reduce((sum, v) => sum + v.downloads, 0)
+
+  // Group by major.minor
+  const groups = new Map<string, ProcessedVersion[]>()
+  for (const version of processed) {
+    // For 0.x versions, treat each minor as significant (0.9.x, 0.10.x are different)
+    // For 1.x+, group by major.minor normally
+    const groupKey = `${version.major}.${version.minor}`
+    const existing = groups.get(groupKey) || []
+    existing.push(version)
+    groups.set(groupKey, existing)
+  }
+
+  // Convert to VersionGroupDownloads
+  const result: VersionGroupDownloads[] = []
+  for (const [groupKey, versions] of groups.entries()) {
+    const groupDownloads = versions.reduce((sum, v) => sum + v.downloads, 0)
+    const percentage = totalDownloads > 0 ? (groupDownloads / totalDownloads) * 100 : 0
+
+    result.push({
+      groupKey: `${groupKey}.x`,
+      label: `v${groupKey}.x`,
+      downloads: groupDownloads,
+      percentage,
+      versions: addPercentages(versions, totalDownloads),
+    })
+  }
+
+  result.sort((a, b) => b.downloads - a.downloads)
+
+  return result
+}
+
+/**
+ * Group versions by the specified mode
+ * @param rawDownloads Raw download data from npm API
+ * @param mode Grouping mode ('major' or 'minor')
+ * @returns Array of version groups sorted by downloads descending
+ */
+export function groupVersionDownloads(
+  rawDownloads: Record<string, number>,
+  mode: VersionGroupingMode,
+): VersionGroupDownloads[] {
+  switch (mode) {
+    case 'major':
+      return groupByMajor(rawDownloads)
+    case 'minor':
+      return groupByMinor(rawDownloads)
+    default:
+      throw new Error(`Invalid grouping mode: ${mode}`)
+  }
+}

shared/types/index.ts

···
 export * from './i18n-status'
 export * from './comparison'
 export * from './skills'
+export * from './version-downloads'

shared/types/version-downloads.ts

···
+/**
+ * Version Downloads Distribution Types
+ * Types for version download statistics and grouping.
+ *
+ * These types support fetching per-version download counts from npm API
+ * and grouping them by major/minor versions for distribution analysis.
+ */
+
+/**
+ * Download data for a single package version
+ */
+export interface VersionDownloadPoint {
+  /** Semantic version string (e.g., "1.2.3") */
+  version: string
+  /** Download count for this version */
+  downloads: number
+  /** Percentage of total downloads (0-100) */
+  percentage: number
+}
+
+/**
+ * Aggregated download data for a version group (major or minor)
+ */
+export interface VersionGroupDownloads {
+  /** Group identifier (e.g., "1.x" for major, "1.2.x" for minor) */
+  groupKey: string
+  /** Human-readable label (e.g., "v1.x", "v1.2.x") */
+  label: string
+  /** Total downloads for all versions in this group */
+  downloads: number
+  /** Percentage of total downloads (0-100) */
+  percentage: number
+  /** Individual versions in this group */
+  versions: VersionDownloadPoint[]
+}
+
+/**
+ * Mode for grouping versions
+ * - 'major': Group by major version (1.x, 2.x)
+ * - 'minor': Group by minor version (1.2.x, 1.3.x)
+ */
+export type VersionGroupingMode = 'major' | 'minor'
+
+/**
+ * API response for version download distribution
+ */
+export interface VersionDistributionResponse {
+  /** Package name */
+  package: string
+  /** Grouping mode used */
+  mode: VersionGroupingMode
+  /** Total downloads across all versions */
+  totalDownloads: number
+  /** Grouped version data */
+  groups: VersionGroupDownloads[]
+  /** ISO 8601 timestamp when data was fetched */
+  timestamp: string
+  /** List of version strings published within the last year (only present when filterOldVersions=true) */
+  recentVersions?: string[]
+}

test/nuxt/a11y.spec.ts

···
   describe('PackageChartModal', () => {
     it('should have no accessibility violations when closed', async () => {
       const component = await mountSuspended(PackageChartModal, {
-        props: { open: false },
-        slots: { title: 'Downloads', default: '<div>Chart content</div>' },
+        props: { open: false, title: 'Downloads' },
+        slots: { default: '<div>Chart content</div>' },
       })
       const results = await runAxe(component)
       expect(results.violations).toEqual([])

test/unit/a11y-component-coverage.spec.ts

···
   'Settings/TranslationHelper.vue': 'i18n helper component - requires specific locale status data',
   'Package/WeeklyDownloadStats.vue':
     'Uses vue-data-ui VueUiSparkline - has DOM measurement issues in test environment',
+  'Package/VersionDistribution.vue':
+    'Uses vue-data-ui VueUiXy - has DOM measurement issues in test environment',
   'UserCombobox.vue': 'Unused component - intended for future admin features',
   'SkeletonBlock.vue': 'Already covered indirectly via other component tests',
   'SkeletonInline.vue': 'Already covered indirectly via other component tests',