wiki-formant 0.37.0 → 0.40.0

package/README.md

@@ -724,16 +724,31 @@ export const POST = gate.route;
 // src/app/stats/page.tsx
 if (!(await gate.signedIn((await cookies()).get(gate.cookie)?.value)))
   return <PasskeyButton endpoint="/api/passkey" invite={invite} create={await gate.open()} />;
-const days = statsDays((await searchParams).days); // 1, 7, 30, 90, 365 or Infinity (?days=all), else 30
-return <Stats digest={await digest(sql, { days })} days={days} />;
+const q = statsQuery(await searchParams); // ?days= (1, 7, 30, 90, 365 or all, else 30) and the filters
+return <Stats digest={await digest(sql, q)} {...q} />;
 ```
 
 `PasskeyButton` (`wiki-formant/passkey-button`) is the browser half and has its
 own subpath, because it imports the optional peer `@simplewebauthn/browser`.
 `Stats` (`wiki-formant/stats`) renders a `digest` as one page: the
-headline figures against the window before, visitors per day, every non-empty
-ranked list, and `?days=` links between windows, all time among them. Everything
-but the daily chart is server-rendered. The chart is `TimeChart` with a count
+headline figures against the window before, one of them per day, every non-empty
+ranked list, and `?days=` links between windows, all time among them. Each
+figure is a button that charts it: visitors, page views, bounce rate, visit
+length, visitors with agents and clicks to X. `digest`'s `by_day` carries every
+one of those per UTC day, a visit on the day it began, so the days add up to the
+totals. A day with no visits has no bounce rate or visit length and is left out
+of those charts rather than drawn as zero. Everything but the figures and the
+chart is server-rendered.
+
+Every row in a list is a link that narrows the page to it, and the narrowings
+stack: `?page=`, `?entry=`, `?source=`, `?country=` and `?device=`, each shown as
+a chip that drops it. A narrowing keeps the visits that pass – that saw the
+page, began on it, came from the source, or were made from the country or
+device – and recounts every figure, list and day from those visits alone, with
+events only from their visitors. Agent tool calls and missed searches are
+events no visit reaches, so their rows are not links. `ViewDay` keeps totals,
+not visits, so a narrowed page starts at `counted_from`, the first day the site
+counted itself, says so, and drops the comparison with the window before. The chart is `TimeChart` with a count
 axis from zero, so `lightweight-charts` is an optional peer that a stats page
 needs installed.
 
@@ -761,7 +776,10 @@ and `volume`. Points that carry the candle get a Line/Candles toggle, opening on
 candles with `candles`; points that carry volume get a volume pane under the
 price, a fifth of the height. Candles take `--chart-up` and `--chart-down` from
 the canvas box, else its `color`. A week of candles opens on its first, closes
-on its last, spans the highest high and lowest low, and sums its volume.
+on its last, spans the highest high and lowest low, and sums its volume. A point
+with a volume of zero is a stretch nothing traded in: its candle and bar leave
+the slot empty, except the last, which is the price now. A price's line is
+straight between closes and a count's is curved.
 
 `aggregate` is how a week or month is made from its days: `last` for a price,
 `mean` for a count, so the week in progress keeps its level instead of reading

package/dist/analytics.d.ts

@@ -65,6 +65,9 @@ export interface Gap {
 }
 /** Searches in a wiki's own search box that found nothing (`searchQueryProps` events). */
 export declare const SEARCH_GAPS: Gap;
+/** What a stats page can be narrowed to: one value each, every one applied. */
+export declare const STATS_FILTERS: readonly ["page", "entry", "source", "country", "device"];
+export type StatsFilter = Partial<Record<(typeof STATS_FILTERS)[number], string>>;
 export interface DigestOptions {
     site?: string;
     /** How far back, in whole days from now; `Infinity` for all time. */
@@ -79,8 +82,28 @@ export interface DigestOptions {
      * The default is the conformance suites (`<repo>-mcp-test`) and the studio's own tools.
      */
     ownAgents?: string[];
+    /**
+     * Narrows every figure to the visits that pass, and the events to their
+     * visitors. `ViewDay` keeps no visits, so a narrowed digest leaves it out
+     * and starts at `counted_from`, and has no `previous_visitors`.
+     */
+    filter?: StatsFilter;
 }
 type Ranked<K extends string, M extends string> = Array<Record<K, string> & Record<M, number>>;
+/** One UTC day of the figures a digest totals; a visit falls on the day it began. */
+export interface DigestDay {
+    date: string;
+    visitors: number;
+    pageviews: number;
+    visits: number;
+    /** Visits that saw one page. */
+    bounces: number;
+    /** Seconds from each visit's first view to its last, summed. */
+    seconds: number;
+    visitors_incl_agents: number;
+    /** Clicks on links to the site's X handle; zero without a handle. */
+    follow_clicks: number;
+}
 export interface Digest {
     visitors: number;
     pageviews: number;
@@ -90,8 +113,10 @@ export interface Digest {
     visit_duration: number | null;
     /** Visitors plus every agent that sent an event, such as an MCP call. */
     visitors_incl_agents: number;
-    /** Visitors in the same number of days before. */
-    previous_visitors: number;
+    /** Visitors in the same number of days before; null when filtered. */
+    previous_visitors: number | null;
+    /** The first UTC day this site counted itself, before which only `ViewDay` speaks; null with no views. */
+    counted_from: string | null;
     top_sources: Ranked<'source', 'visitors'>;
     top_pages: Ranked<'page', 'visitors'>;
     entry_pages: Ranked<'page', 'visitors'>;
@@ -100,7 +125,8 @@ export interface Digest {
     sibling_referrals: Ranked<'source', 'visitors'>;
     countries: Ranked<'country', 'visitors'>;
     devices: Ranked<'device', 'visitors'>;
-    by_day: Ranked<'date', 'visitors'>;
+    /** Every day in the window with anything in it, oldest first. */
+    by_day: DigestDay[];
     follow_clicks: {
         events: number;
         visitors: number;
@@ -112,9 +138,10 @@ export interface Digest {
  * Everything a report needs about one site's last `days` days, in one query.
  * Visitor figures count distinct visitors, so a person who comes back on
  * another day counts once for each day. Days in `ViewDay` add to the visitor,
- * page, source, country, device and per-day figures; events have no history.
+ * page, visit, source, country, device and per-day figures; events have no
+ * history, so an archived day's visitors are its visitors with agents too.
  */
-export declare function digest(sql: Sql, { site, days, handle, siblings, gaps, ownAgents }: DigestOptions): Promise<Digest>;
+export declare function digest(sql: Sql, { site, days, handle, siblings, gaps, ownAgents, filter }: DigestOptions): Promise<Digest>;
 /**
  * Props for an "MCP Call" event, read out of the JSON-RPC envelope.
  *

package/dist/analytics.js

@@ -188,13 +188,27 @@ export async function collect(request, { sql, defer, site, rateLimit: limit = BE
 }
 /** Searches in a wiki's own search box that found nothing (`searchQueryProps` events). */
 export const SEARCH_GAPS = { event: 'Search Query', prop: 'q', where: { results: '0', surface: 'wiki' } };
+/** What a stats page can be narrowed to: one value each, every one applied. */
+export const STATS_FILTERS = ['page', 'entry', 'source', 'country', 'device'];
+/**
+ * Each filter as a test on one visit. A page, country or device is any of the
+ * visit's views; an entry page or a source is its first. `(none)` is no source.
+ */
+const VISIT_TEST = {
+    page: v => `bool_or(path = ${v})`,
+    entry: v => `(array_agg(path ORDER BY at, id))[1] = ${v}`,
+    source: v => `coalesce((array_agg(source ORDER BY at, id))[1], '(none)') = ${v}`,
+    country: v => `bool_or(country = ${v})`,
+    device: v => `bool_or(device = ${v})`,
+};
 /**
  * Everything a report needs about one site's last `days` days, in one query.
  * Visitor figures count distinct visitors, so a person who comes back on
  * another day counts once for each day. Days in `ViewDay` add to the visitor,
- * page, source, country, device and per-day figures; events have no history.
+ * page, visit, source, country, device and per-day figures; events have no
+ * history, so an archived day's visitors are its visitors with agents too.
  */
-export async function digest(sql, { site = '', days, handle, siblings = [], gaps = [SEARCH_GAPS], ownAgents = ['-mcp-test', 'radix-studio'] }) {
+export async function digest(sql, { site = '', days, handle, siblings = [], gaps = [SEARCH_GAPS], ownAgents = ['-mcp-test', 'radix-studio'], filter = {} }) {
     // The window is the database's clock, which stamped the rows; the app's can run behind it.
     // All time is a century: further back than any row, and still an int to Postgres.
     const values = [site, Number.isFinite(days) ? Math.max(1, Math.round(days)) : 36_500];
@@ -202,27 +216,34 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
     const list = (select, limit, order = '2 DESC, 1') => `(SELECT coalesce(json_agg(t), '[]') FROM (${select} ORDER BY ${order}${limit ? ` LIMIT ${limit}` : ''}) t)`;
     /** A ranked list from the views, plus the same breakdown from `ViewDay`. */
     const merged = (label, column, live) => `SELECT k AS ${label}, sum(n) AS visitors FROM (${live} UNION ALL SELECT key, value::int FROM a, jsonb_each_text(a."${column}")) t(k, n) GROUP BY 1`;
+    /** Clicks on links to the site's own X account, among `e`. */
+    const follows = handle && `name = 'Outbound Link: Click' AND props->>'url' ILIKE ANY(${$([`%x.com/${handle}%`, `%twitter.com/${handle}%`])}::text[])`;
+    const tests = STATS_FILTERS.flatMap(k => (filter[k] ? [VISIT_TEST[k]($(filter[k]))] : []));
+    const day = (at) => `to_char(${at} AT TIME ZONE 'UTC', 'YYYY-MM-DD')`;
     const gapSelects = gaps.map(g => {
         const prop = $(g.prop);
         return `(SELECT props->>${prop} AS query, count(*) AS events FROM e
       WHERE name = ${$(g.event)} AND props @> ${$(JSON.stringify(g.where ?? {}))}::jsonb AND props->>${prop} IS NOT NULL
       GROUP BY 1 ORDER BY 2 DESC, 1 LIMIT 15)`;
     });
-    const [row] = (await sql(`WITH v AS (
+    const [row] = (await sql(`WITH viewed AS (
       SELECT id, path, source, country, device, visitor, "createdAt" AS at FROM "View"
       WHERE "siteId" = $1 AND "createdAt" >= now() - make_interval(days => $2::int)
     ), marked AS (
-      SELECT *, CASE WHEN at - lag(at) OVER (PARTITION BY visitor ORDER BY at, id) <= interval '30 minutes' THEN 0 ELSE 1 END AS starts FROM v
+      SELECT *, CASE WHEN at - lag(at) OVER (PARTITION BY visitor ORDER BY at, id) <= interval '30 minutes' THEN 0 ELSE 1 END AS starts FROM viewed
     ), numbered AS (
       SELECT *, sum(starts) OVER (PARTITION BY visitor ORDER BY at, id) AS visit FROM marked
     ), visits AS (
-      SELECT visitor, count(*) AS views, extract(epoch FROM max(at) - min(at)) AS seconds,
+      SELECT visitor, visit, min(at) AS at, count(*) AS views, extract(epoch FROM max(at) - min(at)) AS seconds,
         (array_agg(path ORDER BY at, id))[1] AS entry, (array_agg(source ORDER BY at, id))[1] AS source
-      FROM numbered GROUP BY visitor, visit
+      FROM numbered GROUP BY visitor, visit${tests.length ? ` HAVING ${tests.join(' AND ')}` : ''}
+    ), v AS (
+      ${tests.length ? 'SELECT n.id, n.path, n.source, n.country, n.device, n.visitor, n.at FROM numbered n JOIN visits USING (visitor, visit)' : 'SELECT * FROM viewed'}
     ), e AS (
-      SELECT name, props, visitor FROM "Event" WHERE "siteId" = $1 AND "createdAt" >= now() - make_interval(days => $2::int)
+      SELECT name, props, visitor, "createdAt" AS at FROM "Event" WHERE "siteId" = $1 AND "createdAt" >= now() - make_interval(days => $2::int)
+      ${tests.length ? 'AND visitor IN (SELECT visitor FROM v)' : ''}
     ), a AS (
-      SELECT * FROM "ViewDay" WHERE "siteId" = $1 AND day >= (now() AT TIME ZONE 'UTC' - make_interval(days => $2::int))::date
+      SELECT * FROM "ViewDay" WHERE "siteId" = $1 AND day >= (now() AT TIME ZONE 'UTC' - make_interval(days => $2::int))::date${tests.length ? ' AND false' : ''}
     ), sessions AS (
       SELECT sum(bounces) AS bounces, sum(visits) AS visits, sum(seconds) AS seconds FROM (
         SELECT count(*) FILTER (WHERE views = 1), count(*), coalesce(sum(seconds), 0) FROM visits
@@ -240,11 +261,14 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
       'bounce_rate', (SELECT round(100.0 * bounces / nullif(visits, 0)) FROM sessions),
       'visit_duration', (SELECT round(seconds / nullif(visits, 0)) FROM sessions),
       'visitors_incl_agents', (SELECT count(DISTINCT visitor) FROM (SELECT visitor FROM v UNION SELECT visitor FROM e) u) + (SELECT visitors FROM archived),
-      'previous_visitors', (SELECT count(DISTINCT visitor) FROM "View"
+      'previous_visitors', ${tests.length
+        ? 'NULL'
+        : `(SELECT count(DISTINCT visitor) FROM "View"
         WHERE "siteId" = $1 AND "createdAt" >= now() - make_interval(days => 2 * $2::int) AND "createdAt" < now() - make_interval(days => $2::int))
         + (SELECT coalesce(sum(visitors), 0) FROM "ViewDay" WHERE "siteId" = $1
           AND day >= (now() AT TIME ZONE 'UTC' - make_interval(days => 2 * $2::int))::date
-          AND day < (now() AT TIME ZONE 'UTC' - make_interval(days => $2::int))::date),
+          AND day < (now() AT TIME ZONE 'UTC' - make_interval(days => $2::int))::date)`},
+      'counted_from', (SELECT ${day('min("createdAt")')} FROM "View" WHERE "siteId" = $1),
       'top_sources', ${list('SELECT source, sum(visitors) AS visitors FROM src GROUP BY 1', 6)},
       'top_pages', ${list(merged('page', 'pages', 'SELECT path, count(DISTINCT visitor) FROM v GROUP BY 1'), 6)},
       'entry_pages', ${list(merged('page', 'entryPages', 'SELECT entry, count(DISTINCT visitor) FROM visits GROUP BY 1'), 6)},
@@ -252,14 +276,15 @@ export async function digest(sql, { site = '', days, handle, siblings = [], gaps
       'sibling_referrals', ${list(`SELECT source, sum(visitors) AS visitors FROM src WHERE source = ANY(${$(siblings)}::text[]) GROUP BY 1`, 6)},
       'countries', ${list(merged('country', 'countries', 'SELECT country, count(DISTINCT visitor) FROM v WHERE country IS NOT NULL GROUP BY 1'), 10)},
       'devices', ${list(merged('device', 'devices', 'SELECT device, count(DISTINCT visitor) FROM v GROUP BY 1'))},
-      'by_day', ${list(`SELECT date, sum(n) AS visitors FROM (
-          SELECT to_char(at AT TIME ZONE 'UTC', 'YYYY-MM-DD'), count(DISTINCT visitor) FROM v GROUP BY 1
-          UNION ALL SELECT to_char(day, 'YYYY-MM-DD'), visitors FROM a
-        ) t(date, n) GROUP BY 1`, undefined, '1')},
-      'follow_clicks', ${handle
-        ? `(SELECT json_build_object('events', count(*), 'visitors', count(DISTINCT visitor)) FROM e
-              WHERE name = 'Outbound Link: Click' AND props->>'url' ILIKE ANY(${$([`%x.com/${handle}%`, `%twitter.com/${handle}%`])}::text[]))`
-        : 'NULL'},
+      'by_day', ${list(`SELECT date, sum(visitors) AS visitors, sum(pageviews) AS pageviews, sum(visits) AS visits, sum(bounces) AS bounces,
+          sum(seconds) AS seconds, sum(agents) AS visitors_incl_agents, sum(follows) AS follow_clicks FROM (
+          SELECT ${day('at')}, count(DISTINCT visitor), count(*), 0, 0, 0, 0, 0 FROM v GROUP BY 1
+          UNION ALL SELECT ${day('at')}, 0, 0, count(*), count(*) FILTER (WHERE views = 1), coalesce(sum(seconds), 0), 0, 0 FROM visits GROUP BY 1
+          UNION ALL SELECT ${day('at')}, 0, 0, 0, 0, 0, count(DISTINCT visitor), 0 FROM (SELECT at, visitor FROM v UNION ALL SELECT at, visitor FROM e) u GROUP BY 1
+          ${follows ? `UNION ALL SELECT ${day('at')}, 0, 0, 0, 0, 0, 0, count(*) FROM e WHERE ${follows} GROUP BY 1` : ''}
+          UNION ALL SELECT to_char(day, 'YYYY-MM-DD'), visitors, pageviews, visits, bounces, seconds, visitors, 0 FROM a
+        ) t(date, visitors, pageviews, visits, bounces, seconds, agents, follows) GROUP BY 1`, undefined, '1')},
+      'follow_clicks', ${follows ? `(SELECT json_build_object('events', count(*), 'visitors', count(DISTINCT visitor)) FROM e WHERE ${follows})` : 'NULL'},
       'agent_tool_calls', ${list(`SELECT coalesce(props->>'tool', '(none)') AS tool, count(*) AS events FROM e
          WHERE name = 'MCP Call' AND props->>'method' = 'tools/call'
            AND NOT coalesce(props->>'ua', '') ILIKE ANY(${$(ownAgents.map(a => `%${a}%`))}::text[])

package/dist/base.css

@@ -199,13 +199,26 @@ pre:hover > .code-copy-btn,
 .stats { display: grid; gap: 2rem; }
 .stats-ranges { display: flex; flex-wrap: wrap; gap: 1rem; }
 .stats-ranges a[aria-current] { text-decoration: underline; text-underline-offset: 0.3em; }
+/* Each figure is a button that charts it; pressed is the one drawn. */
 .stats-figures {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr));
   gap: 1rem;
-  margin: 0;
 }
