@hhkaos/webmentions-widget 0.5.4 → 0.6.0

package/README.md

@@ -197,6 +197,12 @@ Finds the anchor in the source page that points back at you and quotes the
 sentence around it, rather than excerpting from the top of the post. Falls back to
 `content.text`. Pass `parseHTML` to run outside a browser.
 
+### `getMentionAuthor(mention)`
+
+Returns `{name, url, photo, initial, hue}`. `name` falls back to the source host,
+and `initial`/`hue` are there so a mention whose h-card has no `photo` — a plain
+blog, or your own site — still renders an avatar instead of a gap.
+
 ### `getMentionSourceUrl(mention, content)`
 
 Appends a `#:~:text=` fragment so the source link lands on the quoted sentence.
@@ -209,6 +215,35 @@ can hydrate from a build-time snapshot without touching the network.
 Every remote string is written with `textContent`. Nothing in this package ever
 assigns remote HTML.
 
+## Avatars
+
+Both renderers always emit an avatar element per mention. With `author.photo`
+it is an `<img>` carrying the photo class (`webmention-photo` in React,
+`webmentions__photo` in the DOM renderer); without one it is a `<span>` holding
+the author's initial, carrying that same class plus `is-initial` and a
+`--webmention-avatar-hue` custom property (0–359, stable per author name).
+
+The package ships no CSS. Style the fallback yourself — the hue is offered, not
+imposed:
+
+```css
+.webmention-photo {
+  border-radius: 50%;
+  flex: 0 0 40px;
+  height: 40px;
+  width: 40px;
+}
+
+.webmention-photo.is-initial {
+  align-items: center;
+  background: hsl(var(--webmention-avatar-hue, 220) 45% 92%);
+  color: hsl(var(--webmention-avatar-hue, 220) 45% 30%);
+  display: flex;
+  font-weight: 700;
+  justify-content: center;
+}
+```
+
 ## Notes on webmention.io quirks
 
 - The jf2 feed says `mention-of`; some payloads say `mention`. `normalizeProperty`

package/package.json

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

@@ -46,6 +46,47 @@ export function cleanText(value) {
   return String(value ?? '').replace(/\s+/g, ' ').trim();
 }
 
