@byline/admin 5.1.3 → 5.1.4

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "5.1.3",
+  "version": "5.1.4",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -183,12 +183,12 @@
     "react-diff-viewer-continued": "^4.4.0",
     "uuid": "^14.0.2",
     "zod": "^4.5.4",
-    "@byline/analytics": "5.1.3",
-    "@byline/analytics-agent": "5.1.3",
-    "@byline/ui": "5.1.3",
-    "@byline/core": "5.1.3",
-    "@byline/i18n": "5.1.3",
-    "@byline/auth": "5.1.3"
+    "@byline/analytics": "5.1.4",
+    "@byline/auth": "5.1.4",
+    "@byline/i18n": "5.1.4",
+    "@byline/ui": "5.1.4",
+    "@byline/analytics-agent": "5.1.4",
+    "@byline/core": "5.1.4"
   },
   "peerDependencies": {
     "react": "^19.0.0",

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

@@ -328,3 +328,72 @@
     grid-template-columns: 1fr;
   }
 }
+
+/* ── Preview cap and full-list modal ───────────────────────────────── */
+
+/* The header carries the "View all" action beside the title so the card's
+   body stays a plain ranking. */
+.listHeader,
+:global(.byline-analytics-list-header) {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 0.75rem;
+}
+
+.listHeading {
+  min-width: 0;
+}
+
+.viewAll,
+:global(.byline-analytics-view-all) {
+  flex-shrink: 0;
+  white-space: nowrap;
+}
+
+.modal,
+:global(.byline-analytics-modal) {
+  width: min(40rem, calc(100vw - 2rem));
+}
+
+.modalCaption,
+:global(.byline-analytics-modal-caption) {
+  margin: 0.25rem 0 0;
+  font-size: 0.75rem;
+  font-variant-numeric: tabular-nums;
+}
+
+/* Twenty-five rows exceed a short viewport; the content scrolls inside the
+   dialog so the pager and close action stay reachable. */
+.modalContent,
+:global(.byline-analytics-modal-content) {
+  max-height: min(60vh, 48rem);
+  overflow-y: auto;
+}
+
+.modalStatus {
+  display: flex;
+  justify-content: center;
+  padding: 2rem 0;
+}
+
+.modalActions,
+:global(.byline-analytics-modal-actions) {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+}
+
+.srOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/src/modules/analytics/components/dashboard.tsx

@@ -11,6 +11,11 @@
 import type React from 'react'
 import { useEffect, useMemo, useState } from 'react'
 
