@harshankur/viewcounter 3.0.1 → 3.1.0

package/admin/js/constants.js

@@ -0,0 +1,150 @@
+/**
+ * Front-end constants for the admin UI (CODE_STANDARDS.md §0/§1).
+ *
+ * Limits that the server enforces (batch size, field lengths, page sizes) are
+ * NOT duplicated here: the UI reads them from GET api/meta, so the two can
+ * never disagree. What lives here is either UI-only or part of the wire
+ * contract; the wire-contract values are checked against constants.js by
+ * tests/adminUiContract.test.js.
+ */
+
+/** Human-facing product name. Mirrors APP_NAME in the server constants. */
+export const APP_NAME = 'ViewCounter';
+
+/** Storage-key namespace. Mirrors APP_SLUG in the server constants. */
+export const APP_SLUG = 'viewcounter';
+
+/** Relative to the page, so the UI works wherever the router is mounted. */
+export const API_BASE = 'api';
+
+/** Must match ADMIN.CSRF_HEADER on the server. */
+export const CSRF_HEADER = 'x-csrf-token';
+
+/** Mirrors ADMIN_ERROR_CODE on the server. */
+export const ERROR_CODE = Object.freeze({
+    UNAUTHENTICATED: 'UNAUTHENTICATED',
+    INVALID_PASSWORD: 'INVALID_PASSWORD',
+    TOO_MANY_ATTEMPTS: 'TOO_MANY_ATTEMPTS',
+    RATE_LIMITED: 'RATE_LIMITED',
+    CSRF_REJECTED: 'CSRF_REJECTED',
+    VALIDATION_FAILED: 'VALIDATION_FAILED',
+    NOT_FOUND: 'NOT_FOUND',
+    SERVER_ERROR: 'SERVER_ERROR',
+    /** Client-side only: the request never got an answer. */
+    NETWORK: 'NETWORK',
+});
+
+/** Mirrors VIEW_STATUS on the server. */
+export const VIEW_STATUS = Object.freeze({
+    ACTIVE: 'active',
+    DELETED: 'deleted',
+    ALL: 'all',
+});
+
+/** Mirrors MODIFIED_FILTER on the server. */
+export const MODIFIED_FILTER = Object.freeze({
+    ANY: 'any',
+    MODIFIED: 'modified',
+    UNMODIFIED: 'unmodified',
+});
+
+export const SORT_ORDER = Object.freeze({
+    ASC: 'asc',
+    DESC: 'desc',
+});
+
+/** The sections of the UI. */
+export const TAB = Object.freeze({
+    VIEWS: 'views',
+    TRASH: 'trash',
+    ADMIN_LOG: 'adminLog',
+    VIEW_LOG: 'viewLog',
+});
+
+export const THEME = Object.freeze({
+    LIGHT: 'light',
+    DARK: 'dark',
+    AUTO: 'auto',
+});
+
+export const STORAGE_KEY = Object.freeze({
+    THEME: `${APP_SLUG}-admin-theme`,
+    LAST_APP: `${APP_SLUG}-admin-last-app`,
+    INSIGHTS_OPEN: `${APP_SLUG}-admin-insights-open`,
+});
+
+export const TOAST_DURATION_MS = 4000;
+
+/** Wait after the last keystroke before searching. */
+export const SEARCH_DEBOUNCE_MS = 300;
+
+export const DEFAULT_LOCALE = 'en';
+
+/** Every field a view row exposes, in display order for the details dialog. */
+export const VIEW_DETAIL_FIELDS = Object.freeze([
+    'id', 'timestamp', 'pagePath', 'pageTitle', 'referrer', 'referrerDomain', 'sourceType',
+    'deviceSize', 'deviceType', 'country', 'maskedIp', 'browser', 'browserVersion', 'os',
+    'osVersion', 'sessionId', 'eventType', 'eventData', 'isUnique', 'note', 'adminModifiedAt',
+    'deletedAt',
+]);
+
+/** Editable fields rendered as free text, and those rendered otherwise. */
+export const TEXT_FIELDS = Object.freeze(['pagePath', 'pageTitle', 'referrer', 'eventType']);
+export const DEVICE_SIZE_FIELD = 'deviceSize';
+export const EVENT_DATA_FIELD = 'eventData';
+
+/** Rows of the event-data editor. */
+export const EVENT_DATA_ROWS = 6;
+export const NOTE_ROWS = 4;
+
+/** Two-line clamp for page titles, one line for everything else. */
+export const CLAMP_LINES = Object.freeze({ SINGLE: 1, DOUBLE: 2 });
+
+/** Key names the keyboard handlers compare against. */
+export const KEY = Object.freeze({
+    ESCAPE: 'Escape',
+    ENTER: 'Enter',
+    SPACE: ' ',
+    TAB: 'Tab',
+    ARROW_UP: 'ArrowUp',
+    ARROW_DOWN: 'ArrowDown',
+    ARROW_LEFT: 'ArrowLeft',
+    ARROW_RIGHT: 'ArrowRight',
+    HOME: 'Home',
+    END: 'End',
+});
+
+/** Sentinel app selection meaning every app. Not a valid app ID ('*' is refused). */
+export const ALL_APPS = '*';
+
+/** Mirrors ADMIN_RANGE on the server. */
+export const RANGE = Object.freeze({
+    WEEK: '7d',
+    MONTH: '30d',
+    QUARTER: '90d',
+    YEAR: '1y',
+    ALL: 'all',
+});
+
+/** Geometry and limits for the insights charts. */
+export const CHART = Object.freeze({
+    TREND: Object.freeze({
+        WIDTH: 720,
+        HEIGHT: 220,
+        MARGIN: Object.freeze({ top: 12, right: 12, bottom: 28, left: 44 }),
+    }),
+    Y_TICKS: 4,
+    TICK_GAP: 8,
+    X_LABEL_GAP: 18,
+    /** r >= 4, so a marker is at least 8px across. */
+    DOT_RADIUS: 4,
+    TOOLTIP_OFFSET: 12,
+    /** Event types listed in a country's tooltip. */
+    TOOLTIP_TYPES: 4,
+    /** Sequential classes on the map; must match --map-1..5 in admin.css. */
+    MAP_CLASSES: 5,
+    COUNTRY_LIST_LIMIT: 10,
+});
+
+/** JSON indentation in the details and edit dialogs. */
+export const JSON_INDENT = 2;

