@hhkaos/webmentions-widget 0.4.0 → 0.5.1

package/README.md

@@ -150,7 +150,12 @@ widget dates what it is showing:
 
 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.
+
+While the snapshot is recent the timestamp reads as "3 hours ago"; once it is
+over a day old it becomes an absolute date. Either way the exact moment is one
+hover or one click away, and the `<time datetime>` attribute always carries the
+machine-readable value. `renderUpdated={(iso, label, exact) => …}` 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.

package/bin/snapshot.js

@@ -18,11 +18,14 @@
 import {readFile, writeFile, mkdir} from 'node:fs/promises';
 import {dirname} from 'node:path';
 
-import {getSnapshotMentions, mergeSnapshot} from '../src/core.js';
+import {getSnapshotMentions, mergeSnapshot, parseWebmentionJson} from '../src/core.js';
 
 const DEFAULT_API = 'https://webmention.io/api/mentions.jf2';
 const PER_PAGE = 100;
 const PAGE_DELAY_MS = 500;
+const RETRIES = 8;
+const RETRY_DELAY_MS = 3000;
+const MAX_RETRY_DELAY_MS = 30000;
 
 function parseArgs(argv) {
   const args = {};
@@ -49,6 +52,48 @@ async function readExisting(path) {
 
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
+/**
+ * webmention.io returns intermittent 502s. A daily job that gives up on the
+ * first one silently skips a whole day, so retry with backoff before deciding
+ * the API is really unavailable.
+ */
+async function fetchPage(url) {
+  let lastError = null;
+
+  for (let attempt = 0; attempt <= RETRIES; attempt += 1) {
+    if (attempt > 0) {
+      // Capped exponential backoff with jitter. webmention.io has spent today
+      // failing roughly two requests in three, so a job that gives up after
+      // half a minute loses the coin flip often enough to skip whole days; a
+      // daily job can afford to be patient for a couple of minutes instead.
+      const backoff = Math.min(RETRY_DELAY_MS * 2 ** (attempt - 1), MAX_RETRY_DELAY_MS);
+
+      await wait(backoff + Math.random() * 1000);
+    }
+
+    try {
+      const response = await fetch(url);
+
+      if (response.ok) {
+        return parseWebmentionJson(await response.text());
+      }
+
+      lastError = new Error(`webmention.io responded with ${response.status}`);
+
+      // A 4xx will not fix itself; only server errors are worth retrying.
+      if (response.status < 500 && response.status !== 429) {
+        break;
+      }
+    } catch (error) {
+      lastError = error;
+    }
+
+    console.error(`  attempt ${attempt + 1}/${RETRIES + 1} failed: ${lastError.message}`);
+  }
+
+  throw lastError;
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const domain = args.domain;
@@ -84,16 +129,18 @@ async function main() {
       params.set('since_id', String(sinceId));
     }
 
-    const response = await fetch(`${apiUrl}?${params}`);
+    let payload;
 
-    if (!response.ok) {
+    try {
+      payload = await fetchPage(`${apiUrl}?${params}`);
+    } catch (error) {
       // 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.`);
+      console.error(`${error.message}; keeping the current snapshot.`);
       process.exit(1);
     }
 
-    const batch = (await response.json())?.children || [];
+    const batch = payload?.children || [];
     collected.push(...batch);
 
     if (batch.length < PER_PAGE) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hhkaos/webmentions-widget",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Framework-agnostic, dependency-free widget to fetch and render webmention.io mentions for the current page.",
   "type": "module",
   "license": "MIT",

package/src/core.js

@@ -147,6 +147,84 @@ export function formatMentionDate(value, locale) {
   }).format(date);
 }
 
+const RELATIVE_UNITS = [
+  ['second', 1000],
+  ['minute', 60 * 1000],
+  ['hour', 60 * 60 * 1000],
+  ['day', 24 * 60 * 60 * 1000],
+];
+
+/** Default: fall back to an absolute date once a snapshot is over a day old. */
+export const DEFAULT_RELATIVE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * "3 hours ago" for a recent timestamp, `null` once it is old enough that an
+ * absolute date reads better. `null` is the signal to the caller to format the
+ * date instead — "27 days ago" is worse than "5 Sept".
+ */
+export function formatRelativeTime(value, locale, {
+  now = Date.now(),
+  thresholdMs = DEFAULT_RELATIVE_THRESHOLD_MS,
+} = {}) {
+  if (!value || typeof Intl?.RelativeTimeFormat !== 'function') {
+    return null;
+  }
+
+  const date = new Date(value);
+
+  if (Number.isNaN(date.getTime())) {
+    return null;
+  }
+
+  const elapsed = now - date.getTime();
+
+  // A clock skew that puts the snapshot slightly in the future should read as
+  // "now", not as a negative age.
+  if (elapsed > thresholdMs) {
+    return null;
+  }
+
+  const formatter = new Intl.RelativeTimeFormat(locale, {numeric: 'auto'});
+  const [unit, unitMs] = [...RELATIVE_UNITS]
+    .reverse()
+    .find(([, ms]) => Math.abs(elapsed) >= ms) || RELATIVE_UNITS[0];
+  const amount = Math.round(elapsed / unitMs);
+
+  return formatter.format(-amount, unit);
+}
+
+/** The exact moment, for a tooltip or an expanded view. */
+export function formatDateTime(value, locale) {
+  if (!value) {
+    return null;
+  }
+
+  const date = new Date(value);
+
+  if (Number.isNaN(date.getTime())) {
+    return null;
+  }
+
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: 'long',
+    timeStyle: 'short',
+  }).format(date);
+}
+
+/**
+ * What to show for a snapshot timestamp: a relative phrase while it is fresh,
+ * an absolute date once it is not, plus the exact moment for the tooltip.
+ */
+export function describeTimestamp(value, locale, options = {}) {
+  const relative = formatRelativeTime(value, locale, options);
+
+  return {
+    label: relative || formatMentionDate(value, locale),
+    exact: formatDateTime(value, locale),
+    isRelative: Boolean(relative),
+  };
+}
+
 function normalizeUrl(value, base) {
   if (!value) {
     return null;

package/src/react.js

@@ -5,9 +5,10 @@
  * buildless — consumers import the source directly.
  */
 
-import {createElement as h, useEffect, useMemo, useState} from 'react';
+import {createElement as h, useCallback, useEffect, useMemo, useState} from 'react';
 import {
   FACEPILE_PROPERTIES,
+  describeTimestamp,
   fetchWebmentions,
   filterMentionsByTargets,
   formatMentionDate,
@@ -227,6 +228,51 @@ function Thread({mention, classNames, labels, locale, maxLength}) {
   );
 }
 
+/**
+ * "Updated 3 hours ago" while the snapshot is fresh, an absolute date once it
+ * is not. The exact moment is always reachable: as a tooltip on hover, and by
+ * clicking — hover does not exist on touch.
+ */
+function UpdatedLine({className, generatedAt, locale, label, render}) {
+  const [expanded, setExpanded] = useState(false);
+  const toggle = useCallback(() => setExpanded((previous) => !previous), []);
+  const {label: relative, exact, isRelative} = useMemo(
+    () => describeTimestamp(generatedAt, locale),
+    [generatedAt, locale],
+  );
+
+  if (render) {
+    return h('p', {className}, render(generatedAt, relative, exact));
+  }
+
+  return h(
+    'p',
+    {className},
+    renderLabel(label, 'updated'),
+    ' ',
+    h(
+      'time',
+      {
+        dateTime: generatedAt,
+        title: exact,
+        onClick: isRelative ? toggle : undefined,
+        role: isRelative ? 'button' : undefined,
+        tabIndex: isRelative ? 0 : undefined,
+        onKeyDown: isRelative
+          ? (event) => {
+            if (event.key === 'Enter' || event.key === ' ') {
+              event.preventDefault();
+              toggle();
+            }
+          }
+          : undefined,
+        style: isRelative ? {cursor: 'pointer'} : undefined,
+      },
+      expanded ? exact : relative,
+    ),
+  );
+}
+
 const REACT_CLASS_NAMES = {
   root: 'webmentions',
   title: 'webmentions-title',
@@ -309,21 +355,14 @@ export function Webmentions({
     // 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),
-            ),
-          ],
-      )
+      ? h(UpdatedLine, {
+        key: 'updated',
+        className: classNames.updated,
+        generatedAt,
+        locale,
+        label: labels.updated,
+        render: renderUpdated,
+      })
       : null,
   ];
 

package/src/render.js

@@ -7,6 +7,7 @@
 
 import {
   FACEPILE_PROPERTIES,
+  describeTimestamp,
   fetchWebmentions,
   formatMentionDate,
   getMentionContent,
@@ -305,9 +306,37 @@ export function renderGroups(groups, {
       appendLabel(updatedElement, labels.updated, doc);
       updatedElement.appendChild(doc.createTextNode(' '));
 
+      // Relative while fresh, absolute once it is not. The exact moment stays
+      // reachable by hover and by click — hover does not exist on touch.
+      const {label, exact, isRelative} = describeTimestamp(updatedAt, locale);
       const time = doc.createElement('time');
       time.dateTime = updatedAt;
-      time.textContent = formatMentionDate(updatedAt, locale);
+      time.textContent = label;
+
+      if (exact) {
+        time.title = exact;
+      }
+
+      if (isRelative && exact) {
+        time.setAttribute('role', 'button');
+        time.setAttribute('tabindex', '0');
+        time.style.cursor = 'pointer';
+
+        let expanded = false;
+        const toggle = () => {
+          expanded = !expanded;
+          time.textContent = expanded ? exact : label;
+        };
+
+        time.addEventListener('click', toggle);
+        time.addEventListener('keydown', (event) => {
+          if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            toggle();
+          }
+        });
+      }
+
       updatedElement.appendChild(time);
     }