-.stats-figures dd { margin: 0; font-variant-numeric: tabular-nums; }
+.stats-figures button {
+  display: grid;
+  gap: 0.25em;
+  padding: 0;
+  font: inherit;
+  color: inherit;
+  text-align: start;
+  background: none;
+  border: 0;
+  cursor: pointer;
+  opacity: 0.6;
+}
+.stats-figures button[aria-pressed='true'] { opacity: 1; }
+.stats-figures strong { font-variant-numeric: tabular-nums; }
 .stats-lists {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr));
@@ -229,4 +242,12 @@ pre:hover > .code-copy-btn,
   pointer-events: none;
 }
 .stats-list li > span:first-child { min-width: 0; overflow-wrap: anywhere; }
+/* A row narrows the page to itself; the whole row is the link. */
+.stats-list a { color: inherit; text-decoration: none; }
+.stats-list a::after { content: ''; position: absolute; inset: 0; }
+.stats-list a:is(:hover, :focus-visible) { text-decoration: underline; text-underline-offset: 0.2em; }
+.stats-filters { display: grid; gap: 0.5rem; }
+.stats-filters ul { display: flex; flex-wrap: wrap; gap: 0.5rem; margin: 0; padding: 0; list-style: none; }
+.stats-filters a { display: inline-block; padding: 0.25em 0.75em; border: 1px solid; border-radius: 9999px; text-decoration: none; }
+.stats-filters p { margin: 0; opacity: 0.7; }
 .stats-count { font-variant-numeric: tabular-nums; }