package/admin/js/dom.js

@@ -0,0 +1,83 @@
+/**
+ * DOM construction helpers.
+ *
+ * Every value that came from the database is untrusted: page titles, paths,
+ * referrers, and event data are sent by anonymous visitors. This module is the
+ * only way the UI builds elements, and it only ever sets text through
+ * `textContent` and attributes through `setAttribute`. There is no path here,
+ * or anywhere in the UI, that parses a string as HTML; ESLint forbids
+ * innerHTML and its relatives under admin/.
+ */
+
+/**
+ * Create an element.
+ * @param {string} tag
+ * @param {{ className?: string, text?: string, attrs?: Record<string, string|number|boolean|null|undefined>,
+ *   on?: Record<string, EventListener>, dataset?: Record<string, string> }} [options]
+ * @param {Array<Node|string|null|undefined|false>} [children]
+ * @returns {HTMLElement}
+ */
+export function el(tag, { className, text, attrs = {}, on = {}, dataset = {} } = {}, children = []) {
+    const node = document.createElement(tag);
+    if (className) node.className = className;
+    if (text !== undefined && text !== null) node.textContent = String(text);
+    for (const [name, value] of Object.entries(attrs)) {
+        if (value === false || value === null || value === undefined) continue;
+        node.setAttribute(name, value === true ? '' : String(value));
+    }
+    for (const [name, value] of Object.entries(dataset)) node.dataset[name] = value;
+    for (const [event, handler] of Object.entries(on)) node.addEventListener(event, handler);
+    append(node, children);
+    return node;
+}
+
+/** Append children, turning strings into text nodes and skipping blanks. */
+export function append(parent, children) {
+    for (const child of children) {
+        if (child === null || child === undefined || child === false) continue;
+        parent.append(typeof child === 'string' ? document.createTextNode(child) : child);
+    }
+    return parent;
+}
+
+/** Remove every child. */
+export function clear(node) {
+    while (node.firstChild) node.firstChild.remove();
+    return node;
+}
+
+/** Replace a node's children in one step. */
+export function replaceChildren(node, children) {
+    clear(node);
+    return append(node, children);
+}
+
+/** @returns {HTMLElement} */
+export function byId(id) {
+    return document.getElementById(id);
+}
+
+/** Every focusable element inside `root`, in tab order. */
+export function focusableWithin(root) {
+    const selector = [
+        'a[href]', 'button:not([disabled])', 'input:not([disabled])', 'textarea:not([disabled])',
+        '[tabindex]:not([tabindex="-1"])',
+    ].join(',');
+    return [...root.querySelectorAll(selector)].filter((node) => !node.hidden && node.offsetParent !== null);
+}
+
+/** Debounce a function by `ms`. */
+export function debounce(fn, ms) {
+    let timer = null;
+    return (...args) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => fn(...args), ms);
+    };
+}
+
+let idCounter = 0;
+/** A document-unique id for ARIA relationships. */
+export function uniqueId(prefix) {
+    idCounter += 1;
+    return `${prefix}-${idCounter}`;
+}

