@byline/admin 5.1.2 → 5.1.4

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()
+  })
+})

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

@@ -0,0 +1,159 @@
+'use client'
+
+/**
+ * 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
+ */
+
+/**
+ * Full ranking for one dashboard card, paged client-side.
+ *
+ * The dashboard cards show a short preview so the lists band stays even
+ * regardless of traffic. This modal shows the whole set behind a card's
+ * "View all" action. A `source` may be a ready list (countries are fully
+ * loaded with the dashboard) or a loader invoked once each time the modal
+ * opens (pages, downloads and referrers fetch a larger top-N on demand).
+ *
+ * The caption keeps the dashboard's honesty rule: when the loaded rows are
+ * a top-N slice of a larger set it says so alongside the page range.
+ */
+
+import type React from 'react'
+import { useEffect, useState } from 'react'
+
+import { useTranslation } from '@byline/i18n/react'
+import { Alert, Button, LoaderRing, Modal, Pagination } from '@byline/ui/react'
+import cx from 'clsx'
+
+import styles from './dashboard.module.css'
+import { type AnalyticsTone, pageWindow, type RankedListSource, RankingRows } from './ranking.js'
+
+export type RankedListSourceInput = RankedListSource | (() => Promise<RankedListSource>)
+
+export interface RankedListModalProps {
+  isOpen: boolean
+  onDismiss(): void
+  title: string
+  tone: AnalyticsTone
+  locale: string
+  source: RankedListSourceInput
+  pageSize?: number
+}
+
+type LoadState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'ready'; data: RankedListSource }
+  | { status: 'error' }
+
+export function RankedListModal({
+  isOpen,
+  onDismiss,
+  title,
+  tone,
+  locale,
+  source,
+  pageSize = 25,
+}: RankedListModalProps): React.JSX.Element {
+  const { t } = useTranslation('byline-admin')
+  const [state, setState] = useState<LoadState>({ status: 'idle' })
+  const [page, setPage] = useState(1)
+
+  useEffect(() => {
+    if (!isOpen) {
+      setState({ status: 'idle' })
+      setPage(1)
+      return
+    }
+    if (typeof source !== 'function') {
+      setState({ status: 'ready', data: source })
+      return
+    }
+    let current = true
+    setState({ status: 'loading' })
+    source()
+      .then((data) => {
+        if (current) setState({ status: 'ready', data })
+      })
+      .catch(() => {
+        if (current) setState({ status: 'error' })
+      })
+    return () => {
+      current = false
+    }
+  }, [isOpen, source])
+
+  const data = state.status === 'ready' ? state.data : undefined
+  const loaded = data?.rows.length ?? 0
+  const window = pageWindow(loaded, pageSize, page)
+  const visible = data?.rows.slice(window.start, window.end) ?? []
+  const truncated = data != null && data.total > loaded
+  const caption = data
+    ? [
+        loaded === 0
+          ? undefined
+          : t('analytics.range', {
+              from: window.start + 1,
+              to: window.end,
+              total: loaded,
+            }),
+        truncated ? t('analytics.topOf', { shown: loaded, total: data.total }) : undefined,
+      ]
+        .filter((value): value is string => value != null)
+        .join(' · ')
+    : undefined
+
+  return (
+    <Modal isOpen={isOpen} onDismiss={onDismiss} closeOnOverlayClick>
+      <Modal.Container className={cx('byline-analytics-modal', styles.modal)}>
+        <Modal.Header>
+          <h2>{title}</h2>
+          {caption != null && caption.length > 0 && (
+            <p className={cx('muted', 'byline-analytics-modal-caption', styles.modalCaption)}>
+              {caption}
+            </p>
+          )}
+        </Modal.Header>
+        <Modal.Content className={cx('byline-analytics-modal-content', styles.modalContent)}>
+          {state.status === 'loading' && (
+            <div role="status" aria-live="polite" className={styles.modalStatus}>
+              <LoaderRing size={28} aria-hidden="true" />
+              <span className={styles.srOnly}>{t('common.loading')}</span>
+            </div>
+          )}
+          {state.status === 'error' && (
+            <div role="alert">
+              <Alert intent="danger" close={false}>
+                {t('analytics.loadError')}
+              </Alert>
+            </div>
+          )}
+          {data != null && loaded === 0 && <p className="muted">{t('analytics.empty')}</p>}
+          {data != null && loaded > 0 && <RankingRows rows={visible} tone={tone} locale={locale} />}
+        </Modal.Content>
+        <Modal.Actions className={cx('byline-analytics-modal-actions', styles.modalActions)}>
+          {window.pageCount > 1 ? (
+            <Pagination
+              variant="dashboard"
+              count={window.pageCount}
+              page={Math.min(page, window.pageCount)}
+              onChange={(_event, next) => setPage(next)}
+            >
+              <Pagination.Root ariaLabel={t('analytics.pager')}>
+                <Pagination.Pager />
+              </Pagination.Root>
+            </Pagination>
+          ) : (
+            <span />
+          )}
+          <Button type="button" size="sm" variant="outlined" onClick={onDismiss}>
+            {t('common.actions.close')}
+          </Button>
+        </Modal.Actions>
+      </Modal.Container>
+    </Modal>
+  )
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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 { describe, expect, it } from 'vitest'
+
+import { pageWindow, regionName } from './ranking.js'
+
+describe('pageWindow', () => {
+  it('slices the first page and reports the page count', () => {
+    expect(pageWindow(55, 25, 1)).toEqual({ start: 0, end: 25, pageCount: 3 })
+  })
+
+  it('shortens the last page to the remaining rows', () => {
+    expect(pageWindow(55, 25, 3)).toEqual({ start: 50, end: 55, pageCount: 3 })
+  })
+
+  it('clamps a page past the end and below the start', () => {
+    expect(pageWindow(55, 25, 9)).toEqual({ start: 50, end: 55, pageCount: 3 })
+    expect(pageWindow(55, 25, 0)).toEqual({ start: 0, end: 25, pageCount: 3 })
+  })
+
+  it('reports one empty page for no rows', () => {
+    expect(pageWindow(0, 25, 1)).toEqual({ start: 0, end: 0, pageCount: 1 })
+  })
+})
+
+describe('regionName', () => {
+  it('renders a known ISO code as the localised region name', () => {
+    expect(regionName('TH', 'en')).toBe('Thailand')
+    expect(regionName('TH', 'fr')).toBe('Thaïlande')
+  })
+
+  it('falls back to the code for unknown or malformed values', () => {
+    expect(regionName('AA', 'en')).toBe('AA')
+    expect(regionName('not-a-code', 'en')).toBe('not-a-code')
+    expect(regionName('', 'en')).toBe('')
+  })
+})