package/dist/chart.js

@@ -7,7 +7,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // that carries volume gets a volume pane under it. `lightweight-charts` is
 // loaded on mount, so the page paints without it. Every colour is the canvas
 // box's own `color`, its axis `--chart-axis`, and a candle `--chart-up` or
-// `--chart-down`, each if set.
+// `--chart-down`, each if set. A count's line is curved; a price's is straight,
+// since a curve between two closes draws prices nobody paid.
 import { useEffect, useMemo, useRef, useState } from 'react';
 const DAY = 86_400;
 const RANGE = {
@@ -126,6 +127,7 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
             const down = rgba(style.getPropertyValue('--chart-down').trim() || style.color, style.getPropertyValue('--chart-down').trim() ? 1 : 0.45);
             const priceFormat = { type: 'custom', formatter: (n) => formatRef.current(n), minMove: 1e-12 };
             const guide = { color: rgba(style.color, 0.4), width: 1, style: LineStyle.Dotted, labelBackgroundColor: ink };
+            const grid = rgba(axis || style.color, 0.1);
             const api = createChart(el, {
                 autoSize: true,
                 layout: {
@@ -133,8 +135,10 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
                     textColor: axis ? rgba(axis) : rgba(style.color, 0.7),
                     fontFamily: style.fontFamily,
                     fontSize: parseFloat(style.fontSize) || 11,
+                    // The volume pane's border is a grid line, not the library's light-theme rule.
+                    panes: { separatorColor: grid, separatorHoverColor: 'transparent', enableResize: false },
                 },
-                grid: { vertLines: { color: rgba(axis || style.color, 0.1) }, horzLines: { color: rgba(axis || style.color, 0.1) } },
+                grid: { vertLines: { color: grid }, horzLines: { color: grid } },
                 crosshair: { mode: CrosshairMode.Magnet, vertLine: guide, horzLine: guide },
                 rightPriceScale: { borderVisible: false, scaleMargins: { top: 0.15, bottom: 0.1 } },
                 timeScale: { borderVisible: false, secondsVisible: false },
@@ -146,7 +150,7 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
                 topColor: rgba(style.color, 0.4),
                 bottomColor: rgba(style.color, 0.02),
                 lineWidth: 2,
-                lineType: LineType.Curved,
+                lineType: aggregate === 'mean' ? LineType.Curved : LineType.Simple,
                 crosshairMarkerBackgroundColor: ink,
                 crosshairMarkerBorderColor: ink,
                 priceFormat,
@@ -181,7 +185,7 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
             chart.current = null;
             setReady(false);
         };
-    }, [fromZero]);
+    }, [fromZero, aggregate]);
     // One request per resolution for the life of the loader: every range from 30D up reads the same days.
     const cache = useRef(new Map());
     useEffect(() => {
@@ -232,11 +236,14 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
         const shown = view?.shown ?? [];
         const asCandles = candles && !!view?.ohlc;
         const time = (p) => p.time;
+        // A point with no volume is a stretch nothing traded in: its candle and its bar leave the slot
+        // empty rather than draw a flat dash. The last one always draws, as the price now.
+        const idle = (p, i) => p.volume === 0 && i < shown.length - 1;
         c.api.applyOptions({ timeScale: { timeVisible: source.resolution !== 'day' } });
         c.area.applyOptions({ visible: !asCandles });
         c.candle.applyOptions({ visible: asCandles });
         c.area.setData(asCandles ? [] : shown.map(p => ({ time: time(p), value: p.value })));
-        c.candle.setData(asCandles ? shown.map(p => ({ time: time(p), open: p.open, high: p.high, low: p.low, close: p.value })) : []);
+        c.candle.setData(asCandles ? shown.map((p, i) => (idle(p, i) ? { time: time(p) } : { time: time(p), open: p.open, high: p.high, low: p.low, close: p.value })) : []);
         if (view?.volume && !c.volume)
             c.volume = c.addVolume();
         else if (!view?.volume && c.volume) {
@@ -246,6 +253,8 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
                 c.api.removePane(1);
         }
         c.volume?.setData(shown.map((p, i) => {
+            if (!p.volume)
+                return { time: time(p) };
             const rising = p.value >= (p.open ?? shown[i - 1]?.value ?? p.value);
             return { time: time(p), value: p.volume ?? 0, color: (rising ? c.up : c.down).replace(/[\d.]+\)$/, '0.5)') };
         }));

package/dist/stats-figures.d.ts

@@ -0,0 +1,10 @@
+import type { Digest } from './analytics.js';
+/**
+ * The figures as `.stats-figures button[aria-pressed]` and the pressed one per
+ * day from `first` (a UTC day number) to today. A count's empty day is a zero;
+ * a rate's is left out, since no visits is not a bounce rate of nothing.
+ */
+export declare function StatsFigures({ digest, first }: {
+    digest: Digest;
+    first: number;
+}): import("react").JSX.Element;

package/dist/stats-figures.js

@@ -0,0 +1,58 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// stats-figures.tsx — the stats page's headline figures and the chart under
+// them. Each figure is a button that charts that figure per day, so the chart
+// is not only visitors. Its own module because it holds state; `Stats` stays a
+// server component and hands it the digest, which is plain JSON.
+import { useMemo, useState } from 'react';
+import { TimeChart } from './chart.js';
+const count = (n) => n.toLocaleString('en');
+const duration = (s) => (s < 60 ? `${Math.round(s)}s` : `${Math.floor(s / 60)}m ${Math.round(s % 60)}s`);
+const percent = (n) => `${Math.round(n)}%`;
+/** Unsigned at zero, so no change never reads as growth. */
+const change = (now, before) => {
+    if (!before)
+        return null;
+    const pct = Math.round((100 * (now - before)) / before);
+    return pct > 0 ? `+${pct}%` : `${pct}%`;
+};
+const figuresOf = (d) => [
+    { label: 'Visitors', value: count(d.visitors), delta: change(d.visitors, d.previous_visitors), day: r => r.visitors },
+    { label: 'Page views', value: count(d.pageviews), day: r => r.pageviews },
+    {
+        label: 'Bounce rate',
+        value: d.bounce_rate == null ? '–' : percent(d.bounce_rate),
+        day: r => (r.visits ? (100 * r.bounces) / r.visits : null),
+        format: percent,
+    },
+    {
+        label: 'Visit length',
+        value: d.visit_duration == null ? '–' : duration(d.visit_duration),
+        day: r => (r.visits ? r.seconds / r.visits : null),
+        format: duration,
+    },
+    { label: 'With agents', value: count(d.visitors_incl_agents), day: r => r.visitors_incl_agents },
+    ...(d.follow_clicks ? [{ label: 'Clicks to X', value: count(d.follow_clicks.events), day: (r) => r.follow_clicks }] : []),
+];
+const DAY = 86_400;
+const EMPTY = { date: '', visitors: 0, pageviews: 0, visits: 0, bounces: 0, seconds: 0, visitors_incl_agents: 0, follow_clicks: 0 };
+/**
+ * The figures as `.stats-figures button[aria-pressed]` and the pressed one per
+ * day from `first` (a UTC day number) to today. A count's empty day is a zero;
+ * a rate's is left out, since no visits is not a bounce rate of nothing.
+ */
+export function StatsFigures({ digest, first }) {
+    const figures = useMemo(() => figuresOf(digest), [digest]);
+    const [chosen, choose] = useState(0);
+    const figure = figures[chosen] ?? figures[0];
+    const byDay = useMemo(() => new Map(digest.by_day.map(r => [r.date, r])), [digest.by_day]);
+    const series = useMemo(() => {
+        const today = Math.floor(Date.now() / 1000 / DAY);
+        return Array.from({ length: today - first + 1 }, (_, i) => {
+            const time = (first + i) * DAY;
+            const value = figure.day(byDay.get(new Date(time * 1000).toISOString().slice(0, 10)) ?? EMPTY);
+            return value == null ? null : { time, value };
+        }).filter(p => p !== null);
+    }, [byDay, first, figure]);
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "stats-figures", role: "group", "aria-label": "Chart", children: figures.map((f, i) => (_jsxs("button", { type: "button", "aria-pressed": i === chosen, onClick: () => choose(i), children: [_jsx("span", { children: f.label }), _jsxs("strong", { children: [f.value, f.delta && _jsx("small", { children: ` ${f.delta}` })] })] }, f.label))) }), _jsx(TimeChart, { series: series, label: `${figure.label} per day`, ranges: ['all'], aggregate: "mean", fromZero: true, format: figure.format, className: "stats-chart" })] }));
+}

