@hhkaos/webmentions-widget 0.2.0 → 0.4.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)`
@@ -189,6 +210,10 @@ assigns remote HTML.
   folds them together, so only ever branch on `mention-of`.
 - Bridgy mangles emoji into runs of `?` and `U+FFFD` when extracting plain text.
   `stripMojibake` removes the debris — the emoji is not recoverable.
+- Responses are sometimes **invalid JSON**: source content is copied into string
+  literals unescaped, so a backslash or a raw newline in a mention's content
+  makes the whole payload unparseable. `parseWebmentionJson` repairs those two
+  cases; valid payloads pass through untouched.
 
 ## Development
 

package/package.json

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

@@ -461,6 +461,86 @@ export function mergeSnapshot(existing, incoming) {
   };
 }
 
+const VALID_JSON_ESCAPES = new Set(['"', '\\', '/', 'b', 'f', 'n', 'r', 't', 'u']);
+
+/**
+ * Repair the malformed JSON webmention.io sometimes serves.
+ *
+ * Its serializer copies source-page content into string literals without
+ * escaping it, so a mention whose content contains a backslash (a shell example
+ * ending in `\`, say) or a raw newline produces a payload that `JSON.parse`
+ * rejects outright. The mention is then invisible — not because the API was
+ * down, but because its response could not be read at all.
+ *
+ * Walks the text tracking whether it is inside a string literal, escaping only
+ * the offending characters and leaving valid escapes untouched.
+ */
+export function repairJson(text) {
+  let out = '';
+  let inString = false;
+
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+
+    if (!inString) {
+      if (char === '"') {
+        inString = true;
+      }
+
+      out += char;
+      continue;
+    }
+
+    if (char === '"') {
+      inString = false;
+      out += char;
+      continue;
+    }
+
+    if (char === '\\') {
+      const next = text[index + 1];
+
+      if (VALID_JSON_ESCAPES.has(next)) {
+        out += char + next;
+        index += 1;
+      } else {
+        out += '\\\\';
+      }
+
+      continue;
+    }
+
+    const code = char.charCodeAt(0);
+
+    if (code < 0x20) {
+      if (code === 0x0a) {
+        out += '\\n';
+      } else if (code === 0x0d) {
+        out += '\\r';
+      } else if (code === 0x09) {
+        out += '\\t';
+      } else {
+        out += `\\u${code.toString(16).padStart(4, '0')}`;
+      }
+
+      continue;
+    }
+
+    out += char;
+  }
+
+  return out;
+}
+
+/** Parse a webmention.io response, repairing it only if it will not parse. */
+export function parseWebmentionJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return JSON.parse(repairJson(text));
+  }
+}
+
 export class WebmentionFetchError extends Error {
   constructor(message, {status, attempts, cause} = {}) {
     super(message, {cause});
@@ -612,7 +692,7 @@ export async function fetchWebmentions({
           continue;
         }
 
-        const data = await response.json();
+        const data = parseWebmentionJson(await response.text());
 
         return endpoint.json
           ? normalizeJsonFeed(data)

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;