@byline/admin 5.1.3 → 5.1.4

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

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

@@ -0,0 +1,122 @@
+'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
+ */
+
+/**
+ * Ranked-row rendering shared by the dashboard cards and the full-list
+ * modal, plus the small pure helpers both rely on.
+ */
+
+import type React from 'react'
+import { useMemo } from 'react'
+
+import { useTranslation } from '@byline/i18n/react'
+import cx from 'clsx'
+
+import styles from './dashboard.module.css'
+
+export type AnalyticsTone = 'views' | 'visitors' | 'downloads'
+
+export interface RankedRow {
+  key: string
+  label: string
+  value: number
+  visitors: number
+  overflow: boolean
+}
+
+/** A complete ranking plus the size of the set it was drawn from. */
+export interface RankedListSource {
+  rows: RankedRow[]
+  total: number
+}
+
+const TONE_BAR: Record<AnalyticsTone, string | undefined> = {
+  views: styles.barViews,
+  visitors: styles.barVisitors,
+  downloads: styles.barDownloads,
+}
+
+/** The ordered list with a share bar behind each row. Renders no card chrome. */
+export function RankingRows({
+  rows,
+  tone,
+  locale,
+}: {
+  rows: RankedRow[]
+  tone: AnalyticsTone
+  locale: 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))
+  return (
+    <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>
+  )
+}
+
+/** 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))
+}
+
+/** Row indices for one page of a list, with the page clamped into range. */
+export function pageWindow(
+  total: number,
+  pageSize: number,
+  page: number
+): { start: number; end: number; pageCount: number } {
+  const pageCount = Math.max(1, Math.ceil(total / pageSize))
+  const current = Math.min(Math.max(1, page), pageCount)
+  const start = (current - 1) * pageSize
+  return { start, end: Math.min(total, start + pageSize), pageCount }
+}
+
+/**
+ * Localised region name for an ISO 3166-1 alpha-2 code, or the code itself
+ * when the value is not a code or the runtime has no name for it. The
+ * dashboard stores bare codes, so this is purely a display concern.
+ */
+export function regionName(code: string, locale: string): string {
+  if (!/^[A-Za-z]{2}$/.test(code)) return code
+  try {
+    const names = new Intl.DisplayNames([locale], { type: 'region', fallback: 'none' })
+    return names.of(code.toUpperCase()) ?? code
+  } catch {
+    return code
+  }
+}