package/dist/stats.d.ts

@@ -1,20 +1,32 @@
-import type { Digest } from './analytics.js';
+import { type Digest, type StatsFilter } from './analytics.js';
 export interface StatsProps {
     /** One window's figures, from `digest` in `wiki-formant/analytics`. */
     digest: Digest;
     /** The window the digest covers, in days; `Infinity` for all time. */
     days: number;
+    /** What the digest was narrowed to, as `digest` was given it. */
+    filter?: StatsFilter;
     /** The windows offered as `?days=` links on the same page. */
     ranges?: readonly number[];
 }
 /** The windows the stats page offers, in days; `Infinity` is all time. */
 export declare const STATS_RANGES: readonly [1, 7, 30, 90, 365, number];
-/** A `?days=` value as one of `ranges`, else `fallback`: the page's only input. */
+/** A `?days=` value as one of `ranges`, else `fallback`. */
 export declare const statsDays: (param: unknown, ranges?: readonly number[], fallback?: number) => number;
+/**
+ * A stats page's query as the window and the filter, both ready for `digest`
+ * and `Stats`: `const q = statsQuery(await searchParams)`. A repeated or empty
+ * parameter is ignored.
+ */
+export declare function statsQuery(params: Record<string, string | string[] | undefined>, ranges?: readonly number[]): {
+    days: number;
+    filter: Partial<Record<"page" | "entry" | "source" | "country" | "device", string>>;
+};
 /**
  * A site's own analytics on one page: the headline figures against the window
- * before, visitors per day, and every ranked list the digest carries. Lists
- * with nothing in them are left out. The chart and the bars are
- * `currentColor` until the importing stylesheet gives them a colour.
+ * before, whichever of them is chosen per day, and every ranked list the
+ * digest carries, each row a link that narrows the page to it. Lists with
+ * nothing in them are left out. The chart and the bars are `currentColor`
+ * until the importing stylesheet gives them a colour.
  */