+import type {
+  AnalyticsPathTotal,
+  AnalyticsRankedTotals,
+  AnalyticsReferrerTotal,
+} from '@byline/analytics'
 import {
   ANALYTICS_DASHBOARD_PERIODS,
   ANALYTICS_OVERFLOW_KEY,
@@ -18,23 +23,42 @@ import {
 } from '@byline/analytics/config'
 import { ANALYTICS_IGNORE_STORAGE_KEY } from '@byline/analytics-agent'
 import { useTranslation } from '@byline/i18n/react'
-import { Button, Card, Container, Section, Select } from '@byline/ui/react'
+import { Button, Card, Container, Section, Select, useModal } from '@byline/ui/react'
 import cx from 'clsx'
 
 import styles from './dashboard.module.css'
+import { RankedListModal, type RankedListSourceInput } from './ranked-list-modal.js'
+import { type AnalyticsTone, type RankedRow, RankingRows, regionName } from './ranking.js'
 import { AnalyticsTimeseries, resolveAnalyticsChartGranularity } from './timeseries.js'
 import type { AnalyticsDashboardData, AnalyticsDashboardPeriod } from '../types.js'
 
+export { shareWidth } from './ranking.js'
+
+/** Rows each ranked card shows before offering the full list. */
+export const ANALYTICS_PREVIEW_ROWS = 10
+
+/** The truncated lists a host can fetch in full on demand. */
+export type AnalyticsFullListKind = 'pages' | 'downloads' | 'referrers'
+
 export interface AnalyticsDashboardProps {
   data: AnalyticsDashboardData
   period: AnalyticsDashboardPeriod
   onPeriodChange(period: AnalyticsDashboardPeriod): void
+  /**
+   * Fetch a larger top-N for one of the truncated lists when its "View all"
+   * modal opens. Countries are always complete and never use this. Omit it
+   * and those cards still show their preview, without the action.
+   */
+  loadFullList?(
+    kind: AnalyticsFullListKind
+  ): Promise<AnalyticsRankedTotals<AnalyticsPathTotal | AnalyticsReferrerTotal>>
 }
 
 export function AnalyticsDashboard({
   data,
   period,
   onPeriodChange,
+  loadFullList,
 }: AnalyticsDashboardProps): React.JSX.Element {
   const { locale, t } = useTranslation('byline-admin')
   const [excluded, setExcluded] = useState(false)
@@ -70,6 +94,30 @@ export function AnalyticsDashboard({
   const days = data.summary.timeseries.length
   const chartGranularity = resolveAnalyticsChartGranularity(period, days)
 
+  // Each full-list loader is a stable closure per range so the modal's
+  // effect does not refetch on every dashboard render.
+  const fullLists = useMemo(() => {
+    if (!loadFullList) return {}
+    const load = (kind: AnalyticsFullListKind) => () =>
+      loadFullList(kind).then((result) => ({
+        rows: result.rows.map(toRankedRow),
+        total: result.total,
+      }))
+    return { pages: load('pages'), downloads: load('downloads'), referrers: load('referrers') }
+  }, [loadFullList])
+
+  const countryRows = useMemo(
+    () =>
+      data.countries.map((row) => ({
+        key: row.country,
+        label: regionName(row.country, locale),
+        value: row.views,
+        visitors: row.visitors,
+        overflow: false,
+      })),
+    [data.countries, locale]
+  )
+
   return (
     <Section>
       <Container>
@@ -156,15 +204,17 @@ export function AnalyticsDashboard({
         </Card>
 
         {/* Top pages is the list people actually read, so it gets the wide
-            column; referrers and countries stack beside it. */}
+            column; referrers and countries stack beside it. Every card shows
+            the same preview depth so the band stays even at any traffic. */}
         <div className={cx('byline-analytics-lists', styles.lists)}>
           <RankedList
             title={t('analytics.sections.pages')}
             caption={t('analytics.columns.viewsAndUniques')}
             tone="views"
             locale={locale}
-            rows={data.pages.rows.map(toPathRow)}
+            rows={data.pages.rows.map(toRankedRow)}
             total={data.pages.total}
+            fullList={fullLists.pages}
             coverageFrom={partialCoverageFrom(data.range.from, data.coverage.pathsFrom)}
           />
           <div className={styles.stack}>
@@ -172,27 +222,19 @@ export function AnalyticsDashboard({
               title={t('analytics.sections.referrers')}
               tone="visitors"
               locale={locale}
+              rows={data.referrers.rows.map(toRankedRow)}
               total={data.referrers.total}
+              fullList={fullLists.referrers}
               coverageFrom={partialCoverageFrom(data.range.from, data.coverage.referrersFrom)}
-              rows={data.referrers.rows.map((row) => ({
-                key: row.referrerHost,
-                label: row.referrerHost,
-                value: row.views,
-                visitors: row.visitors,
-                overflow: row.referrerHost === ANALYTICS_OVERFLOW_KEY,
-              }))}
             />
             <RankedList
               title={t('analytics.sections.countries')}
               tone="visitors"
               locale={locale}
-              rows={data.countries.map((row) => ({
-                key: row.country,
-                label: row.country,
-                value: row.views,
-                visitors: row.visitors,
-                overflow: false,
-              }))}
+              rows={countryRows}
+              total={countryRows.length}
+              // Countries arrive complete, so the full list needs no fetch.
+              fullList={{ rows: countryRows, total: countryRows.length }}
             />
           </div>
         </div>
@@ -202,8 +244,9 @@ export function AnalyticsDashboard({
           caption={t('analytics.columns.clicksAndUniques')}
           tone="downloads"
           locale={locale}
-          rows={data.downloads.rows.map(toPathRow)}
+          rows={data.downloads.rows.map(toRankedRow)}
           total={data.downloads.total}
+          fullList={fullLists.downloads}
           coverageFrom={partialCoverageFrom(data.range.from, data.coverage.pathsFrom)}
         />
       </Container>
@@ -211,20 +254,12 @@ export function AnalyticsDashboard({
   )
 }
 
-type AnalyticsTone = 'views' | 'visitors' | 'downloads'
-
 const TONE_TILE: Record<AnalyticsTone, string | undefined> = {
   views: styles.toneViews,
   visitors: styles.toneVisitors,
   downloads: styles.toneDownloads,
 }
 
-const TONE_BAR: Record<AnalyticsTone, string | undefined> = {
-  views: styles.barViews,
-  visitors: styles.barVisitors,
-  downloads: styles.barDownloads,
-}
-
 function StatTile({
   tone,
   label,
@@ -245,21 +280,15 @@ function StatTile({
   )
 }
 
-interface RankedRow {
-  key: string
-  label: string
-  value: number
-  visitors: number
-  overflow: boolean
-}
-
-function toPathRow(row: { path: string; views: number; visitors: number }): RankedRow {
+/** Map a path or referrer total onto the shared row shape. */
+function toRankedRow(row: AnalyticsPathTotal | AnalyticsReferrerTotal): RankedRow {
+  const key = 'path' in row ? row.path : row.referrerHost
   return {
-    key: row.path,
-    label: row.path,
+    key,
+    label: key,
     value: row.views,
     visitors: row.visitors,
-    overflow: row.path === ANALYTICS_OVERFLOW_KEY,
+    overflow: key === ANALYTICS_OVERFLOW_KEY,
   }
 }
 
@@ -270,6 +299,7 @@ function RankedList({
   tone,
   locale,
   total,
+  fullList,
   coverageFrom,
 }: {
   title: string
@@ -277,17 +307,19 @@ function RankedList({
   rows: RankedRow[]
   tone: AnalyticsTone
   locale: string
-  /** Distinct keys in the period; omit for lists that are never truncated. */
-  total?: number
+  /** Distinct keys in the period, before any top-N slice. */
+  total: number
+  /** The complete ranking, ready or fetched on demand; omit to offer no "View all". */
+  fullList?: RankedListSourceInput
   /** First complete day when the selected report begins before retained rows. */
   coverageFrom?: string
 }): React.JSX.Element {
   const { t } = useTranslation('byline-admin')
-  const numbers = useMemo(() => new Intl.NumberFormat(locale), [locale])
-  const ceiling = Math.max(1, ...rows.map((row) => row.value))
-  // Say so when the list is a top-N slice. Without this the card presents a
+  const modal = useModal()
+  const preview = rows.slice(0, ANALYTICS_PREVIEW_ROWS)
+  // Say so when the card is a top-N slice. Without this the card presents a
   // truncated ranking as though it were the whole set.
-  const truncated = total != null && total > rows.length
+  const truncated = total > preview.length
   const coverageDate = useMemo(
     () =>
       new Intl.DateTimeFormat(locale, {
@@ -297,7 +329,7 @@ function RankedList({
     [locale]
   )
   const description = [
-    truncated ? t('analytics.topOf', { shown: rows.length, total }) : caption,
+    truncated ? t('analytics.topOf', { shown: preview.length, total }) : caption,
     coverageFrom == null
       ? undefined
       : t('analytics.coverage.since', {
@@ -309,54 +341,44 @@ function RankedList({
 
   return (
     <Card className={cx('byline-analytics-list', styles.list)}>
-      <Card.Header>
-        <Card.Title>{title}</Card.Title>
-        {description.length > 0 && <Card.Description>{description}</Card.Description>}
+      <Card.Header className={cx('byline-analytics-list-header', styles.listHeader)}>
+        <div className={styles.listHeading}>
+          <Card.Title>{title}</Card.Title>
+          {description.length > 0 && <Card.Description>{description}</Card.Description>}
+        </div>
+        {fullList != null && truncated && (
+          <Button
+            type="button"
+            size="xs"
+            variant="outlined"
+            className={cx('byline-analytics-view-all', styles.viewAll)}
+            onClick={modal.onOpen}
+          >
+            {t('analytics.viewAll', { count: total })}
+          </Button>
+        )}
       </Card.Header>
       <Card.Content>
-        {rows.length === 0 ? (
+        {preview.length === 0 ? (
           <p className="muted">{t('analytics.empty')}</p>
         ) : (
-          <ol className={cx('byline-analytics-ranking', styles.ranking)}>
-            {rows.map((row) => (
-              <li
-                key={row.key}
-                className={cx(
-                  'byline-analytics-ranking-row',
-                  styles.rankingRow,
-                  TONE_BAR[tone],
-                  row.overflow && styles.rankingOverflow
-                )}
-                // The share bar sits behind the row so the label and its
-                // magnitude occupy one line and are read together.
-                style={
-                  {
-                    '--byline-analytics-share': `${shareWidth(row.value, ceiling)}%`,
-                  } as React.CSSProperties
-                }
-              >
-                <span className={styles.rankingLabel} title={row.key}>
-                  {/* `__other__` is a reserved aggregate, not a page anyone
-                      visited — never render it as though it were a real path. */}
-                  {row.overflow ? t('analytics.overflow') : row.label}
-                </span>
-                <span className={styles.rankingValue}>{numbers.format(row.value)}</span>
-                <span className={styles.rankingVisitors}>{numbers.format(row.visitors)}</span>
-              </li>
-            ))}
-          </ol>
+          <RankingRows rows={preview} tone={tone} locale={locale} />
         )}
       </Card.Content>
+      {fullList != null && (
+        <RankedListModal
+          isOpen={modal.isOpen}
+          onDismiss={modal.onDismiss}
+          title={title}
+          tone={tone}
+          locale={locale}
+          source={fullList}
+        />
+      )}
     </Card>
   )
 }
 
-/** Never collapse the bar entirely: a visible sliver still encodes "smallest". */
-export function shareWidth(value: number, ceiling: number): number {
-  if (!Number.isFinite(value) || value <= 0 || ceiling <= 0) return 0
-  return Math.max(3, Math.min(100, (value / ceiling) * 100))
-}
-
 export function formatShare(part: number, whole: number, locale: string): string {
   const percent = new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 1 })
   return percent.format(whole <= 0 ? 0 : part / whole)

package/src/modules/analytics/components/ranked-list-modal.test.tsx

@@ -0,0 +1,154 @@
+/**
+ * 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 { act } from 'react'
+
+import { adminTranslations } from '@byline/i18n/admin'
+import { I18nProvider } from '@byline/i18n/react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// The real Modal renders through a Base UI portal; a pass-through keeps the
+// rows queryable in the test container. Everything else is the shipped kit.
+vi.mock('@byline/ui/react', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>()
+  const Pass = ({ children }: any) => <div>{children}</div>
+  const Modal: any = ({ children, isOpen }: any) =>
+    isOpen ? <div data-testid="modal">{children}</div> : null
+  Modal.Container = Pass
+  Modal.Header = Pass
+  Modal.Content = Pass
+  Modal.Actions = Pass
+  return { ...actual, Modal }
+})
+
+import { RankedListModal } from './ranked-list-modal.js'
+import type { RankedRow } from './ranking.js'
+
+;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true
+
+function rows(count: number): RankedRow[] {
+  return Array.from({ length: count }, (_, i) => ({
+    key: `row-${i + 1}`,
+    label: `Row ${i + 1}`,
+    value: count - i,
+    visitors: 1,
+    overflow: false,
+  }))
+}
+
+let root: Root
+let container: HTMLDivElement
+beforeEach(() => {
+  // The kit pager's mobile toggle reads a media query; jsdom has no matchMedia.
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn((query: string) => ({
+      matches: false,
+      media: query,
+      addEventListener() {},
+      removeEventListener() {},
+      addListener() {},
+      removeListener() {},
+    }))
+  )
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+  vi.unstubAllGlobals()
+})
+
+async function render(props: Partial<React.ComponentProps<typeof RankedListModal>>) {
+  await act(async () => {
+    root.render(
+      <I18nProvider
+        bundle={adminTranslations({ locales: ['en'] })}
+        activeLocale="en"
+        defaultLocale="en"
+        localeDefinitions={[]}
+      >
+        <RankedListModal
+          isOpen
+          onDismiss={() => {}}
+          title="Countries"
+          tone="visitors"
+          locale="en"
+          source={{ rows: [], total: 0 }}
+          {...props}
+        />
+      </I18nProvider>
+    )
+  })
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0))
+  })
+}
+
+const labels = () =>
+  Array.from(container.querySelectorAll('.byline-analytics-ranking-row')).map(
+    (row) => row.querySelector('span')?.textContent
+  )
+
+describe('RankedListModal', () => {
+  it('renders a preloaded list on the first page with a range caption', async () => {
+    await render({ source: { rows: rows(55), total: 55 } })
+    expect(labels()).toHaveLength(25)
+    expect(labels()[0]).toBe('Row 1')
+    expect(container.textContent).toContain('1–25 of 55')
+  })
+
+  it('moves to the next page when the pager is used', async () => {
+    await render({ source: { rows: rows(55), total: 55 } })
+    const next = container.querySelector('[aria-label="Next"]')
+    expect(next).not.toBeNull()
+    await act(async () => {
+      ;(next as HTMLElement).click()
+    })
+    expect(labels()[0]).toBe('Row 26')
+    expect(container.textContent).toContain('26–50 of 55')
+  })
+
+  it('loads an async source when opened and then renders it', async () => {
+    let resolve!: (value: { rows: RankedRow[]; total: number }) => void
+    const load = vi.fn(
+      () =>
+        new Promise<{ rows: RankedRow[]; total: number }>((r) => {
+          resolve = r
+        })
+    )
+    await render({ title: 'Top pages', source: load })
+    expect(load).toHaveBeenCalledTimes(1)
+    expect(container.querySelector('[role="status"]')).not.toBeNull()
+    await act(async () => {
+      resolve({ rows: rows(3), total: 143 })
+    })
+    expect(labels()).toHaveLength(3)
+    expect(container.textContent).toContain('1–3 of 3')
+    expect(container.textContent).toContain('Top 3 of 143')
+  })
+
+  it('shows an error instead of rows when the async source fails', async () => {
+    const load = vi.fn(() => Promise.reject(new Error('network')))
+    await render({ title: 'Top pages', source: load })
+    expect(labels()).toHaveLength(0)
+    expect(container.querySelector('[role="alert"]')?.textContent).toContain(
+      'Unable to load this list'
+    )
+  })
+
+  it('does not call a loader while closed', async () => {
+    const load = vi.fn(() => Promise.resolve({ rows: rows(1), total: 1 }))
+    await render({ isOpen: false, source: load })
+    expect(load).not.toHaveBeenCalled()
+    expect(container.querySelector('[data-testid="modal"]')).toBeNull()
+  })
+})