package/admin/js/format.js

@@ -0,0 +1,79 @@
+/**
+ * Locale-aware formatting (FRONTEND.md §8: dates and numbers are localized
+ * too, not only strings).
+ */
+
+import { currentLocale, t } from './i18n.js';
+
+/** Intl time styles: with seconds, and without. */
+const TIME_STYLE = Object.freeze({ FULL: 'medium', SHORT: 'short' });
+
+function formatParts(value, options) {
+    if (value === null || value === undefined || value === '') return t('common.none');
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) return String(value);
+    return new Intl.DateTimeFormat(currentLocale(), options).format(date);
+}
+
+function formatWith(value, timeStyle) {
+    return formatParts(value, { dateStyle: 'medium', timeStyle });
+}
+
+/** Date and time to the second: logs and the details dialog. */
+export function formatDateTime(value) {
+    return formatWith(value, TIME_STYLE.FULL);
+}
+
+/** The date alone: the first line of a table's time cell. */
+export function formatDate(value) {
+    return formatParts(value, { dateStyle: 'medium' });
+}
+
+/**
+ * The time of day alone: the second line of a table's time cell. Logs keep the
+ * seconds, since they order events that can be moments apart.
+ */
+export function formatTime(value, { seconds = false } = {}) {
+    return formatParts(value, { timeStyle: seconds ? TIME_STYLE.FULL : TIME_STYLE.SHORT });
+}
+
+/** @param {number} value */
+export function formatNumber(value) {
+    return new Intl.NumberFormat(currentLocale()).format(Number(value) || 0);
+}
+
+/** 1,284 stays exact; 12,900 becomes 12.9K. */
+export function formatCompact(value) {
+    return new Intl.NumberFormat(currentLocale(), { notation: 'compact', maximumFractionDigits: 1 }).format(Number(value) || 0);
+}
+
+/** A ratio (0..1) as a percentage. */
+export function formatPercent(ratio) {
+    return new Intl.NumberFormat(currentLocale(), { style: 'percent', maximumFractionDigits: 1 }).format(Number(ratio) || 0);
+}
+
+/**
+ * A trend bucket label. Buckets are named by the date they start on
+ * (YYYY-MM-DD, from the server) and read as calendar dates, not instants, so
+ * they are formatted in UTC to avoid shifting a day across time zones.
+ * @param {string} period
+ * @param {'day'|'week'|'month'} bucket
+ * @param {{ long?: boolean }} [options] long adds the year, and "week of"
+ */
+export function formatPeriod(period, bucket, { long = false } = {}) {
+    const date = new Date(`${period}T00:00:00Z`);
+    if (Number.isNaN(date.getTime())) return period;
+    const locale = currentLocale();
+    if (bucket === 'month') {
+        return new Intl.DateTimeFormat(locale, { month: long ? 'long' : 'short', year: 'numeric', timeZone: 'UTC' }).format(date);
+    }
+    const day = new Intl.DateTimeFormat(locale, {
+        day: 'numeric', month: 'short', ...(long ? { year: 'numeric' } : {}), timeZone: 'UTC',
+    }).format(date);
+    return bucket === 'week' && long ? t('insights.weekOf', { date: day }) : day;
+}
+
+/** A value for display, with a translated placeholder for empty. */
+export function orNone(value) {
+    return value === null || value === undefined || value === '' ? t('common.none') : String(value);
+}

