@harshankur/viewcounter 3.0.1 → 3.2.0

package/admin/js/format.js

@@ -0,0 +1,130 @@
+/**
+ * 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 headline count: exact below ten thousand (1,029), compact above (12.9K). */
+export function formatHeadline(value) {
+    return Math.abs(Number(value) || 0) < 10000 ? formatNumber(value) : formatCompact(value);
+}
+
+/** 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 number with at most `digits` decimals: 1.75 pages per visit reads 1.8. */
+export function formatDecimal(value, digits = 1) {
+    return new Intl.NumberFormat(currentLocale(), { maximumFractionDigits: digits }).format(Number(value) || 0);
+}
+
+function unit(value, name) {
+    return new Intl.NumberFormat(currentLocale(), { style: 'unit', unit: name, unitDisplay: 'narrow' }).format(value);
+}
+
+/**
+ * A duration, to the second below an hour: 45s, 3m 20s, 1h 5m. Empty
+ * (never measured) shows the placeholder rather than a misleading 0s.
+ * @param {number|null} ms
+ */
+export function formatDuration(ms) {
+    if (ms === null || ms === undefined || Number.isNaN(Number(ms))) return t('common.none');
+    const seconds = Math.round(Number(ms) / 1000);
+    if (seconds < 60) return unit(seconds, 'second');
+    if (seconds < 3600) {
+        const rest = seconds % 60;
+        return rest ? `${unit(Math.floor(seconds / 60), 'minute')} ${unit(rest, 'second')}` : unit(seconds / 60, 'minute');
+    }
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const hours = Math.floor(seconds / 3600);
+    return minutes ? `${unit(hours, 'hour')} ${unit(minutes, 'minute')}` : unit(hours, 'hour');
+}
+
+/**
+ * When a trend bucket starts. Day, week, and month buckets are named by their
+ * date (YYYY-MM-DD) and read as calendar dates at UTC midnight; hour buckets
+ * ("YYYY-MM-DD HH:00") are instants in the server's clock, which is UTC.
+ * @param {string} period
+ * @param {'hour'|'day'|'week'|'month'} bucket
+ * @returns {Date}
+ */
+export function periodStart(period, bucket) {
+    return bucket === 'hour'
+        ? new Date(`${String(period).replace(' ', 'T')}:00Z`)
+        : new Date(`${period}T00:00:00Z`);
+}
+
+/**
+ * A trend bucket label. Calendar buckets are formatted in UTC so a day never
+ * shifts across time zones; an hour is an instant, shown in local time.
+ * @param {string} period
+ * @param {'hour'|'day'|'week'|'month'} bucket
+ * @param {{ long?: boolean }} [options] long adds the date to an hour, the year
+ *   to a day, and "week of" to a week
+ */
+export function formatPeriod(period, bucket, { long = false } = {}) {
+    const date = periodStart(period, bucket);
+    if (Number.isNaN(date.getTime())) return period;
+    const locale = currentLocale();
+    if (bucket === 'hour') {
+        return new Intl.DateTimeFormat(locale, {
+            ...(long ? { day: 'numeric', month: 'short' } : {}), hour: 'numeric', minute: '2-digit',
+        }).format(date);
+    }
+    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('charts.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/icons.js

@@ -0,0 +1,168 @@
+/**
+ * The UI's icons: small line drawings on a 24-unit grid, built as SVG
+ * elements (never parsed from markup), stroked in the text colour around
+ * them. An icon is always decoration: the control it sits in carries the
+ * accessible name.
+ */
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/**
+ * Each icon is a list of [tag, attributes]. Paths are open line drawings;
+ * `fill: true` marks the few shapes that are solid.
+ */
+const ICONS = {
+    overview: [
+        ['rect', { x: 3, y: 3, width: 7, height: 9, rx: 1.5 }],
+        ['rect', { x: 14, y: 3, width: 7, height: 5, rx: 1.5 }],
+        ['rect', { x: 14, y: 12, width: 7, height: 9, rx: 1.5 }],
+        ['rect', { x: 3, y: 16, width: 7, height: 5, rx: 1.5 }],
+    ],
+    views: [
+        ['rect', { x: 3, y: 4, width: 18, height: 16, rx: 2 }],
+        ['path', { d: 'M3 9.5h18M3 15h18M9 9.5V20' }],
+    ],
+    trash: [
+        ['path', { d: 'M4 7h16M10 11v6M14 11v6M9 7V4.5h6V7M6 7l1 12a2 2 0 0 0 2 2h6a2 2 0 0 0 2-2l1-12' }],
+    ],
+    trackingLog: [
+        ['path', { d: 'M3 12h4l3-7 4 14 3-7h4' }],
+    ],
+    adminLog: [
+        ['path', { d: 'M12 3l7 3v5c0 4.6-3 8.4-7 10-4-1.6-7-5.4-7-10V6z' }],
+        ['path', { d: 'M9 12l2 2 4-4' }],
+    ],
+    sun: [
+        ['circle', { cx: 12, cy: 12, r: 4 }],
+        ['path', { d: 'M12 2.5v2M12 19.5v2M2.5 12h2M19.5 12h2M5.3 5.3l1.4 1.4M17.3 17.3l1.4 1.4M5.3 18.7l1.4-1.4M17.3 6.7l1.4-1.4' }],
+    ],
+    moon: [
+        ['path', { d: 'M20 14.5A8 8 0 1 1 9.5 4a6.5 6.5 0 0 0 10.5 10.5z' }],
+    ],
+    auto: [
+        ['circle', { cx: 12, cy: 12, r: 8.5 }],
+        ['path', { d: 'M12 3.5a8.5 8.5 0 0 1 0 17z', fill: true }],
+    ],
+    signOut: [
+        ['path', { d: 'M9 4H6a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h3M15 16.5l4.5-4.5L15 7.5M19.5 12H9' }],
+    ],
+    external: [
+        ['path', { d: 'M14 4h6v6M20 4l-9 9M18 14v4a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h4' }],
+    ],
+    globe: [
+        ['circle', { cx: 12, cy: 12, r: 9 }],
+        ['path', { d: 'M3 12h18M12 3c2.5 2.6 3.8 5.6 3.8 9s-1.3 6.4-3.8 9c-2.5-2.6-3.8-5.6-3.8-9S9.5 5.6 12 3z' }],
+    ],
+    book: [
+        ['path', { d: 'M5 5.5A2.5 2.5 0 0 1 7.5 3H19v15H7.5A2.5 2.5 0 0 0 5 20.5zM5 20.5A2.5 2.5 0 0 0 7.5 21H19v-3' }],
+    ],
+    code: [
+        ['path', { d: 'M8.5 7L3.5 12l5 5M15.5 7l5 5-5 5' }],
+    ],
+    package: [
+        ['path', { d: 'M12 3l8 4.5v9L12 21l-8-4.5v-9zM4 7.5l8 4.5 8-4.5M12 12v9' }],
+    ],
+    info: [
+        ['circle', { cx: 12, cy: 12, r: 9 }],
+        ['path', { d: 'M12 11v5.5M12 7.6v.1' }],
+    ],
+    edit: [
+        ['path', { d: 'M4 20h4L19 9l-4-4L4 16zM13.5 6.5l4 4' }],
+    ],
+    note: [
+        ['path', { d: 'M5 4h14v10.5L14.5 19H5zM14 19v-4.5h5M8.5 8.5h7M8.5 12h4' }],
+    ],
+    restore: [
+        ['path', { d: 'M3.5 12a8.5 8.5 0 1 0 2.6-6.1M3.5 4v4.5H8' }],
+    ],
+    purge: [
+        ['circle', { cx: 12, cy: 12, r: 9 }],
+        ['path', { d: 'M9 9l6 6M15 9l-6 6' }],
+    ],
+    chevronDown: [
+        ['path', { d: 'M6 9l6 6 6-6' }],
+    ],
+    chevronRight: [
+        ['path', { d: 'M9 6l6 6-6 6' }],
+    ],
+    columns: [
+        ['rect', { x: 3, y: 4, width: 18, height: 16, rx: 2 }],
+        ['path', { d: 'M9 4v16M15 4v16' }],
+    ],
+    arrowUp: [
+        ['path', { d: 'M12 19V5M6 11l6-6 6 6' }],
+    ],
+    arrowDown: [
+        ['path', { d: 'M12 5v14M6 13l6 6 6-6' }],
+    ],
+    sort: [
+        ['path', { d: 'M8 5v14M4.5 8.5L8 5l3.5 3.5M16 19V5M12.5 15.5L16 19l3.5-3.5' }],
+    ],
+    table: [
+        ['rect', { x: 3, y: 4, width: 18, height: 16, rx: 2 }],
+        ['path', { d: 'M3 9.5h18M3 14.8h18M10 9.5V20' }],
+    ],
+    chart: [
+        ['path', { d: 'M4 4v16h16M7.5 15l4-4.5 3 3L20 7' }],
+    ],
+    refresh: [
+        ['path', { d: 'M20 12a8 8 0 1 1-2.4-5.7M20 4v5h-5' }],
+    ],
+    close: [
+        ['path', { d: 'M6 6l12 12M18 6L6 18' }],
+    ],
+    filter: [
+        ['path', { d: 'M4 5h16l-6.2 7.2V18l-3.6 2v-7.8z' }],
+    ],
+    arrowRight: [
+        ['path', { d: 'M5 12h14M13 6l6 6-6 6' }],
+    ],
+    pause: [
+        ['path', { d: 'M9 5.5v13M15 5.5v13' }],
+    ],
+    play: [
+        ['path', { d: 'M7.5 5.5l11 6.5-11 6.5z', fill: true }],
+    ],
+    clock: [
+        ['circle', { cx: 12, cy: 12, r: 9 }],
+        ['path', { d: 'M12 7v5l3 2' }],
+    ],
+};
+
+/** Every icon name, for tests and for callers that pick one by key. */
+export const ICON_NAMES = Object.freeze(Object.keys(ICONS));
+
+/**
+ * Build an icon.
+ * @param {string} name a key of ICONS
+ * @param {{ className?: string }} [options]
+ * @returns {SVGSVGElement}
+ */
+export function icon(name, { className = '' } = {}) {
+    const shapes = ICONS[name];
+    if (!shapes) throw new Error(`Unknown icon: ${name}`);
+    const root = document.createElementNS(SVG_NS, 'svg');
+    const attrs = {
+        class: `icon icon-${name} ${className}`.trim(),
+        viewBox: '0 0 24 24',
+        width: '16',
+        height: '16',
+        fill: 'none',
+        stroke: 'currentColor',
+        'stroke-width': '1.8',
+        'stroke-linecap': 'round',
+        'stroke-linejoin': 'round',
+        'aria-hidden': 'true',
+        focusable: 'false',
+    };
+    for (const [key, value] of Object.entries(attrs)) root.setAttribute(key, value);
+    for (const [tag, shapeAttrs] of shapes) {
+        const shape = document.createElementNS(SVG_NS, tag);
+        for (const [key, value] of Object.entries(shapeAttrs)) {
+            if (key === 'fill') shape.setAttribute('fill', 'currentColor');
+            else shape.setAttribute(key, String(value));
+        }
+        root.append(shape);
+    }
+    return root;
+}

package/admin/js/listbox.js

@@ -0,0 +1,145 @@
+/**
+ * A select replacement (FRONTEND.md §0, §7): a button that opens a listbox the
+ * page renders itself, so it can be styled and behaves identically on every
+ * machine.
+ *
+ * ARIA listbox pattern: the button has aria-haspopup/aria-expanded; the
+ * options carry role=option and aria-selected; the active option is announced
+ * through aria-activedescendant. Keyboard: ArrowUp/ArrowDown move, Home/End
+ * jump, Enter/Space commit, Escape and Tab close.
+ */
+
+import { el, clear, uniqueId } from './dom.js';
+import { icon } from './icons.js';
+import { KEY } from './constants.js';
+
+/**
+ * @param {{ label: string, options: Array<{value: string, label: string}>, value?: string,
+ *   onChange?: (value: string) => void, className?: string }} config
+ * @returns {{ element: HTMLElement, getValue: () => string, setValue: (value: string) => void,
+ *   setOptions: (options: Array<{value: string, label: string}>, value?: string) => void }}
+ */
+export function createListbox({ label, options, value, onChange = () => {}, className = '' }) {
+    const listId = uniqueId('listbox');
+    let items = options;
+    let selected = value ?? options[0]?.value;
+    let activeIndex = -1;
+
+    const valueText = el('span', { className: 'listbox-value' });
+    const button = el('button', {
+        className: 'listbox-button',
+        attrs: { type: 'button', 'aria-haspopup': 'listbox', 'aria-expanded': 'false', 'aria-label': label },
+    }, [valueText, icon('chevronDown', { className: 'listbox-caret' })]);
+
+    const list = el('ul', {
+        className: 'listbox-popup',
+        attrs: { role: 'listbox', id: listId, tabindex: '-1', 'aria-label': label },
+    });
+    list.hidden = true;
+    button.setAttribute('aria-controls', listId);
+
+    const wrapper = el('div', { className: `listbox ${className}`.trim() }, [button, list]);
+
+    const labelOf = (v) => items.find((item) => item.value === v)?.label ?? '';
+
+    function render() {
+        valueText.textContent = labelOf(selected);
+        clear(list);
+        items.forEach((item, index) => {
+            const isSelected = item.value === selected;
+            list.append(el('li', {
+                className: `listbox-option${index === activeIndex ? ' active' : ''}`,
+                text: item.label,
+                attrs: { role: 'option', id: `${listId}-${index}`, 'aria-selected': String(isSelected) },
+                on: {
+                    mousedown: (event) => event.preventDefault(),
+                    click: () => commit(index),
+                },
+            }));
+        });
+        if (activeIndex >= 0) list.setAttribute('aria-activedescendant', `${listId}-${activeIndex}`);
+        else list.removeAttribute('aria-activedescendant');
+    }
+
+    function isOpen() {
+        return !list.hidden;
+    }
+
+    function open() {
+        if (isOpen()) return;
+        activeIndex = Math.max(0, items.findIndex((item) => item.value === selected));
+        list.hidden = false;
+        button.setAttribute('aria-expanded', 'true');
+        render();
+        list.focus();
+        list.querySelector('.active')?.scrollIntoView({ block: 'nearest' });
+        document.addEventListener('mousedown', onOutside, true);
+    }
+
+    function close({ refocus = true } = {}) {
+        if (!isOpen()) return;
+        list.hidden = true;
+        button.setAttribute('aria-expanded', 'false');
+        activeIndex = -1;
+        document.removeEventListener('mousedown', onOutside, true);
+        if (refocus) button.focus();
+    }
+
+    function commit(index) {
+        const item = items[index];
+        if (!item) return;
+        const changed = item.value !== selected;
+        selected = item.value;
+        close();
+        render();
+        if (changed) onChange(selected);
+    }
+
+    function move(index) {
+        activeIndex = Math.min(Math.max(index, 0), items.length - 1);
+        render();
+        list.querySelector('.active')?.scrollIntoView({ block: 'nearest' });
+    }
+
+    function onOutside(event) {
+        if (!wrapper.contains(event.target)) close({ refocus: false });
+    }
+
+    button.addEventListener('click', () => (isOpen() ? close() : open()));
+    button.addEventListener('keydown', (event) => {
+        if (event.key === KEY.ARROW_DOWN || event.key === KEY.ARROW_UP) {
+            event.preventDefault();
+            open();
+        }
+    });
+
+    list.addEventListener('keydown', (event) => {
+        switch (event.key) {
+            case KEY.ARROW_DOWN: event.preventDefault(); move(activeIndex + 1); break;
+            case KEY.ARROW_UP: event.preventDefault(); move(activeIndex - 1); break;
+            case KEY.HOME: event.preventDefault(); move(0); break;
+            case KEY.END: event.preventDefault(); move(items.length - 1); break;
+            case KEY.ENTER:
+            case KEY.SPACE: event.preventDefault(); commit(activeIndex); break;
+            case KEY.ESCAPE: event.preventDefault(); event.stopPropagation(); close(); break;
+            case KEY.TAB: close({ refocus: false }); break;
+            default: break;
+        }
+    });
+
+    render();
+
+    return {
+        element: wrapper,
+        getValue: () => selected,
+        setValue(next) {
+            selected = next;
+            render();
+        },
+        setOptions(nextOptions, nextValue) {
+            items = nextOptions;
+            selected = nextValue ?? (items.some((item) => item.value === selected) ? selected : items[0]?.value);
+            render();
+        },
+    };
+}