@hhkaos/webmentions-widget 0.1.1 → 0.3.0

package/README.md

@@ -101,6 +101,60 @@ export default function SiteWebmentions() {
 without the markup. It returns `{status, groups, error}` where `status` is
 `idle | loading | success | error`.
 
+## Build-time snapshot (recommended)
+
+By default the widget fetches in the browser, which costs webmention.io one
+request per visitor per page view — and leaves the section empty whenever their
+API is down. A snapshot inverts that: fetch once per day in CI, commit the
+result, and serve it as data.
+
+```sh
+npx webmentions-snapshot --domain example.com --out src/data/webmentions.json
+```
+
+Domain-wide queries need an API token (webmention.io → Settings → API Key),
+read from `WEBMENTION_IO_TOKEN`. The command fetches only what is new since the
+last run (`since_id`), waits between pages, and leaves the existing file
+untouched if the API errors — a bad fetch never replaces good data.
+
+Then hand the snapshot to the component:
+
+```jsx
+import snapshot from '@site/src/data/webmentions.json';
+
+<Webmentions targets={targets} snapshot={snapshot} />
+```
+
+The component narrows the whole-site snapshot to the current page locally and
+renders with **no network request at all**. Pass `revalidate` to opt back into
+a live fetch on top (the snapshot renders first either way, and a failed
+revalidation never blanks a section the snapshot could fill).
+
+Two things this buys beyond politeness: the section survives a webmention.io
+outage, and the committed JSON is a durable copy of your mentions if the
+service ever disappears.
+
+### Saying how fresh it is
+
+A snapshot is by definition a little behind. Pass an `updated` label and the
+widget dates what it is showing:
+
+```jsx
+<Webmentions
+  targets={targets}
+  snapshot={snapshot}
+  locale="es"
+  labels={{updated: {en: 'Updated', es: 'Actualizado'}}}
+/>
+```
+
+It renders only when the mentions came from a snapshot and there is at least one
+to qualify — on a live fetch the data is current and dating it would mislead.
+`renderUpdated={(iso, formatted) => …}` takes over the wording entirely.
+
+The widget owns this because it is the only layer that knows which source the
+mentions came from; the host owns the copy.
+
 ## API
 
 ### `fetchWebmentions(options)`

package/bin/snapshot.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+/**
+ * Refresh a build-time webmentions snapshot.
+ *
+ * Queries webmention.io once for the whole domain instead of once per page,
+ * and only for what is new since the last run (`since_id`). A site that runs
+ * this daily costs webmention.io one or two requests a day, versus one request
+ * per visitor per page view when the widget fetches in the browser.
+ *
+ * Usage:
+ *   webmentions-snapshot --domain example.com --out src/data/webmentions.json
+ *
+ * The API token (webmention.io → Settings → API Key) is read from
+ * WEBMENTION_IO_TOKEN, or --token. Domain queries require it.
+ */
+
+import {readFile, writeFile, mkdir} from 'node:fs/promises';
+import {dirname} from 'node:path';
+
+import {getSnapshotMentions, mergeSnapshot} from '../src/core.js';
+
+const DEFAULT_API = 'https://webmention.io/api/mentions.jf2';
+const PER_PAGE = 100;
+const PAGE_DELAY_MS = 500;
+
+function parseArgs(argv) {
+  const args = {};
+
+  argv.forEach((arg, index) => {
+    if (!arg.startsWith('--')) {
+      return;
+    }
+
+    const [flag, inline] = arg.slice(2).split('=');
+    args[flag] = inline ?? (argv[index + 1]?.startsWith('--') ? true : argv[index + 1]);
+  });
+
+  return args;
+}
+
+async function readExisting(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const domain = args.domain;
+  const out = args.out;
+  const token = args.token || process.env.WEBMENTION_IO_TOKEN;
+  const apiUrl = args.api || DEFAULT_API;
+
+  if (!domain || !out) {
+    console.error('Usage: webmentions-snapshot --domain <domain> --out <file.json> [--token <token>]');
+    process.exit(2);
+  }
+
+  if (!token) {
+    console.error('Missing API token: set WEBMENTION_IO_TOKEN or pass --token.');
+    process.exit(2);
+  }
+
+  const existing = await readExisting(out);
+  const sinceId = args.full ? null : existing?.lastId ?? null;
+  const collected = [];
+
+  for (let page = 0; ; page += 1) {
+    const params = new URLSearchParams({
+      domain,
+      token,
+      'per-page': String(PER_PAGE),
+      page: String(page),
+      'sort-by': 'created',
+      'sort-dir': 'up',
+    });
+
+    if (sinceId) {
+      params.set('since_id', String(sinceId));
+    }
+
+    const response = await fetch(`${apiUrl}?${params}`);
+
+    if (!response.ok) {
+      // Leave the existing snapshot alone rather than replacing good data with
+      // a partial fetch; the next scheduled run picks up where this stopped.
+      console.error(`webmention.io responded with ${response.status}; keeping the current snapshot.`);
+      process.exit(1);
+    }
+
+    const batch = (await response.json())?.children || [];
+    collected.push(...batch);
+
+    if (batch.length < PER_PAGE) {
+      break;
+    }
+
+    await wait(PAGE_DELAY_MS);
+  }
+
+  const before = getSnapshotMentions(existing).length;
+
+  if (!collected.length && existing) {
+    console.log(`No new mentions since #${sinceId}. Snapshot unchanged (${before}).`);
+    return;
+  }
+
+  const snapshot = mergeSnapshot(existing, collected);
+
+  if (snapshot.count === before) {
+    console.log(`Snapshot unchanged (${before} mentions).`);
+    return;
+  }
+
+  await mkdir(dirname(out), {recursive: true});
+  await writeFile(out, `${JSON.stringify(snapshot, null, 2)}\n`);
+
+  console.log(`Snapshot updated: ${before} → ${snapshot.count} mentions (lastId ${snapshot.lastId}).`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hhkaos/webmentions-widget",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Framework-agnostic, dependency-free widget to fetch and render webmention.io mentions for the current page.",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,7 @@
   },
   "files": [
     "src",
+    "bin",
     "README.md",
     "LICENSE"
   ],
@@ -53,5 +54,8 @@
   "devDependencies": {
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
+  },
+  "bin": {
+    "webmentions-snapshot": "./bin/snapshot.js"
   }
 }

package/src/core.js

@@ -391,6 +391,76 @@ export function groupWebmentions(mentions, {facepileProperties = FACEPILE_PROPER
   };
 }
 
+/**
+ * Match a mention's stored target against the variants we query for a page.
+ * Comparison ignores the trailing slash and the fragment, so a snapshot taken
+ * against one variant still matches a page queried under another.
+ */
+function targetMatches(mention, normalizedTargets) {
+  const target = normalizeUrl(mention?.['wm-target']);
+
+  return Boolean(target) && normalizedTargets.has(target);
+}
+
+/**
+ * Narrow a whole-domain snapshot down to one page.
+ *
+ * A build-time snapshot is fetched once for the entire site (webmention.io's
+ * `domain=` query), so each page has to pick out its own mentions locally
+ * rather than asking the API again.
+ */
+export function filterMentionsByTargets(mentions, targets = []) {
+  const normalizedTargets = new Set(
+    targets.map((target) => normalizeUrl(target)).filter(Boolean),
+  );
+
+  if (!normalizedTargets.size) {
+    return [];
+  }
+
+  return (mentions || []).filter((mention) => targetMatches(mention, normalizedTargets));
+}
+
+/**
+ * Read a snapshot in either accepted shape: a bare array of entries, or the
+ * `{mentions, generatedAt, lastId}` envelope that the refresh job writes.
+ */
+export function getSnapshotMentions(snapshot) {
+  if (Array.isArray(snapshot)) {
+    return snapshot;
+  }
+
+  return snapshot?.mentions || snapshot?.children || [];
+}
+
+/**
+ * Merge a fresh page of mentions into a snapshot, newest first, deduped by
+ * `wm-id`. Used by the refresh job so an incremental `since_id` fetch does not
+ * have to re-download everything.
+ */
+export function mergeSnapshot(existing, incoming) {
+  const byId = new Map();
+
+  [...getSnapshotMentions(existing), ...(incoming || [])].forEach((mention) => {
+    const key = mention?.['wm-id'] ?? mention?.['wm-source'];
+
+    if (key != null) {
+      byId.set(key, mention);
+    }
+  });
+
+  const mentions = [...byId.values()].sort((a, b) => (
+    (b['wm-id'] ?? 0) - (a['wm-id'] ?? 0)
+  ));
+
+  return {
+    generatedAt: new Date().toISOString(),
+    lastId: mentions.reduce((max, mention) => Math.max(max, mention['wm-id'] ?? 0), 0) || null,
+    count: mentions.length,
+    mentions,
+  };
+}
+
 export class WebmentionFetchError extends Error {
   constructor(message, {status, attempts, cause} = {}) {
     super(message, {cause});

package/src/react.js

@@ -5,14 +5,16 @@
  * buildless — consumers import the source directly.
  */
 
-import {createElement as h, useEffect, useMemo, useRef, useState} from 'react';
+import {createElement as h, useEffect, useMemo, useState} from 'react';
 import {
   FACEPILE_PROPERTIES,
   fetchWebmentions,
+  filterMentionsByTargets,
   formatMentionDate,
   getMentionContent,
   getMentionSourceUrl,
   getMentionType,
+  getSnapshotMentions,
   groupWebmentions,
 } from './core.js';
 
@@ -39,25 +41,42 @@ export function useWebmentions(targets, options = {}) {
     retryDelayMs,
     fallbackToJson,
     initialMentions,
+    // A whole-site snapshot, narrowed to these targets locally.
+    snapshot,
+    // With mentions already in hand, skip the network by default: the point of
+    // a snapshot is that a page view costs webmention.io nothing.
+    revalidate,
   } = options;
-  const [state, setState] = useState(() => ({
-    status: initialMentions ? 'success' : 'idle',
-    groups: initialMentions ? groupWebmentions(initialMentions) : EMPTY_GROUPS,
-    error: null,
-  }));
   const targetsKey = targets.join('\n');
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
+
+  // Derived, not stored: on a client-side route change the targets change, and
+  // state seeded once in a useState initializer would go stale.
+  const seededGroups = useMemo(() => {
+    if (initialMentions) {
+      return groupWebmentions(initialMentions);
+    }
+
+    if (!snapshot) {
+      return null;
+    }
+
+    return groupWebmentions(
+      filterMentionsByTargets(getSnapshotMentions(snapshot), targetsKey ? targetsKey.split('\n') : []),
+    );
+  }, [initialMentions, snapshot, targetsKey]);
+
+  const shouldFetch = (revalidate ?? !seededGroups) && Boolean(targetsKey);
+  const [fetched, setFetched] = useState({status: 'idle', groups: null, error: null});
 
   useEffect(() => {
-    if (!targetsKey) {
+    if (!shouldFetch) {
       return undefined;
     }
 
     const controller = new AbortController();
     let active = true;
 
-    setState((previous) => ({...previous, status: 'loading'}));
+    setFetched({status: 'loading', groups: null, error: null});
 
     fetchWebmentions({
       targets: targetsKey.split('\n'),
@@ -70,12 +89,12 @@ export function useWebmentions(targets, options = {}) {
     })
       .then((mentions) => {
         if (active) {
-          setState({status: 'success', groups: groupWebmentions(mentions), error: null});
+          setFetched({status: 'success', groups: groupWebmentions(mentions), error: null});
         }
       })
       .catch((error) => {
         if (active && error?.name !== 'AbortError') {
-          setState({status: 'error', groups: EMPTY_GROUPS, error});
+          setFetched({status: 'error', groups: null, error});
         }
       });
 
@@ -83,9 +102,48 @@ export function useWebmentions(targets, options = {}) {
       active = false;
       controller.abort();
     };
-  }, [targetsKey, apiUrl, perPage, retries, retryDelayMs, fallbackToJson]);
+  }, [targetsKey, shouldFetch, apiUrl, perPage, retries, retryDelayMs, fallbackToJson]);
+
+  // A live result wins once it lands; until then the snapshot renders. A failed
+  // revalidation never blanks a section the snapshot could still fill.
+  if (fetched.groups) {
+    return {...fetched, source: 'network', generatedAt: null};
+  }
+
+  if (seededGroups) {
+    return {
+      status: 'success',
+      groups: seededGroups,
+      error: fetched.error,
+      source: 'snapshot',
+      // Only meaningful for a snapshot: how stale the data on screen may be.
+      generatedAt: initialMentions ? null : snapshot?.generatedAt ?? null,
+    };
+  }
 
-  return state;
+  return {
+    status: fetched.status,
+    groups: EMPTY_GROUPS,
+    error: fetched.error,
+    source: null,
+    generatedAt: null,
+  };
+}
+
+/**
+ * A label is a plain string, or a `{en, es}` map for sites that ship both
+ * languages and toggle them with CSS.
+ */
+function renderLabel(label, keyPrefix) {
+  if (label == null || typeof label === 'string') {
+    return label ?? null;
+  }
+
+  return Object.entries(label).map(([lang, text]) => h(
+    'span',
+    {key: `${keyPrefix}-${lang}`, className: `i18n-${lang}`, lang},
+    text,
+  ));
 }
 
 function Face({mention, classNames}) {
@@ -184,6 +242,7 @@ const REACT_CLASS_NAMES = {
   threadAuthor: 'p-author h-card u-url',
   threadContent: 'e-content webmention-content',
   threadSource: 'u-url webmention-source',
+  updated: 'webmentions-updated',
 };
 
 /**
@@ -202,10 +261,11 @@ export function Webmentions({
   innerClassName = null,
   renderEmpty = null,
   renderError = null,
+  renderUpdated = null,
   ...options
 }) {
   const classNames = {...REACT_CLASS_NAMES, ...classNameOverrides};
-  const {status, groups, error} = useWebmentions(targets, options);
+  const {status, groups, error, source, generatedAt} = useWebmentions(targets, options);
 
   if (status === 'error') {
     return renderError ? renderError(error) : null;
@@ -246,6 +306,25 @@ export function Webmentions({
         })),
       )
       : null,
+    // Only when rendering from a snapshot: on a live fetch the mentions are
+    // current and dating them would be misleading.
+    source === 'snapshot' && generatedAt && (labels.updated || renderUpdated)
+      ? h(
+        'p',
+        {key: 'updated', className: classNames.updated},
+        renderUpdated
+          ? renderUpdated(generatedAt, formatMentionDate(generatedAt, locale))
+          : [
+            renderLabel(labels.updated, 'updated'),
+            ' ',
+            h(
+              'time',
+              {key: 'updated-time', dateTime: generatedAt},
+              formatMentionDate(generatedAt, locale),
+            ),
+          ],
+      )
+      : null,
   ];
 
   return h(

package/src/render.js

@@ -33,6 +33,7 @@ export const DEFAULT_CLASS_NAMES = {
   threadContent: 'webmentions__content p-content',
   threadSource: 'webmentions__source u-url',
   threadPhoto: '',
+  updated: 'webmentions__updated',
 };
 
 const FACEPILE_META = {
@@ -253,6 +254,10 @@ export function renderGroups(groups, {
   classNames: classNameOverrides = {},
   facepileMode = 'flat',
   maxLength,
+  // Timestamp of the snapshot these groups came from, if any. Rendering it
+  // tells a reader how stale the list may be; on a live fetch, leave it unset.
+  updatedAt = null,
+  updated,
   document: doc = globalThis.document,
 } = {}) {
   const classNames = {...DEFAULT_CLASS_NAMES, ...classNameOverrides};
@@ -287,6 +292,28 @@ export function renderGroups(groups, {
     })));
   }
 
+  const updatedElement = resolveElement(updated, containerElement, doc)
+    || containerElement?.querySelector(`.${classNames.updated.split(' ')[0]}`);
+
+  if (updatedElement) {
+    const show = Boolean(updatedAt) && labels.updated != null
+      && (groups.interactions.length > 0 || groups.threads.length > 0);
+
+    updatedElement.replaceChildren();
+
+    if (show) {
+      appendLabel(updatedElement, labels.updated, doc);
+      updatedElement.appendChild(doc.createTextNode(' '));
+
+      const time = doc.createElement('time');
+      time.dateTime = updatedAt;
+      time.textContent = formatMentionDate(updatedAt, locale);
+      updatedElement.appendChild(time);
+    }
+
+    updatedElement.hidden = !show;
+  }
+
   if (containerElement) {
     const empty = !groups.interactions.length && !groups.threads.length;
     containerElement.hidden = empty;