package/admin/js/i18n.js

@@ -0,0 +1,80 @@
+/**
+ * Translation layer (FRONTEND.md §8).
+ *
+ * Every user-visible string is a key resolved here. One locale ships today;
+ * adding another is a new file in locales/ with the same key set, which
+ * tests/adminUiContract.test.js enforces.
+ *
+ * Keys are dotted paths into the locale JSON. `{name}` placeholders are
+ * interpolated. When params include `count` and the key names an object with
+ * plural categories (`one`, `other`, ...), the category is chosen with
+ * Intl.PluralRules for the active locale.
+ */
+
+import { DEFAULT_LOCALE } from './constants.js';
+
+let messages = {};
+let locale = DEFAULT_LOCALE;
+let pluralRules = new Intl.PluralRules(DEFAULT_LOCALE);
+
+/** Load a locale bundle. Called once at startup. */
+export async function loadLocale(code = DEFAULT_LOCALE) {
+    const response = await fetch(`locales/${code}.json`, { credentials: 'same-origin' });
+    messages = await response.json();
+    locale = code;
+    pluralRules = new Intl.PluralRules(code);
+    document.documentElement.lang = code;
+}
+
+export function currentLocale() {
+    return locale;
+}
+
+function lookup(key) {
+    return key.split('.').reduce((node, part) => (node && typeof node === 'object' ? node[part] : undefined), messages);
+}
+
+/**
+ * Resolve a key.
+ * @param {string} key
+ * @param {Record<string, string|number>} [params]
+ * @returns {string} the translation, or the key itself if missing, so a gap
+ *   is visible on screen rather than silently blank
+ */
+export function t(key, params = {}) {
+    let entry = lookup(key);
+    if (entry && typeof entry === 'object' && typeof params.count === 'number') {
+        entry = entry[pluralRules.select(params.count)] ?? entry.other;
+    }
+    if (typeof entry !== 'string') return key;
+    return entry.replace(/\{(\w+)\}/g, (match, name) => (name in params ? String(params[name]) : match));
+}
+
+/**
+ * Resolve a key that may legitimately be absent, such as a device size or
+ * source type defined in the server's config rather than in this bundle, and
+ * fall back to the raw value instead of showing the key.
+ * @param {string} key
+ * @param {string} fallback
+ */
+export function tOr(key, fallback, params = {}) {
+    const result = t(key, params);
+    return result === key ? fallback : result;
+}
+
+/**
+ * Translate static markup: `data-i18n` sets text, `data-i18n-attr` sets
+ * attributes as `attr:key;attr:key`.
+ * @param {ParentNode} root
+ */
+export function applyTranslations(root = document) {
+    for (const node of root.querySelectorAll('[data-i18n]')) {
+        node.textContent = t(node.dataset.i18n);
+    }
+    for (const node of root.querySelectorAll('[data-i18n-attr]')) {
+        for (const pair of node.dataset.i18nAttr.split(';')) {
+            const [attr, key] = pair.split(':').map((part) => part.trim());
+            if (attr && key) node.setAttribute(attr, t(key));
+        }
+    }
+}

package/admin/js/insights.js

