@byline/admin 5.1.3 → 5.2.0

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

package/dist/exports-parity.test.node.js

@@ -1,37 +0,0 @@
-/**
- * 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
- */
-/**
- * Guard against `publishConfig.exports` drift.
- *
- * `@byline/admin` carries a `publishConfig.exports` block that npm uses to
- * **override** the top-level `exports` at publish time. The workspace and dev
- * builds resolve through the top-level `exports` (or source), so a subpath
- * added there but forgotten in `publishConfig.exports` typechecks and builds
- * locally yet is **missing from the published package** — surfacing only as a
- * downstream consumer's build error ("X is not exported …"). That is exactly
- * how `./admin-activity` slipped through in v3.11.0.
- *
- * This test fails the moment the two blocks drift, so the gap is caught in
- * `pnpm test` / CI rather than in a production Docker build.
- */
-import { readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { describe, expect, it } from 'vitest';
-const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), '../package.json');
-const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-describe('package.json export parity', () => {
-    it('every top-level export subpath is also declared in publishConfig.exports', () => {
-        const publishExports = pkg.publishConfig?.exports;
-        // If there is no override, the top-level exports ship as-is — nothing to check.
-        if (publishExports == null)
-            return;
-        const missing = Object.keys(pkg.exports).filter((key) => !(key in publishExports));
-        expect(missing, `publishConfig.exports is missing subpath(s) present in the top-level exports: ${missing.join(', ')}. The published package would not expose them — add them to BOTH blocks.`).toEqual([]);
-    });
-});

package/dist/fields/array/array-field.jsx

