@hhkaos/webmentions-widget 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raul Jimenez Ortega
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# @hhkaos/webmentions-widget
+
+Fetch and render [webmention.io](https://webmention.io) mentions for the current page.
+
+Dependency-free, buildless ES modules. One implementation shared by every site
+instead of a copy per repo — see [#1](https://github.com/hhkaos/webmentions-widget/issues/1)
+for the history.
+
+## Why it exists
+
+Three sites had grown three near-identical copies of "query `mentions.jf2`, dedupe,
+render a facepile and a reply list". When webmention.io started returning
+intermittent `502`s in September 2026, every copy had the same flaw: a single
+un-retried `fetch`, and a widget that hides itself on failure. The 502 comes from
+nginx with **no `Access-Control-Allow-Origin` header**, so in a browser it surfaces
+as an opaque `Failed to fetch` — and the section silently vanished on all three
+sites at once.
+
+So this package builds the fixes in once:
+
+- **Retries with exponential backoff** on network errors and 5xx.
+- **Automatic fallback** from `/api/mentions.jf2` to the older `/api/mentions.json`,
+  reshaped into the same entry format.
+- **`error` is distinct from empty**, so a caller can keep server-rendered markup
+  on screen during an outage instead of blanking the section.
+- **Target URL variants** — `www`/no-`www`, trailing slash or not, locale prefixes.
+  webmention.io matches targets by exact string, so this is the single most common
+  cause of "the mention exists but does not show up".
+
+## Install
+
+```sh
+npm install @hhkaos/webmentions-widget
+```
+
+Or load it straight from a CDN — **always pin the version**, never `@latest`:
+
+```html
+<script type="module">
+  import {renderWebmentions} from 'https://esm.sh/@hhkaos/webmentions-widget@0.1.0/render';
+</script>
+```
+
+## Vanilla usage
+
+```html
+<section class="webmentions h-feed" id="webmentions" hidden>
+  <h2>Mentions</h2>
+  <div class="webmentions__facepile" id="webmentions-facepile" hidden></div>
+  <ol class="webmentions__list" id="webmentions-list"></ol>
+</section>
+
+<script type="module">
+  import {renderWebmentions} from '@hhkaos/webmentions-widget/render';
+
+  renderWebmentions({
+    container: '#webmentions',
+    facepile: '#webmentions-facepile',
+    list: '#webmentions-list',
+    // targets default to <link rel="canonical"> expanded into every variant
+    facepileMode: 'grouped',
+    labels: {
+      'like-of': {en: 'like', es: 'me gusta'},
+      'in-reply-to': {en: 'replied', es: 'respondió'},
+      viewSource: {en: 'View source', es: 'Ver original'},
+    },
+    onError: (error) => console.warn('[webmentions]', error),
+  });
+</script>
+```
+
+A label can be a plain string, or a `{en, es}` map — which renders one
+`<span class="i18n-en">` / `<span class="i18n-es">` per language, for sites that
+ship both and toggle with CSS.
+
+`facepileMode: 'grouped'` renders a separate like / repost / bookmark group with a
+count and a glyph. `'flat'` (the default) renders one merged pile.
+
+## React / Docusaurus usage
+
+```jsx
+import {getCanonicalTargets} from '@hhkaos/webmentions-widget';
+import {Webmentions} from '@hhkaos/webmentions-widget/react';
+import {useLocation} from '@docusaurus/router';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+export default function SiteWebmentions() {
+  const {pathname} = useLocation();
+  const {siteConfig} = useDocusaurusContext();
+  const targets = getCanonicalTargets({
+    siteUrl: siteConfig.url,
+    pathname,
+    i18n: siteConfig.i18n,
+  });
+
+  return <Webmentions targets={targets} locale="es" />;
+}
+```
+
+`useWebmentions(targets, options)` is exported separately if you want the data
+without the markup. It returns `{status, groups, error}` where `status` is
+`idle | loading | success | error`.
+
+## API
+
+### `fetchWebmentions(options)`
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `targets` | from `<link rel="canonical">` | array of exact target URLs |
+| `apiUrl` | `.../api/mentions.jf2` | |
+| `jsonApiUrl` | `.../api/mentions.json` | used only for the fallback |
+| `perPage` | `20` | |
+| `sortBy` / `sortDir` | `published` / `down` | |
+| `retries` | `2` | extra attempts *per endpoint* |
+| `retryDelayMs` | `400` | doubles each attempt |
+| `fallbackToJson` | `true` | |
+| `signal` | — | `AbortSignal`; aborts are never retried |
+| `fetch` | `globalThis.fetch` | injectable, for tests or a proxy |
+
+Resolves to an array of jf2 entries. Rejects with a `WebmentionFetchError`
+(carrying `.status` and `.attempts`) once every attempt is spent. A `4xx` is not
+retried — it will not fix itself — but the fallback endpoint is still tried.
+
+### `getCanonicalTargets({siteUrl, pathname, i18n, localePrefixes})`
+
+Expands one page into every target string webmention.io might have stored it under.
+
+### `groupWebmentions(mentions)`
+
+Returns `{interactions, threads, byProperty, counts, total}`. Facepile entries are
+deduped per author *per property*, so one person's like and repost both survive.
+Duplicate `wm-id`s from overlapping target queries are dropped.
+
+### `getMentionContent(mention, {maxLength, parseHTML})`
+
+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.
+
+### `getMentionSourceUrl(mention, content)`
+
+Appends a `#:~:text=` fragment so the source link lands on the quoted sentence.
+
+### `renderWebmentions(options)` / `renderGroups(groups, options)`
+
+Imperative DOM rendering. `renderGroups` paints an already-fetched feed, so a site
+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.
+
+## Notes on webmention.io quirks
+
+- The jf2 feed says `mention-of`; some payloads say `mention`. `normalizeProperty`
+  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.
+
+## Development
+
+```sh
+npm test
+```
+
+No dependencies, no build step. Tests run on `node:test` against a ~90-line fake
+DOM in `test/fake-dom.js`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hhkaos/webmentions-widget",
+  "version": "0.1.0",
+  "description": "Framework-agnostic, dependency-free widget to fetch and render webmention.io mentions for the current page.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Raul Jimenez Ortega",
+  "homepage": "https://github.com/hhkaos/webmentions-widget#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hhkaos/webmentions-widget.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hhkaos/webmentions-widget/issues"
+  },
+  "keywords": [
+    "webmention",
+    "webmention.io",
+    "indieweb",
+    "microformats",
+    "widget"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.js",
+    "./core": "./src/core.js",
+    "./render": "./src/render.js",
+    "./react": "./src/react.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}