@@ -0,0 +1,192 @@
+/**
+ * The insights panel above the views table: headline numbers, views over
+ * time, a world map, and breakdowns, for exactly the rows the table's filters
+ * select (one app or all, date range, search, modified filter).
+ */
+
+import { api } from './api.js';
+import { barList, statTiles, trendChart, trendTable, worldMap } from './charts.js';
+import { el, replaceChildren, uniqueId } from './dom.js';
+import { formatDateTime } from './format.js';
+import { t, tOr } from './i18n.js';
+import { ALL_APPS, STORAGE_KEY } from './constants.js';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Breakdown cards, in display order; `allOnly` cards appear for every app at once. */
+const BREAKDOWNS = [
+    { dim: 'source', label: (v) => (v === null ? t('insights.unknown') : tOr(`sources.${v}`, v)) },
+    { dim: 'deviceSize', label: (v) => (v === null ? t('insights.unknown') : tOr(`deviceSizes.${v}`, v)) },
+    { dim: 'browser', label: (v) => v ?? t('insights.unknown') },
+    { dim: 'os', label: (v) => v ?? t('insights.unknown') },
+    { dim: 'eventType', label: (v) => (v === null ? t('insights.unknown') : tOr(`eventTypes.${v}`, v)) },
+    { dim: 'app', label: (v) => v ?? t('insights.unknown'), allOnly: true },
+];
+
+/** The date after `period` by one bucket, as YYYY-MM-DD. */
+function nextPeriod(period, bucket) {
+    const date = new Date(`${period}T00:00:00Z`);
+    if (bucket === 'month') date.setUTCMonth(date.getUTCMonth() + 1);
+    else date.setTime(date.getTime() + (bucket === 'week' ? 7 : 1) * DAY_MS);
+    return date.toISOString().slice(0, 10);
+}
+
+/**
+ * Insert zero-count buckets between the first and last period, so a quiet
+ * day reads as a dip rather than disappearing from the line.
+ */
+export function fillGaps(trend, bucket) {
+    if (trend.length < 2) return trend;
+    const byPeriod = new Map(trend.map((point) => [point.period, point]));
+    const filled = [];
+    const last = trend[trend.length - 1].period;
+    for (let period = trend[0].period; period <= last; period = nextPeriod(period, bucket)) {
+        filled.push(byPeriod.get(period) || { period, views: 0, uniqueViews: 0 });
+    }
+    return filled;
+}
+
+function readOpen() {
+    try {
+        return localStorage.getItem(STORAGE_KEY.INSIGHTS_OPEN) !== 'false';
+    } catch {
+        return true;
+    }
+}
+
+function storeOpen(open) {
+    try {
+        localStorage.setItem(STORAGE_KEY.INSIGHTS_OPEN, String(open));
+    } catch {
+        // Storage blocked: the panel simply opens by default next time.
+    }
+}
+
+/** A titled card; `control` sits in the header, beside the title. */
+function card(titleKey, body, control, className = '') {
+    const titleId = uniqueId('chart-title');
+    return el('section', { className: `chart-card ${className}`.trim(), attrs: { 'aria-labelledby': titleId } }, [
+        el('header', { className: 'chart-card-header' }, [
+            el('h3', { className: 'chart-title', text: t(titleKey), attrs: { id: titleId } }),
+            control,
+        ]),
+        body,
+    ]);
+}
+
+/**
+ * @param {{ reportError: (error: unknown) => void, onData?: (data: object) => void }} deps
+ *   onData receives each analysis, so the filter row can offer the event types seen
+ */
+export function createInsightsPanel({ reportError, onData = () => {} }) {
+    let open = readOpen();
+    let seq = 0;
+    let data = null;
+    let showTrendTable = false;
+    let allApps = false;
+
+    const bodyId = uniqueId('insights-body');
+    const toggle = el('button', {
+        className: 'insights-toggle',
+        attrs: { type: 'button', 'aria-expanded': String(open), 'aria-controls': bodyId },
+    }, [
+        el('span', { className: 'prompt-char', text: '❯', attrs: { 'aria-hidden': 'true' } }),
+        el('span', { text: t('insights.title') }),
+        el('span', { className: 'insights-caret', text: '▾', attrs: { 'aria-hidden': 'true' } }),
+    ]);
+    const caption = el('span', { className: 'insights-caption' });
+    const body = el('div', { className: 'insights-body', attrs: { id: bodyId } });
+    body.hidden = !open;
+
+    const element = el('section', { className: 'insights', attrs: { 'aria-label': t('insights.title') } }, [
+        el('div', { className: 'insights-header' }, [toggle, caption]),
+        body,
+    ]);
+
+    toggle.addEventListener('click', () => {
+        open = !open;
+        storeOpen(open);
+        toggle.setAttribute('aria-expanded', String(open));
+        body.hidden = !open;
+        if (open) render();
+    });
+
+    function trendCard() {
+        const points = fillGaps(data.trend, data.bucket);
+        const tableToggle = el('button', {
+            className: 'btn btn-ghost btn-small',
+            text: showTrendTable ? t('insights.showChart') : t('insights.showTable'),
+            attrs: { type: 'button', 'aria-pressed': String(showTrendTable) },
+            on: { click: () => {
+                showTrendTable = !showTrendTable;
+                render();
+            } },
+        });
+        // The last bucket is still filling up if it has not ended yet, so its
+        // dip is not a real decline; the tooltip says "so far".
+        const lastPeriod = points[points.length - 1]?.period;
+        const lastInProgress = Boolean(lastPeriod) && nextPeriod(lastPeriod, data.bucket) > new Date().toISOString().slice(0, 10);
+        const content = showTrendTable
+            ? el('div', { className: 'chart-body chart-table-wrap' }, [trendTable({ points, bucket: data.bucket })])
+            : trendChart({ points, bucket: data.bucket, lastInProgress });
+        return card('insights.trendTitle', content, tableToggle, 'chart-trend');
+    }
+
+    function mapCard() {
+        // Every type, or the one chosen in the filter row above: the rows are
+        // already filtered by the server, so the map just shows them.
+        return card('insights.mapTitle', worldMap({ countries: data.countries, type: null }), null, 'chart-map');
+    }
+
+    function render() {
+        if (!open || !data) return;
+        const { totals } = data;
+        const period = totals.firstAt
+            ? t('insights.span', { from: formatDateTime(totals.firstAt), to: formatDateTime(totals.lastAt) })
+            : t('insights.noData');
+
+        replaceChildren(body, [
+            statTiles([
+                { label: t('insights.views'), value: totals.views },
+                { label: t('insights.visitors'), value: totals.visitors },
+                { label: t('insights.uniqueShare'), value: totals.views ? totals.uniqueViews / totals.views : 0, format: 'percent' },
+                { label: t('insights.countries'), value: totals.countries },
+                { label: t('insights.modified'), value: totals.modified },
+            ]),
+            el('p', { className: 'insights-span', text: period }),
+            el('div', { className: 'insights-grid' }, [trendCard(), mapCard()]),
+            el('div', { className: 'breakdown-grid' }, BREAKDOWNS
+                .filter((breakdown) => !breakdown.allOnly || allApps)
+                .map((breakdown) => card(`insights.breakdown.${breakdown.dim}`, barList({
+                    entries: data.breakdowns[breakdown.dim],
+                    total: totals.views,
+                    labelFor: breakdown.label,
+                })))),
+        ]);
+    }
+
+    /**
+     * Fetch and draw the analysis for a filter set. The previous render stays
+     * up, dimmed, until the new one arrives: no flash, no layout jump.
+     * @param {{ appId: string, status: string, modified: string, search: string, range: string }} query
+     */
+    async function load({ appId, ...filters }) {
+        const mine = ++seq;
+        allApps = appId === ALL_APPS;
+        caption.textContent = allApps ? t('insights.scopeAll') : t('insights.scopeApp', { app: appId });
+        element.classList.add('loading');
+        try {
+            const result = allApps ? await api.analyticsAll(filters) : await api.analytics(appId, filters);
+            if (mine !== seq) return;
+            data = result;
+            onData(result);
+            render();
+        } catch (error) {
+            if (mine === seq) reportError(error);
+        } finally {
+            if (mine === seq) element.classList.remove('loading');
+        }
+    }
+
+    return { element, load };
+}