-export declare function Stats({ digest: d, days, ranges }: StatsProps): import("react").JSX.Element;
+export declare function Stats({ digest: d, days, filter, ranges }: StatsProps): import("react").JSX.Element;

package/dist/stats.js

@@ -1,11 +1,34 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { TimeChart } from './chart.js';
+import { STATS_FILTERS } from './analytics.js';
+import { StatsFigures } from './stats-figures.js';
 /** The windows the stats page offers, in days; `Infinity` is all time. */
 export const STATS_RANGES = [1, 7, 30, 90, 365, Infinity];
 /** A window as its `?days=` value. */
 const daysParam = (n) => (Number.isFinite(n) ? String(n) : 'all');
-/** A `?days=` value as one of `ranges`, else `fallback`: the page's only input. */
+/** A `?days=` value as one of `ranges`, else `fallback`. */
 export const statsDays = (param, ranges = STATS_RANGES, fallback = 30) => ranges.find(n => daysParam(n) === param) ?? fallback;
+/**
+ * A stats page's query as the window and the filter, both ready for `digest`
+ * and `Stats`: `const q = statsQuery(await searchParams)`. A repeated or empty
+ * parameter is ignored.
+ */
+export function statsQuery(params, ranges = STATS_RANGES) {
+    const filter = {};
+    for (const k of STATS_FILTERS) {
+        const v = params[k];
+        if (typeof v === 'string' && v)
+            filter[k] = v.slice(0, 500);
+    }
+    return { days: statsDays(params.days, ranges), filter };
+}
+/** The page at a window and a filter, as a query string. */
+const href = (days, filter) => {
+    const q = new URLSearchParams({ days: daysParam(days) });
+    for (const k of STATS_FILTERS)
+        if (filter[k])
+            q.set(k, filter[k]);
+    return `?${q}`;
+};
 const count = (n) => n.toLocaleString('en');
 const regions = new Intl.DisplayNames(['en'], { type: 'region' });
 const country = (code) => {
@@ -16,45 +39,33 @@ const country = (code) => {
         return code;
     }
 };
