@hhkaos/webmentions-widget 0.2.0 → 0.3.0

package/README.md

@@ -134,6 +134,27 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hhkaos/webmentions-widget",
-  "version": "0.2.0",
+  "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",

package/src/react.js

@@ -107,14 +107,43 @@ export function useWebmentions(targets, options = {}) {
   // 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;
+    return {...fetched, source: 'network', generatedAt: null};
   }
 
   if (seededGroups) {
-    return {status: 'success', groups: seededGroups, error: fetched.error};
+    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 {status: fetched.status, groups: EMPTY_GROUPS, error: fetched.error};
+  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}) {
@@ -213,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',
 };
 
 /**
@@ -231,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;
@@ -275,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;