@@ -1,209 +0,0 @@
-/**
- * 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 { useEffect, useState } from 'react';
-import { useTranslation } from '@byline/i18n/react';
-import { DraggableSortable, IconButton, moveItem, PlusIcon } from '@byline/ui/react';
-import cx from 'clsx';
-import { sliceFieldAdmin } from '../../fields/field-admin';
-import { defaultScalarForField } from '../../fields/field-helpers';
-import { FieldRenderer } from '../../fields/field-renderer';
-import { SortableItem, StaticItem } from '../../fields/sortable-item';
-import { useFormContext } from '../../forms/form-context';
-import { hasExistingIdTargets } from '../../forms/nested-path';
-import { moveRepeatingItems, repeatingItemId, repeatingItemPath } from '../../forms/repeating-items';
-import styles from './array-field.module.css';
-// ---------------------------------------------------------------------------
-// ArrayField — renders `type: 'array'` fields. Each item renders every child
-// field declared in the array's `fields` (value fields and/or groups, in any
-// combination). Supports D&D.
-// ---------------------------------------------------------------------------
-export const ArrayField = ({ field, defaultValue, path, disableSorting = false, contentLocale, fieldAdmin, }) => {
-    const { appendPatch, getFieldValue, getFieldValues, removePendingUploadsUnder, setFieldStore } = useFormContext();
-    const { t } = useTranslation('byline-admin');
-    const [items, setItems] = useState([]);
-    useEffect(() => {
-        // Prefer the live form-store value over `defaultValue` when seeding the
-        // rendered list. The store lives in FormProvider — above the tab layout —
-        // so it survives this field unmounting/remounting as the editor switches
-        // tabs; `defaultValue` is only the initial seed and is empty in create
-        // mode. Re-seeding from `defaultValue` on remount would drop items the
-        // editor had already added on an earlier visit to this tab.
-        const storeValue = getFieldValue(path);
-        const source = Array.isArray(storeValue) ? storeValue : defaultValue;
-        if (Array.isArray(source)) {
-            setItems(source.map((item) => ({
-                id: item && typeof item === 'object' && '_id' in item
-                    ? String(item._id)
-                    : item && typeof item === 'object' && 'id' in item
-                        ? String(item.id)
-                        : crypto.randomUUID(),
-                data: item,
-            })));
-        }
-        else {
-            setItems([]);
-        }
-    }, [defaultValue, getFieldValue, path]);
-    const handleDragEnd = ({ moveFromIndex, moveToIndex, }) => {
-        const currentArray = (getFieldValue(path) ?? defaultValue);
-        if (!Array.isArray(currentArray))
-            return;
-        const move = moveRepeatingItems(currentArray, moveFromIndex, moveToIndex);
-        if (move == null)
-            return;
-        setItems((prev) => moveItem(prev, move.fromIndex, move.toIndex));
-        setFieldStore(path, move.items);
-        appendPatch({
-            kind: 'array.move',
-            path,
-            itemId: move.itemId,
-            toIndex: move.toIndex,
-        });
-    };
-    const handleAddItem = async (atIndex) => {
-        const childFields = field.fields ?? [];
-        if (childFields.length === 0)
-            return;
-        const newId = crypto.randomUUID();
-        // Build a new item with default values for ALL child fields.
-        // Assign the stable `_id` client-side — exactly like BlocksField's
-        // handleAddItem — so the item is patch-addressable (move / remove by
-        // `_id`) within the same editing session, before any server write has
-        // assigned identity. The storage layer persists `_id` via store_meta.
-        const newItem = { _id: newId };
-        for (const childField of childFields) {
-            if (childField.type === 'group' && childField.fields && childField.fields.length > 0) {
-                // Group child — build a nested object with defaults for each inner field
-                const groupObj = {};
-                for (const innerField of childField.fields) {
-                    groupObj[innerField.name] = await defaultScalarForField(innerField, getFieldValues);
-                }
-                newItem[childField.name] = groupObj;
-            }
-            else {
-                newItem[childField.name] = await defaultScalarForField(childField, getFieldValues);
-            }
-        }
-        // Defaults may resolve asynchronously. If an enclosing stable-id item was
-        // removed in the meantime, do not append a structural patch that would
-        // recreate that missing parent on the server.
-        if (!hasExistingIdTargets(getFieldValues(), path))
-            return;
-        const currentArray = (getFieldValue(path) ?? defaultValue);
-        const insertAt = atIndex != null ? atIndex : currentArray ? currentArray.length : 0;
-        const newItemWrapper = { id: newId, data: newItem };
-        setItems((prev) => {
-            const next = [...prev];
-            next.splice(insertAt, 0, newItemWrapper);
-            return next;
-        });
-        appendPatch({
-            kind: 'array.insert',
-            path: path,
-            index: insertAt,
-            item: newItem,
-        });
-        const newArrayValue = currentArray ? [...currentArray] : [];
-        newArrayValue.splice(insertAt, 0, newItem);
-        setFieldStore(path, newArrayValue);
-    };
-    const handleRemoveItem = (index) => {
-        const currentArray = (getFieldValue(path) ?? defaultValue);
-        if (!Array.isArray(currentArray) || index < 0 || index >= currentArray.length)
-            return;
-        const item = currentArray[index];
-        const itemPath = repeatingItemPath(path, item, index);
-        setItems((prev) => prev.filter((_, i) => i !== index));
-        removePendingUploadsUnder(itemPath);
-        appendPatch({
-            kind: 'array.remove',
-            path: path,
-            itemId: repeatingItemId(item) ?? String(index),
-        });
-        const newArrayValue = [...currentArray];
-        newArrayValue.splice(index, 1);
-        setFieldStore(path, newArrayValue);
-    };
-    const handleInsertBelow = (index) => {
-        void handleAddItem(index + 1);
-    };
-    const renderItem = (itemWrapper, index) => {
-        const item = itemWrapper.data;
-        const arrayElementPath = repeatingItemPath(path, item, index);
-        if (!item || typeof item !== 'object')
-            return null;
-        const childFields = field.fields ?? [];
-        if (childFields.length === 0)
-            return null;
-        // Render ALL child fields defined in the array's field schema
-        const innerBody = childFields.map((childField) => {
-            const initial = item[childField.name];
-            if (childField.type === 'group' && childField.fields && childField.fields.length > 0) {
-                // Group child — render its inner fields with the group's sub-object.
-                // fieldAdmin slices one level per structural hop: the group's
-                // descendant map first, then each inner field's own slice.
-                const groupData = initial && typeof initial === 'object' ? initial : {};
-                const groupAdmin = sliceFieldAdmin(fieldAdmin, childField.name);
-                return (<div key={childField.name} className={cx('byline-field-array-group-fields', styles['group-fields'])}>
-            {childField.label && (<h4 className={cx('byline-field-array-group-header', styles['group-header'])}>
-                {childField.label}
-              </h4>)}
-            {childField.fields.map((innerField) => (<FieldRenderer key={innerField.name} field={innerField} defaultValue={groupData[innerField.name]} basePath={`${arrayElementPath}.${childField.name}`} disableSorting={true} contentLocale={contentLocale} components={groupAdmin?.[innerField.name]?.components} editor={groupAdmin?.[innerField.name]?.editor} fieldAdmin={sliceFieldAdmin(groupAdmin, innerField.name)}/>))}
-          </div>);
-            }
-            return (<FieldRenderer key={childField.name} field={childField} defaultValue={initial} basePath={arrayElementPath} disableSorting={true} contentLocale={contentLocale} components={fieldAdmin?.[childField.name]?.components} editor={fieldAdmin?.[childField.name]?.editor} fieldAdmin={sliceFieldAdmin(fieldAdmin, childField.name)}/>);
-        });
-        // Per-item label: the array label plus a 1-based position, so items
-        // read "Questions 1", "Questions 2" rather than all repeating the bare
-        // array label.
-        const itemLabel = `${field.label ?? field.name} ${index + 1}`;
-        // `disableSorting` removes only the drag affordance. Structural editing
-        // (add-below / remove / collapse) is always available — StaticItem is
-        // the grip-less sibling of SortableItem (see sortable-item.tsx for why
-        // it is a separate component rather than a prop).
-        if (disableSorting) {
-            return (<StaticItem key={itemWrapper.id} label={itemLabel} onAddBelow={() => handleInsertBelow(index)} onRemove={() => handleRemoveItem(index)}>
-          <div className={cx('byline-field-array-group-fields', styles['group-fields'])}>
-            {innerBody}
-          </div>
-        </StaticItem>);
-        }
-        return (<SortableItem key={itemWrapper.id} id={itemWrapper.id} label={itemLabel} onAddBelow={() => handleInsertBelow(index)} onRemove={() => handleRemoveItem(index)}>
-        <div className={cx('byline-field-array-group-fields', styles['group-fields'])}>
-          {innerBody}
-        </div>
-      </SortableItem>);
-    };
-    // The add-row renders in both branches — structural editing does not
-    // depend on sortability.
-    const addRow = (<div className={cx('byline-field-array-add-row', styles['add-row'])}>
-      <IconButton onClick={() => {
-            void handleAddItem();
-        }} aria-label={t('fields.array.addItemAriaLabel')}>
-        <PlusIcon />
-      </IconButton>
-      {/* Text-styled button so the label is clickable too. Removed from
-            the tab order (tabIndex -1) — the IconButton is the single
-            keyboard/screen-reader control for this action. */}
-      <button type="button" tabIndex={-1} onClick={() => {
-            void handleAddItem();
-        }} className={cx('byline-field-array-add-label', styles['add-label'])}>
-        {t('fields.array.addItem')}
-      </button>
-    </div>);
-    return (<div className={`byline-field-array ${field.name}`}>
-      {field.label && (<h3 className={cx('byline-field-array-title', styles.title)}>{field.label}</h3>)}
-      {disableSorting ? (<div className={cx('byline-field-array-stack', styles.stack)}>
-          {items.map((item, index) => renderItem(item, index))}
-          {addRow}
-        </div>) : (<DraggableSortable ids={items.map((i) => i.id)} onDragEnd={handleDragEnd} className={cx('byline-field-array-stack', styles.stack)}>
-          {items.map((item, index) => renderItem(item, index))}
-          {addRow}
-        </DraggableSortable>)}
-    </div>);
-};