@hhkaos/webmentions-widget 0.1.0

package/src/react.js

@@ -0,0 +1,251 @@
+/**
+ * Optional React entry point.
+ *
+ * Written with `createElement` rather than JSX so the package stays
+ * buildless — consumers import the source directly.
+ */
+
+import {createElement as h, useEffect, useMemo, useRef, useState} from 'react';
+import {
+  FACEPILE_PROPERTIES,
+  fetchWebmentions,
+  formatMentionDate,
+  getMentionContent,
+  getMentionSourceUrl,
+  getMentionType,
+  groupWebmentions,
+} from './core.js';
+
+const EMPTY_GROUPS = {
+  interactions: [],
+  threads: [],
+  byProperty: Object.fromEntries(FACEPILE_PROPERTIES.map((property) => [property, []])),
+  counts: {},
+  total: 0,
+};
+
+/**
+ * Fetch mentions for `targets` and keep them in state.
+ *
+ * `status` distinguishes `'error'` from an empty `'success'`, so a caller can
+ * keep the section mounted during a webmention.io outage instead of silently
+ * unmounting it.
+ */
+export function useWebmentions(targets, options = {}) {
+  const {
+    apiUrl,
+    perPage,
+    retries,
+    retryDelayMs,
+    fallbackToJson,
+    initialMentions,
+  } = 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;
+
+  useEffect(() => {
+    if (!targetsKey) {
+      return undefined;
+    }
+
+    const controller = new AbortController();
+    let active = true;
+
+    setState((previous) => ({...previous, status: 'loading'}));
+
+    fetchWebmentions({
+      targets: targetsKey.split('\n'),
+      apiUrl,
+      perPage,
+      retries,
+      retryDelayMs,
+      fallbackToJson,
+      signal: controller.signal,
+    })
+      .then((mentions) => {
+        if (active) {
+          setState({status: 'success', groups: groupWebmentions(mentions), error: null});
+        }
+      })
+      .catch((error) => {
+        if (active && error?.name !== 'AbortError') {
+          setState({status: 'error', groups: EMPTY_GROUPS, error});
+        }
+      });
+
+    return () => {
+      active = false;
+      controller.abort();
+    };
+  }, [targetsKey, apiUrl, perPage, retries, retryDelayMs, fallbackToJson]);
+
+  return state;
+}
+
+function Face({mention, classNames}) {
+  const author = mention.author || {};
+  const sourceUrl = mention.url || mention['wm-source'] || author.url;
+
+  return h(
+    'li',
+    {className: classNames.facepileItem},
+    h(
+      'a',
+      {
+        className: classNames.facepileLink,
+        href: sourceUrl,
+        rel: 'nofollow noopener',
+        target: '_blank',
+        title: `${author.name || 'Someone'} — ${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()),
+    ),
+  );
+}
+
+function Thread({mention, classNames, labels, locale, maxLength}) {
+  const author = mention.author || {};
+  const published = mention.published || mention['wm-received'];
+  const formattedDate = formatMentionDate(published, locale);
+  const content = useMemo(
+    () => getMentionContent(mention, {maxLength}),
+    [mention, maxLength],
+  );
+  const sourceUrl = getMentionSourceUrl(mention, content);
+
+  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(
+      'div',
+      {className: classNames.threadBody},
+      h(
+        'p',
+        {className: classNames.threadMeta},
+        h(
+          'a',
+          {
+            className: classNames.threadAuthor,
+            href: sourceUrl || author.url,
+            rel: 'nofollow noopener',
+            target: '_blank',
+          },
+          h('span', {className: 'p-name'}, author.name || mention.url),
+        ),
+        ' ',
+        h('span', null, getMentionType(mention, labels)),
+        formattedDate
+          ? h('time', {className: 'dt-published', dateTime: published}, ` · ${formattedDate}`)
+          : null,
+      ),
+      content ? h('p', {className: classNames.threadContent}, content) : null,
+      mention.url ? h('a', {className: classNames.threadSource, href: sourceUrl}, mention.url) : null,
+    ),
+  );
+}
+
+const REACT_CLASS_NAMES = {
+  root: 'webmentions',
+  title: 'webmentions-title',
+  facepile: 'webmentions-facepile',
+  facepileItem: 'webmention-facepile-item',
+  facepileLink: 'webmention-facepile-link',
+  facepilePhoto: 'webmention-facepile-photo',
+  threadList: 'webmentions-list',
+  threadItem: 'h-cite webmention',
+  threadPhoto: 'webmention-photo',
+  threadBody: 'webmention-body',
+  threadMeta: 'webmention-meta',
+  threadAuthor: 'p-author h-card u-url',
+  threadContent: 'e-content webmention-content',
+  threadSource: 'u-url webmention-source',
+};
+
+/**
+ * Presentational component. Pass `targets` (build them with
+ * `getCanonicalTargets`) — routing and site config stay in the host app.
+ */
+export function Webmentions({
+  targets = [],
+  title = 'Webmentions',
+  labels = {},
+  locale,
+  maxLength,
+  classNames: classNameOverrides = {},
+  renderEmpty = null,
+  renderError = null,
+  ...options
+}) {
+  const classNames = {...REACT_CLASS_NAMES, ...classNameOverrides};
+  const {status, groups, error} = useWebmentions(targets, options);
+
+  if (status === 'error') {
+    return renderError ? renderError(error) : null;
+  }
+
+  if (status !== 'success') {
+    return null;
+  }
+
+  if (!groups.interactions.length && !groups.threads.length) {
+    return renderEmpty ? renderEmpty() : null;
+  }
+
+  return h(
+    'aside',
+    {className: classNames.root, 'aria-labelledby': `${classNames.title}-heading`},
+    h('h2', {id: `${classNames.title}-heading`, className: classNames.title}, title),
+    groups.interactions.length
+      ? h(
+        'ol',
+        {className: classNames.facepile, 'aria-label': 'Reactions'},
+        groups.interactions.map((mention) => h(Face, {
+          key: mention['wm-id'] || mention.url || mention['wm-source'],
+          mention,
+          classNames,
+        })),
+      )
+      : null,
+    groups.threads.length
+      ? h(
+        'ol',
+        {className: classNames.threadList},
+        groups.threads.map((mention) => h(Thread, {
+          key: mention['wm-id'] || mention.url || mention['wm-source'],
+          mention,
+          classNames,
+          labels,
+          locale,
+          maxLength,
+        })),
+      )
+      : null,
+  );
+}
+
+export default Webmentions;

package/src/render.js

@@ -0,0 +1,375 @@
+/**
+ * Imperative DOM renderer, for sites without a component framework.
+ *
+ * Every remote string goes through `textContent`; nothing here ever assigns
+ * remote HTML.
+ */
+
+import {
+  FACEPILE_PROPERTIES,
+  fetchWebmentions,
+  formatMentionDate,
+  getMentionContent,
+  getMentionSourceUrl,
+  getMentionType,
+  groupWebmentions,
+  normalizeProperty,
+} from './core.js';
+
+export const DEFAULT_CLASS_NAMES = {
+  facepile: 'webmentions__facepile',
+  facepileGroup: 'webmentions__group',
+  facepileFaces: 'webmentions__faces',
+  facepileCount: 'webmentions__count',
+  facepileGlyph: 'webmentions__glyph',
+  facepileItem: 'webmentions__facepile-item',
+  facepileLink: 'webmentions__facepile-link',
+  facepilePhoto: 'webmentions__facepile-photo',
+  threadList: 'webmentions__list',
+  threadItem: 'webmentions__item h-cite',
+  threadBody: 'webmentions__body',
+  threadMeta: 'webmentions__meta',
+  threadAuthor: 'webmentions__author p-author h-card u-url',
+  threadContent: 'webmentions__content p-content',
+  threadSource: 'webmentions__source u-url',
+  threadPhoto: '',
+};
+
+const FACEPILE_META = {
+  'like-of': {className: 'is-like', glyph: '♥'},
+  'repost-of': {className: 'is-repost', glyph: '↻'},
+  'bookmark-of': {className: 'is-bookmark', glyph: '⚑'},
+};
+
+/**
+ * A label may be a plain string, or a `{en: '…', es: '…'}` map for sites that
+ * ship both languages in the markup and toggle them with CSS.
+ */
+function appendLabel(parent, label, doc) {
+  if (label == null) {
+    return;
+  }
+
+  if (typeof label === 'string') {
+    parent.appendChild(doc.createTextNode(label));
+    return;
+  }
+
+  Object.entries(label).forEach(([lang, text]) => {
+    const span = doc.createElement('span');
+    span.className = `i18n-${lang}`;
+    span.lang = lang;
+    span.textContent = text;
+    parent.appendChild(span);
+  });
+}
+
+function resolveElement(value, root, doc) {
+  if (!value) {
+    return null;
+  }
+
+  if (typeof value === 'string') {
+    return root?.querySelector(value) || doc.querySelector(value);
+  }
+
+  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) {
+  let element;
+
+  if (author.photo) {
+    element = doc.createElement('img');
+    element.src = author.photo;
+    element.alt = '';
+    element.loading = 'lazy';
+    element.width = size;
+    element.height = size;
+  } else {
+    element = doc.createElement('span');
+    element.setAttribute('aria-hidden', 'true');
+    element.textContent = (author.name.charAt(0) || '?').toUpperCase();
+  }
+
+  if (className) {
+    element.className = className;
+  }
+
+  return element;
+}
+
+function createFace(mention, classNames, doc) {
+  const author = authorOf(mention);
+  const item = doc.createElement('li');
+  item.className = classNames.facepileItem;
+
+  const link = doc.createElement('a');
+  link.className = classNames.facepileLink;
+  link.href = mention.url || mention['wm-source'] || author.url || '#';
+  link.rel = 'nofollow noopener';
+  link.target = '_blank';
+  link.title = `${author.name} — ${getMentionType(mention)}`;
+  link.appendChild(createAvatar(author, classNames.facepilePhoto, doc, 32));
+
+  item.appendChild(link);
+
+  return item;
+}
+
+function createFacepileGroup(property, mentions, {classNames, labels, doc}) {
+  const meta = FACEPILE_META[property] || {className: '', glyph: ''};
+  const group = doc.createElement('div');
+  group.className = `${classNames.facepileGroup} ${meta.className}`.trim();
+
+  const faces = doc.createElement('ol');
+  faces.className = classNames.facepileFaces;
+  mentions.forEach((mention) => faces.appendChild(createFace(mention, classNames, doc)));
+  group.appendChild(faces);
+
+  const count = doc.createElement('span');
+  count.className = classNames.facepileCount;
+
+  if (meta.glyph) {
+    const glyph = doc.createElement('span');
+    glyph.className = classNames.facepileGlyph;
+    glyph.setAttribute('aria-hidden', 'true');
+    glyph.textContent = meta.glyph;
+    count.appendChild(glyph);
+  }
+
+  const number = doc.createElement('span');
+  number.textContent = String(mentions.length);
+  count.appendChild(number);
+  group.appendChild(count);
+
+  const accessibleName = `${mentions.length} ${getMentionType({'wm-property': property}, labels)}`;
+  group.setAttribute('aria-label', accessibleName);
+  group.title = accessibleName;
+
+  return group;
+}
+
+function createThreadItem(mention, {classNames, labels, locale, maxLength, doc}) {
+  const author = authorOf(mention);
+  const published = mention.published || mention['wm-received'];
+  const formattedDate = formatMentionDate(published, locale);
+  const content = getMentionContent(mention, {maxLength});
+  const sourceUrl = getMentionSourceUrl(mention, content);
+
+  const item = doc.createElement('li');
+  item.className = classNames.threadItem;
+
+  if (classNames.threadPhoto) {
+    item.appendChild(createAvatar(author, classNames.threadPhoto, doc, 40));
+  }
+
+  const body = doc.createElement('div');
+  body.className = classNames.threadBody;
+
+  const meta = doc.createElement('p');
+  meta.className = classNames.threadMeta;
+
+  const authorLink = doc.createElement('a');
+  authorLink.className = classNames.threadAuthor;
+  authorLink.href = sourceUrl || author.url || '#';
+  authorLink.rel = 'nofollow noopener';
+  authorLink.target = '_blank';
+  authorLink.textContent = author.name;
+  meta.appendChild(authorLink);
+  meta.appendChild(doc.createTextNode(' '));
+
+  const verb = doc.createElement('span');
+  const property = normalizeProperty(mention['wm-property']);
+  appendLabel(verb, labels[property] ?? getMentionType(mention, labels), doc);
+  meta.appendChild(verb);
+
+  if (formattedDate) {
+    const time = doc.createElement('time');
+    time.className = 'dt-published';
+    time.dateTime = published;
+    time.textContent = ` · ${formattedDate}`;
+    meta.appendChild(time);
+  }
+
+  body.appendChild(meta);
+
+  if (content || labels.fallbackContent) {
+    const contentElement = doc.createElement('p');
+    contentElement.className = classNames.threadContent;
+
+    if (content) {
+      contentElement.textContent = content;
+    } else {
+      appendLabel(contentElement, labels.fallbackContent, doc);
+    }
+
+    body.appendChild(contentElement);
+  }
+
+  if (sourceUrl && labels.viewSource) {
+    const sourceLink = doc.createElement('a');
+    sourceLink.className = classNames.threadSource;
+    sourceLink.href = sourceUrl;
+    sourceLink.rel = 'nofollow noopener';
+    sourceLink.target = '_blank';
+    appendLabel(sourceLink, labels.viewSource, doc);
+    body.appendChild(sourceLink);
+  }
+
+  item.appendChild(body);
+
+  return item;
+}
+
+/**
+ * Paint an already-fetched feed. Split out from `renderWebmentions` so a site
+ * can hydrate from a build-time snapshot without touching the network.
+ */
+export function renderGroups(groups, {
+  container,
+  facepile,
+  list,
+  labels = {},
+  locale,
+  classNames: classNameOverrides = {},
+  facepileMode = 'flat',
+  maxLength,
+  document: doc = globalThis.document,
+} = {}) {
+  const classNames = {...DEFAULT_CLASS_NAMES, ...classNameOverrides};
+  const containerElement = resolveElement(container, null, doc);
+  const facepileElement = resolveElement(facepile, containerElement, doc)
+    || containerElement?.querySelector(`.${classNames.facepile.split(' ')[0]}`);
+  const listElement = resolveElement(list, containerElement, doc)
+    || containerElement?.querySelector(`.${classNames.threadList.split(' ')[0]}`);
+
+  if (facepileElement) {
+    const children = facepileMode === 'grouped'
+      ? FACEPILE_PROPERTIES
+        .filter((property) => groups.byProperty?.[property]?.length)
+        .map((property) => createFacepileGroup(property, groups.byProperty[property], {
+          classNames,
+          labels,
+          doc,
+        }))
+      : groups.interactions.map((mention) => createFace(mention, classNames, doc));
+
+    facepileElement.replaceChildren(...children);
+    facepileElement.hidden = children.length === 0;
+  }
+
+  if (listElement) {
+    listElement.replaceChildren(...groups.threads.map((mention) => createThreadItem(mention, {
+      classNames,
+      labels,
+      locale,
+      maxLength,
+      doc,
+    })));
+  }
+
+  if (containerElement) {
+    const empty = !groups.interactions.length && !groups.threads.length;
+    containerElement.hidden = empty;
+    containerElement.setAttribute('aria-hidden', empty ? 'true' : 'false');
+  }
+
+  return groups;
+}
+
+/**
+ * Fetch and render in one call.
+ *
+ * On failure the container is left untouched (so server-rendered or cached
+ * markup survives an outage) and `onError` is invoked. The promise resolves
+ * rather than rejects: a dead third-party API should not produce an unhandled
+ * rejection on every page view.
+ */
+export async function renderWebmentions({
+  container,
+  facepile,
+  list,
+  targets,
+  labels = {},
+  locale,
+  classNames = {},
+  facepileMode = 'flat',
+  maxLength,
+  perPage,
+  retries,
+  retryDelayMs,
+  fallbackToJson,
+  apiUrl,
+  jsonApiUrl,
+  sortBy,
+  sortDir,
+  signal,
+  onError,
+  fetch: fetchImpl,
+  document: doc = globalThis.document,
+} = {}) {
+  const containerElement = resolveElement(container, null, doc);
+
+  if (!containerElement) {
+    return {status: 'error', groups: null, error: new Error('No container element')};
+  }
+
+  try {
+    const mentions = await fetchWebmentions({
+      targets,
+      apiUrl,
+      jsonApiUrl,
+      perPage,
+      sortBy,
+      sortDir,
+      retries,
+      retryDelayMs,
+      fallbackToJson,
+      signal,
+      fetch: fetchImpl,
+      document: doc,
+    });
+    const groups = groupWebmentions(mentions);
+
+    renderGroups(groups, {
+      container: containerElement,
+      facepile,
+      list,
+      labels,
+      locale,
+      classNames,
+      facepileMode,
+      maxLength,
+      document: doc,
+    });
+
+    return {status: 'success', groups, error: null};
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      return {status: 'aborted', groups: null, error};
+    }
+
+    onError?.(error);
+
+    return {status: 'error', groups: null, error};
+  }
+}