+/**
+ * The author as a renderer needs it: never an empty name, never an undefined
+ * photo. An h-card without `photo` is common — a mention from a plain blog, or
+ * from your own site — so `initial` is always there to fall back on and every
+ * mention can carry an avatar-shaped element.
+ */
+export function getMentionAuthor(mention) {
+  const author = mention?.author || {};
+  const source = mention?.url || mention?.['wm-source'] || '';
+  let host = '';
+
+  try {
+    host = new URL(source).hostname.replace(/^www\./, '');
+  } catch {
+    host = '';
+  }
+
+  const name = cleanText(author.name) || host || 'Someone';
+
+  return {
+    name,
+    url: author.url || source,
+    photo: author.photo || '',
+    initial: (name.charAt(0) || '?').toUpperCase(),
+    // A stable hue per author, so a wall of initials reads as distinct people
+    // rather than as one repeated placeholder. Only useful to a stylesheet, so
+    // it travels as a custom property rather than as an inline colour.
+    hue: getAuthorHue(name),
+  };
+}
+
+function getAuthorHue(name) {
+  let hash = 0;
+
+  for (let index = 0; index < name.length; index += 1) {
+    hash = (hash * 31 + name.charCodeAt(index)) % 360;
+  }
+
+  return hash;
+}
+
 /**
  * webmention.io and Bridgy mangle emoji into runs of "?" (and sometimes U+FFFD)
  * when extracting plain text from a toot or skeet. The emoji is unrecoverable,

package/src/react.js

@@ -12,6 +12,7 @@ import {
   fetchWebmentions,
   filterMentionsByTargets,
   formatMentionDate,
+  getMentionAuthor,
   getMentionContent,
   getMentionSourceUrl,
   getMentionType,
@@ -147,8 +148,36 @@ function renderLabel(label, keyPrefix) {
   ));
 }
 
+/**
+ * Every mention gets an avatar-shaped element, photo or not: a row that
+ * sometimes starts with a 40px image and sometimes with nothing has two
+ * different layouts, and the one without reads as a rendering failure.
+ */
+function Avatar({author, className, fallbackClassName, size}) {
+  if (author.photo) {
+    return h('img', {
+      className,
+      src: author.photo,
+      alt: '',
+      loading: 'lazy',
+      width: size,
+      height: size,
+    });
+  }
+
+  return h(
+    'span',
+    {
+      className: fallbackClassName,
+      'aria-hidden': 'true',
+      style: {'--webmention-avatar-hue': author.hue},
+    },
+    author.initial,
+  );
+}
+
 function Face({mention, classNames}) {
-  const author = mention.author || {};
+  const author = getMentionAuthor(mention);
   const sourceUrl = mention.url || mention['wm-source'] || author.url;
 
   return h(
@@ -161,24 +190,20 @@ function Face({mention, classNames}) {
         href: sourceUrl,
         rel: 'nofollow noopener',
         target: '_blank',
-        title: `${author.name || 'Someone'} — ${getMentionType(mention)}`,
+        title: `${author.name} — ${getMentionType(mention)}`,
       },
-      author.photo
-        ? h('img', {
-          className: classNames.facepilePhoto,
-          src: author.photo,
-          alt: '',
-          loading: 'lazy',
-          width: 32,
-          height: 32,
-        })
-        : h('span', {'aria-hidden': 'true'}, (author.name || '?').slice(0, 1).toUpperCase()),
+      h(Avatar, {
+        author,
+        className: classNames.facepilePhoto,
+        fallbackClassName: classNames.facepileInitial,
+        size: 32,
+      }),
     ),
   );
 }
 
 function Thread({mention, classNames, labels, locale, maxLength}) {
-  const author = mention.author || {};
+  const author = getMentionAuthor(mention);
   const published = mention.published || mention['wm-received'];
   const formattedDate = formatMentionDate(published, locale);
   const content = useMemo(
@@ -190,16 +215,12 @@ function Thread({mention, classNames, labels, locale, maxLength}) {
   return h(
     'li',
     {className: classNames.threadItem},
-    author.photo
-      ? h('img', {
-        className: classNames.threadPhoto,
-        src: author.photo,
-        alt: '',
-        loading: 'lazy',
-        width: 40,
-        height: 40,
-      })
-      : null,
+    h(Avatar, {
+      author,
+      className: classNames.threadPhoto,
+      fallbackClassName: classNames.threadInitial,
+      size: 40,
+    }),
     h(
       'div',
       {className: classNames.threadBody},
@@ -214,7 +235,7 @@ function Thread({mention, classNames, labels, locale, maxLength}) {
             rel: 'nofollow noopener',
             target: '_blank',
           },
-          h('span', {className: 'p-name'}, author.name || mention.url),
+          h('span', {className: 'p-name'}, author.name),
         ),
         ' ',
         h('span', null, getMentionType(mention, labels)),
@@ -280,9 +301,11 @@ const REACT_CLASS_NAMES = {
   facepileItem: 'webmention-facepile-item',
   facepileLink: 'webmention-facepile-link',
   facepilePhoto: 'webmention-facepile-photo',
+  facepileInitial: 'webmention-facepile-photo is-initial',
   threadList: 'webmentions-list',
   threadItem: 'h-cite webmention',
   threadPhoto: 'webmention-photo',
+  threadInitial: 'webmention-photo is-initial',
   threadBody: 'webmention-body',
   threadMeta: 'webmention-meta',
   threadAuthor: 'p-author h-card u-url',

package/src/render.js

@@ -10,6 +10,7 @@ import {
   describeTimestamp,
   fetchWebmentions,
   formatMentionDate,
+  getMentionAuthor,
   getMentionContent,
   getMentionSourceUrl,
   getMentionType,
@@ -26,6 +27,7 @@ export const DEFAULT_CLASS_NAMES = {
   facepileItem: 'webmentions__facepile-item',
   facepileLink: 'webmentions__facepile-link',
   facepilePhoto: 'webmentions__facepile-photo',
+  facepileInitial: 'webmentions__facepile-photo is-initial',
   threadList: 'webmentions__list',
   threadItem: 'webmentions__item h-cite',
   threadBody: 'webmentions__body',
@@ -33,7 +35,8 @@ export const DEFAULT_CLASS_NAMES = {
   threadAuthor: 'webmentions__author p-author h-card u-url',
   threadContent: 'webmentions__content p-content',
   threadSource: 'webmentions__source u-url',
-  threadPhoto: '',
+  threadPhoto: 'webmentions__photo',
+  threadInitial: 'webmentions__photo is-initial',
   updated: 'webmentions__updated',
 };
 
@@ -78,26 +81,14 @@ function resolveElement(value, root, doc) {
   return value;
 }
 
-function authorOf(mention) {
-  const author = mention.author || {};
-  const source = mention.url || mention['wm-source'] || '';
-  let host = '';
-
-  try {
-    host = new URL(source).hostname.replace(/^www\./, '');
-  } catch {
-    host = '';
-  }
-
-  return {
-    name: String(author.name || '').trim() || host || 'Someone',
-    url: author.url || source,
-    photo: author.photo || '',
-  };
-}
-
-function createAvatar(author, className, doc, size) {
+/**
+ * Every mention gets an avatar-shaped element, photo or not: a row that
+ * sometimes starts with an image and sometimes with nothing has two different
+ * layouts, and the one without reads as a rendering failure.
+ */
+function createAvatar(author, classNames, doc, size) {
   let element;
+  let className;
 
   if (author.photo) {
     element = doc.createElement('img');
@@ -106,10 +97,13 @@ function createAvatar(author, className, doc, size) {
     element.loading = 'lazy';
     element.width = size;
     element.height = size;
+    className = classNames.photo;
   } else {
     element = doc.createElement('span');
     element.setAttribute('aria-hidden', 'true');
-    element.textContent = (author.name.charAt(0) || '?').toUpperCase();
+    element.textContent = author.initial;
+    element.style.setProperty('--webmention-avatar-hue', author.hue);
+    className = classNames.initial ?? classNames.photo;
   }
 
   if (className) {
@@ -120,7 +114,7 @@ function createAvatar(author, className, doc, size) {
 }
 
 function createFace(mention, classNames, doc) {
-  const author = authorOf(mention);
+  const author = getMentionAuthor(mention);
   const item = doc.createElement('li');
   item.className = classNames.facepileItem;
 
@@ -130,7 +124,12 @@ function createFace(mention, classNames, doc) {
   link.rel = 'nofollow noopener';
   link.target = '_blank';
   link.title = `${author.name} — ${getMentionType(mention)}`;
-  link.appendChild(createAvatar(author, classNames.facepilePhoto, doc, 32));
+  link.appendChild(createAvatar(
+    author,
+    {photo: classNames.facepilePhoto, initial: classNames.facepileInitial},
+    doc,
+    32,
+  ));
 
   item.appendChild(link);
 
@@ -171,7 +170,7 @@ function createFacepileGroup(property, mentions, {classNames, labels, doc}) {
 }
 
 function createThreadItem(mention, {classNames, labels, locale, maxLength, doc}) {
-  const author = authorOf(mention);
+  const author = getMentionAuthor(mention);
   const published = mention.published || mention['wm-received'];
   const formattedDate = formatMentionDate(published, locale);
   const content = getMentionContent(mention, {maxLength});
@@ -180,9 +179,12 @@ function createThreadItem(mention, {classNames, labels, locale, maxLength, doc})
   const item = doc.createElement('li');
   item.className = classNames.threadItem;
 
-  if (classNames.threadPhoto) {
-    item.appendChild(createAvatar(author, classNames.threadPhoto, doc, 40));
-  }
+  item.appendChild(createAvatar(
+    author,
+    {photo: classNames.threadPhoto, initial: classNames.threadInitial},
+    doc,
+    40,
+  ));
 
   const body = doc.createElement('div');
   body.className = classNames.threadBody;