-const duration = (s) => (s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`);
-/** Unsigned at zero, so no change never reads as growth. */
-const change = (now, before) => {
-    if (!before)
-        return null;
-    const pct = Math.round((100 * (now - before)) / before);
-    return pct > 0 ? `+${pct}%` : `${pct}%`;
-};
-function StatsList({ title, rows, label = v => v }) {
+const NAMES = { page: 'Page', entry: 'Entry page', source: 'Source', country: 'Country', device: 'Device' };
+const DAY_MS = 86_400_000;
+function StatsList({ title, rows, label = v => v, to, }) {
     if (!rows.length)
         return null;
     const max = Math.max(...rows.map(([, n]) => n));
-    return (_jsxs("section", { className: "stats-list", children: [_jsx("h2", { children: title }), _jsx("ol", { children: rows.map(([v, n]) => (_jsxs("li", { style: { '--share': n / max }, children: [_jsx("span", { children: label(v) }), _jsx("span", { className: "stats-count", children: count(n) })] }, v))) })] }));
+    return (_jsxs("section", { className: "stats-list", children: [_jsx("h2", { children: title }), _jsx("ol", { children: rows.map(([v, n]) => (_jsxs("li", { style: { '--share': n / max }, children: [_jsx("span", { children: to ? _jsx("a", { href: to(v), children: label(v) }) : label(v) }), _jsx("span", { className: "stats-count", children: count(n) })] }, v))) })] }));
 }
 /**
  * A site's own analytics on one page: the headline figures against the window
- * before, visitors per day, and every ranked list the digest carries. Lists
- * with nothing in them are left out. The chart and the bars are
- * `currentColor` until the importing stylesheet gives them a colour.
+ * before, whichever of them is chosen per day, and every ranked list the
+ * digest carries, each row a link that narrows the page to it. Lists with
+ * nothing in them are left out. The chart and the bars are `currentColor`
+ * until the importing stylesheet gives them a colour.
  */
-export function Stats({ digest: d, days, ranges = STATS_RANGES }) {
-    const byDay = new Map(d.by_day.map(r => [r.date, r.visitors]));
+export function Stats({ digest: d, days, filter = {}, ranges = STATS_RANGES }) {
+    const today = Math.floor(Date.now() / DAY_MS);
+    const counted = d.counted_from ? Date.parse(d.counted_from) / DAY_MS : today;
+    const narrowed = STATS_FILTERS.filter(k => filter[k]);
     // A rolling window of n days touches n + 1 UTC dates, the first of them in
-    // part. All time starts at the first day anything was counted.
-    const today = Math.floor(Date.now() / 86_400_000);
-    const first = Number.isFinite(days) ? today - days : Math.min(today, ...d.by_day.map(r => Date.parse(r.date) / 86_400_000));
-    const series = Array.from({ length: today - first + 1 }, (_, i) => {
-        const time = (first + i) * 86_400;
-        return { time, value: byDay.get(new Date(time * 1000).toISOString().slice(0, 10)) ?? 0 };
-    });
-    const figures = [
-        ['Visitors', count(d.visitors), change(d.visitors, d.previous_visitors)],
-        ['Page views', count(d.pageviews), null],
-        ['Bounce rate', d.bounce_rate == null ? '–' : `${d.bounce_rate}%`, null],
-        ['Visit length', d.visit_duration == null ? '–' : duration(d.visit_duration), null],
-        ['With agents', count(d.visitors_incl_agents), null],
-    ];
-    if (d.follow_clicks)
-        figures.push(['Clicks to X', count(d.follow_clicks.events), null]);
+    // part. All time starts at the first day anything was counted, and a
+    // narrowed window at the first day the site counted itself.
+    const start = Number.isFinite(days) ? today - days : -Infinity;
+    const first = narrowed.length
+        ? Math.max(start, counted)
+        : Number.isFinite(start) ? start : Math.min(today, ...d.by_day.map(r => Date.parse(r.date) / DAY_MS));
     const rows = (list, k, m) => list.map(r => [r[k], r[m]]);
-    return (_jsxs("div", { className: "stats", children: [_jsx("nav", { className: "stats-ranges", "aria-label": "Window", children: ranges.map(n => (_jsx("a", { href: `?days=${daysParam(n)}`, "aria-current": n === days ? 'page' : undefined, children: n === 1 ? '24 hours' : Number.isFinite(n) ? `${n} days` : 'All time' }, n))) }), _jsx("dl", { className: "stats-figures", children: figures.map(([label, value, delta]) => (_jsxs("div", { children: [_jsx("dt", { children: label }), _jsxs("dd", { children: [value, delta && _jsx("small", { children: ` ${delta}` })] })] }, label))) }), _jsx(TimeChart, { series: series, label: "Visitors per day", ranges: ['all'], aggregate: "mean", fromZero: true, className: "stats-chart" }), _jsxs("div", { className: "stats-lists", children: [_jsx(StatsList, { title: "Pages", rows: rows(d.top_pages, 'page', 'visitors') }), _jsx(StatsList, { title: "Entry pages", rows: rows(d.entry_pages, 'page', 'visitors') }), _jsx(StatsList, { title: "Sources", rows: rows(d.top_sources, 'source', 'visitors') }), _jsx(StatsList, { title: "From X posts", rows: rows(d.from_posts, 'page', 'visitors') }), _jsx(StatsList, { title: "Sibling sites", rows: rows(d.sibling_referrals, 'source', 'visitors') }), _jsx(StatsList, { title: "Countries", rows: rows(d.countries, 'country', 'visitors'), label: country }), _jsx(StatsList, { title: "Devices", rows: rows(d.devices, 'device', 'visitors') }), _jsx(StatsList, { title: "Agent tool calls", rows: rows(d.agent_tool_calls, 'tool', 'events') }), _jsx(StatsList, { title: "Searches that found nothing", rows: rows(d.gaps, 'query', 'events') })] })] }));
+    const to = (k) => (v) => href(days, { ...filter, [k]: v });
+    return (_jsxs("div", { className: "stats", children: [_jsx("nav", { className: "stats-ranges", "aria-label": "Window", children: ranges.map(n => (_jsx("a", { href: href(n, filter), "aria-current": n === days ? 'page' : undefined, children: n === 1 ? '24 hours' : Number.isFinite(n) ? `${n} days` : 'All time' }, n))) }), narrowed.length > 0 && (_jsxs("div", { className: "stats-filters", children: [_jsx("ul", { "aria-label": "Narrowed to", children: narrowed.map(k => (_jsx("li", { children: _jsxs("a", { href: href(days, { ...filter, [k]: undefined }), title: "Remove", children: [NAMES[k], ": ", k === 'country' ? country(filter[k]) : filter[k], " \u00D7"] }) }, k))) }), start < counted && d.counted_from && (_jsxs("p", { children: ["Narrowed figures start on ", d.counted_from, ", the first day this site counted its own visits."] }))] })), _jsx(StatsFigures, { digest: d, first: first }), _jsxs("div", { className: "stats-lists", children: [_jsx(StatsList, { title: "Pages", rows: rows(d.top_pages, 'page', 'visitors'), to: to('page') }), _jsx(StatsList, { title: "Entry pages", rows: rows(d.entry_pages, 'page', 'visitors'), to: to('entry') }), _jsx(StatsList, { title: "Sources", rows: rows(d.top_sources, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { title: "From X posts", rows: rows(d.from_posts, 'page', 'visitors'), to: v => href(days, { ...filter, source: 'x', entry: v }) }), _jsx(StatsList, { title: "Sibling sites", rows: rows(d.sibling_referrals, 'source', 'visitors'), to: to('source') }), _jsx(StatsList, { title: "Countries", rows: rows(d.countries, 'country', 'visitors'), label: country, to: to('country') }), _jsx(StatsList, { title: "Devices", rows: rows(d.devices, 'device', 'visitors'), to: to('device') }), _jsx(StatsList, { title: "Agent tool calls", rows: rows(d.agent_tool_calls, 'tool', 'events') }), _jsx(StatsList, { title: "Searches that found nothing", rows: rows(d.gaps, 'query', 'events') })] })] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.37.0",
+  "version": "0.40.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",