@byline/admin 4.14.1 → 4.16.0

package/src/modules/analytics/components/dashboard.module.css

@@ -0,0 +1,330 @@
+/**
+ * AnalyticsDashboard — the installation-level analytics page.
+ *
+ * Override handles:
+ *   .byline-analytics-header       — title block and period/exclusion controls
+ *   .byline-analytics-title        — page heading
+ *   .byline-analytics-help         — the daily-uniques qualification
+ *   .byline-analytics-controls     — period picker + exclusion toggle
+ *   .byline-analytics-stats        — the three metric tiles
+ *   .byline-analytics-stat         — one tile
+ *   .byline-analytics-stat-label   — tracked uppercase metric name
+ *   .byline-analytics-stat-value   — the figure
+ *   .byline-analytics-stat-foot    — the figure's qualification
+ *   .byline-analytics-chart-card   — card wrapping the timeseries
+ *   .byline-analytics-lists        — top-pages / referrers+countries band
+ *   .byline-analytics-list         — one ranked-list card
+ *   .byline-analytics-ranking      — the ordered list
+ *   .byline-analytics-ranking-row  — one row, carrying its share bar
+ *
+ * The tile hues are the collection dashboard's status-tile values
+ * (`byline-dashboard-stat-tile`), so the two surfaces read as one system.
+ * Amber is deliberately unused here: it already means "draft".
+ */
+
+.header,
+:global(.byline-analytics-header) {
+  display: flex;
+  align-items: flex-end;
+  justify-content: space-between;
+  gap: 1rem 1.5rem;
+  flex-wrap: wrap;
+  margin-bottom: 1.25rem;
+  padding-bottom: 1rem;
+  border-bottom: var(--border-width-thin) var(--border-style-solid) var(--gray-200);
+}
+
+.title,
+:global(.byline-analytics-title) {
+  margin: 0;
+  font-size: 1.875rem;
+  font-weight: 650;
+  letter-spacing: -0.02em;
+}
+
+.help,
+:global(.byline-analytics-help) {
+  max-width: 48ch;
+  margin: 0.35rem 0 0;
+  font-size: 0.8125rem;
+}
+
+/* `Card.Title` defaults to 1.8rem bold — larger than this page's own heading,
+   which inverted the hierarchy. Bring the section titles below the h1 while
+   keeping them clearly headings. Scoped to the analytics cards so no other
+   Card consumer shifts. */
+.chartCard :global(.byline-card-title),
+.list :global(.byline-card-title) {
+  font-size: 1.25rem;
+  font-weight: 600;
+  letter-spacing: normal;
+}
+
+.chartCard :global(.byline-card-description),
+.list :global(.byline-card-description) {
+  font-size: 0.75rem;
+}
+
+.controls,
+:global(.byline-analytics-controls) {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+}
+
+/* ── Metric tiles ──────────────────────────────────────────────────── */
+
+.stats,
+:global(.byline-analytics-stats) {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 0.75rem;
+  margin-bottom: 0.75rem;
+}
+
+.stat,
+:global(.byline-analytics-stat) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  min-width: 0;
+  padding: 1rem 1.125rem 1.125rem;
+  border-radius: 0.375rem;
+}
+
+.statLabel,
+:global(.byline-analytics-stat-label) {
+  font-size: 0.625rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  line-height: 1;
+}
+
+.statValue,
+:global(.byline-analytics-stat-value) {
+  font-size: clamp(1.75rem, 4.5vw, 2.5rem);
+  font-weight: 700;
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+  letter-spacing: -0.02em;
+}
+
+.statFoot,
+:global(.byline-analytics-stat-foot) {
+  font-size: 0.6875rem;
+  font-variant-numeric: tabular-nums;
+  color: var(--gray-600);
+}
+
+.toneViews {
+  background-color: #f0f9ff;
+}
+
+.toneViews .statLabel,
+.toneViews .statValue {
+  color: #0369a1;
+}
+
+.toneVisitors {
+  background-color: #f5f3ff;
+}
+
+.toneVisitors .statLabel,
+.toneVisitors .statValue {
+  color: #6d28d9;
+}
+
+.toneDownloads {
+  background-color: #ecfdf5;
+}
+
+.toneDownloads .statLabel,
+.toneDownloads .statValue {
+  color: #047857;
+}
+
+:is([data-theme="dark"], :global(.dark)) .statFoot,
+:is([data-theme="dark"], :global(.dark)) :global(.byline-analytics-stat-foot) {
+  color: var(--gray-400);
+}
+
+:is([data-theme="dark"], :global(.dark)) .toneViews {
+  background-color: rgba(12, 74, 110, 0.28);
+}
+
+:is([data-theme="dark"], :global(.dark)) .toneViews .statLabel,
+:is([data-theme="dark"], :global(.dark)) .toneViews .statValue {
+  color: #7dd3fc;
+}
+
+:is([data-theme="dark"], :global(.dark)) .toneVisitors {
+  background-color: rgba(76, 29, 149, 0.3);
+}
+
+:is([data-theme="dark"], :global(.dark)) .toneVisitors .statLabel,
+:is([data-theme="dark"], :global(.dark)) .toneVisitors .statValue {
+  color: #c4b5fd;
+}
+
+:is([data-theme="dark"], :global(.dark)) .toneDownloads {
+  background-color: rgba(6, 78, 59, 0.28);
+}
+
+:is([data-theme="dark"], :global(.dark)) .toneDownloads .statLabel,
+:is([data-theme="dark"], :global(.dark)) .toneDownloads .statValue {
+  color: #6ee7b7;
+}
+
+/* ── Lists ─────────────────────────────────────────────────────────── */
+
+.chartCard,
+:global(.byline-analytics-chart-card) {
+  margin-bottom: 0.75rem;
+}
+
+/* Top pages is the list people actually read, so it takes the wide track. */
+.lists,
+:global(.byline-analytics-lists) {
+  display: grid;
+  grid-template-columns: 1.55fr 1fr;
+  align-items: start;
+  gap: 0.75rem;
+  margin-bottom: 0.75rem;
+}
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.ranking,
+:global(.byline-analytics-ranking) {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+.rankingRow,
+:global(.byline-analytics-ranking-row) {
+  position: relative;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto auto;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 0.45rem 0.625rem;
+  border-radius: 0.25rem;
+  /* The row paints its own stacking context so the share bar can sit behind
+     the text without escaping to the card background. */
+  isolation: isolate;
+}
+
+.rankingRow::before {
+  content: "";
+  position: absolute;
+  inset: 0 auto 0 0;
+  z-index: -1;
+  width: var(--byline-analytics-share, 0%);
+  border-radius: 0.25rem;
+  background-color: var(--byline-analytics-bar, transparent);
+  opacity: 0.16;
+}
+
+.barViews {
+  --byline-analytics-bar: #38bdf8;
+}
+
+.barVisitors {
+  --byline-analytics-bar: #7c3aed;
+}
+
+.barDownloads {
+  --byline-analytics-bar: #10b981;
+}
+
+/* The reserved overflow bucket is an aggregate, not a page — a dashed rule
+   and muted label keep it from reading as traffic to a real path. */
+.rankingOverflow {
+  border: var(--border-width-thin) dashed var(--gray-300);
+}
+
+.rankingOverflow::before {
+  opacity: 0.07;
+}
+
+.rankingOverflow .rankingLabel {
+  font-style: italic;
+  color: var(--gray-600);
+}
+
+.rankingLabel {
+  overflow: hidden;
+  min-width: 0;
+  font-size: 0.8125rem;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.rankingValue {
+  font-size: 0.8125rem;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+}
+
+.rankingVisitors {
+  min-width: 3ch;
+  font-size: 0.6875rem;
+  font-variant-numeric: tabular-nums;
+  text-align: end;
+  color: var(--gray-500);
+}
+
+:is([data-theme="dark"], :global(.dark)) .header,
+:is([data-theme="dark"], :global(.dark)) :global(.byline-analytics-header) {
+  border-bottom-color: var(--gray-700);
+}
+
+:is([data-theme="dark"], :global(.dark)) .rankingVisitors {
+  color: var(--gray-400);
+}
+
+:is([data-theme="dark"], :global(.dark)) .rankingOverflow {
+  border-color: var(--gray-600);
+}
+
+:is([data-theme="dark"], :global(.dark)) .rankingOverflow .rankingLabel {
+  color: var(--gray-400);
+}
+
+:is([data-theme="dark"], :global(.dark)) .barVisitors {
+  --byline-analytics-bar: #a78bfa;
+}
+
+:is([data-theme="dark"], :global(.dark)) .barDownloads {
+  --byline-analytics-bar: #34d399;
+}
+
+@media (max-width: 900px) {
+  .lists,
+  :global(.byline-analytics-lists) {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (max-width: 720px) {
+  .header,
+  :global(.byline-analytics-header) {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .stats,
+  :global(.byline-analytics-stats) {
+    grid-template-columns: 1fr;
+  }
+}

package/src/modules/analytics/components/dashboard.test.node.ts

@@ -0,0 +1,193 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { AnalyticsSummaryDay } from '@byline/analytics'
+import { describe, expect, it } from 'vitest'
+
+import { formatShare, partialCoverageFrom, shareWidth } from './dashboard.js'
+import {
+  bucketAnalyticsTimeseries,
+  buildAnalyticsColumns,
+  resolveAnalyticsChartGranularity,
+} from './timeseries.js'
+
+function day(date: string, views: number, visitors: number): AnalyticsSummaryDay {
+  return { day: date, views, visitors, downloads: 0 }
+}
+
+describe('buildAnalyticsColumns', () => {
+  it('scales every column against the tallest day in the window', () => {
+    const columns = buildAnalyticsColumns([
+      day('2026-08-20', 0, 0),
+      day('2026-08-21', 5, 3),
+      day('2026-08-22', 10, 4),
+    ])
+
+    expect(columns).toHaveLength(3)
+    expect(columns[0]?.height).toBe(0)
+    expect(columns[1]?.height).toBe(90)
+    expect(columns[2]?.height).toBe(180)
+    // The tallest column reaches the top of the plot, and every column sits on
+    // the baseline: y + height is the full viewBox height.
+    for (const column of columns) {
+      expect(column.y + column.height).toBeCloseTo(180)
+    }
+  })
+
+  it('keeps the unique-visitor mark inset within its own day', () => {
+    const [column] = buildAnalyticsColumns([day('2026-08-20', 10, 4)])
+    if (column == null) throw new Error('expected one column')
+
+    // Visitors can never exceed that day's views, so the inset mark is always
+    // shorter and narrower than the column it sits inside.
+    expect(column.insetHeight).toBeLessThan(column.height)
+    expect(column.insetWidth).toBeLessThan(column.width)
+    expect(column.insetX).toBeGreaterThan(column.x)
+    expect(column.insetX + column.insetWidth).toBeLessThan(column.x + column.width)
+  })
+
+  it('survives an all-zero window without dividing by zero', () => {
+    const columns = buildAnalyticsColumns([day('2026-08-20', 0, 0), day('2026-08-21', 0, 0)])
+    expect(columns.map((column) => column.height)).toEqual([0, 0])
+    expect(columns.every((column) => Number.isFinite(column.x))).toBe(true)
+  })
+
+  it('returns nothing for an empty window', () => {
+    expect(buildAnalyticsColumns([])).toEqual([])
+  })
+
+  it('spans the full plot width and never overlaps neighbouring hit targets', () => {
+    const columns = buildAnalyticsColumns([
+      day('2026-08-20', 1, 1),
+      day('2026-08-21', 2, 1),
+      day('2026-08-22', 3, 2),
+    ])
+    expect(columns[0]?.hitX).toBe(0)
+    const last = columns[columns.length - 1]
+    expect((last?.hitX ?? 0) + (last?.hitWidth ?? 0)).toBeCloseTo(900)
+    for (let index = 1; index < columns.length; index += 1) {
+      const previous = columns[index - 1]
+      expect(columns[index]?.hitX).toBeCloseTo((previous?.hitX ?? 0) + (previous?.hitWidth ?? 0))
+    }
+  })
+})
+
+describe('analytics chart buckets', () => {
+  it('selects granularity explicitly from the reporting period and range size', () => {
+    expect(resolveAnalyticsChartGranularity(90, 90)).toBe('day')
+    expect(resolveAnalyticsChartGranularity('ytd', 90)).toBe('seven-day')
+    expect(resolveAnalyticsChartGranularity('all', 90)).toBe('day')
+    expect(resolveAnalyticsChartGranularity('all', 91)).toBe('seven-day')
+    expect(resolveAnalyticsChartGranularity('all', 733)).toBe('month')
+  })
+
+  it('keeps day boundaries and width in daily buckets', () => {
+    expect(bucketAnalyticsTimeseries([day('2026-01-01', 2, 1)], 'day')).toEqual([
+      {
+        from: '2026-01-01',
+        to: '2026-01-01',
+        granularity: 'day',
+        dayCount: 1,
+        views: 2,
+        visitors: 1,
+        downloads: 0,
+      },
+    ])
+  })
+
+  it('sums daily rows into explicit seven-day buckets', () => {
+    const days = Array.from({ length: 8 }, (_, index) =>
+      day(`2026-01-${String(index + 1).padStart(2, '0')}`, 2, 1)
+    )
+    expect(bucketAnalyticsTimeseries(days, 'seven-day')).toEqual([
+      {
+        from: '2026-01-01',
+        to: '2026-01-07',
+        granularity: 'seven-day',
+        dayCount: 7,
+        views: 14,
+        visitors: 7,
+        downloads: 0,
+      },
+      {
+        from: '2026-01-08',
+        to: '2026-01-08',
+        granularity: 'seven-day',
+        dayCount: 1,
+        views: 2,
+        visitors: 1,
+        downloads: 0,
+      },
+    ])
+  })
+
+  it('aligns month buckets to UTC calendar boundaries', () => {
+    expect(
+      bucketAnalyticsTimeseries(
+        [day('2026-01-31', 2, 1), day('2026-02-01', 3, 2), day('2026-02-02', 4, 2)],
+        'month'
+      )
+    ).toEqual([
+      {
+        from: '2026-01-31',
+        to: '2026-01-31',
+        granularity: 'month',
+        dayCount: 1,
+        views: 2,
+        visitors: 1,
+        downloads: 0,
+      },
+      {
+        from: '2026-02-01',
+        to: '2026-02-02',
+        granularity: 'month',
+        dayCount: 2,
+        views: 7,
+        visitors: 4,
+        downloads: 0,
+      },
+    ])
+  })
+})
+
+describe('shareWidth', () => {
+  it('scales a row against the largest row in its list', () => {
+    expect(shareWidth(50, 100)).toBe(50)
+    expect(shareWidth(100, 100)).toBe(100)
+  })
+
+  it('keeps the smallest row visible rather than collapsing it', () => {
+    expect(shareWidth(1, 10_000)).toBe(3)
+  })
+
+  it('returns no bar for absent or impossible values', () => {
+    expect(shareWidth(0, 100)).toBe(0)
+    expect(shareWidth(5, 0)).toBe(0)
+    expect(shareWidth(Number.NaN, 100)).toBe(0)
+  })
+})
+
+describe('formatShare', () => {
+  it('renders a locale-aware percentage of the whole', () => {
+    expect(formatShare(96, 1_200, 'en-US')).toBe('8%')
+    expect(formatShare(1, 3, 'en-US')).toBe('33.3%')
+  })
+
+  it('reports zero rather than NaN when there is nothing to divide', () => {
+    expect(formatShare(0, 0, 'en-US')).toBe('0%')
+  })
+})
+
+describe('partialCoverageFrom', () => {
+  it('returns a retained boundary only when it truncates the report', () => {
+    expect(partialCoverageFrom('2025-01-01', '2026-05-26')).toBe('2026-05-26')
+    expect(partialCoverageFrom('2026-05-27', '2026-05-26')).toBeUndefined()
+    expect(partialCoverageFrom('2026-05-26', '2026-05-26')).toBeUndefined()
+    expect(partialCoverageFrom('2025-01-01', null)).toBeUndefined()
+  })
+})