webmention-web-components 0.0.1-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Severin Steffensen
+
+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/package.json

@@ -0,0 +1,28 @@
+{
+    "name": "webmention-web-components",
+    "version": "0.0.1-alpha.2",
+    "description": "Web components for presenting webmentions.",
+    "main": "./index.js",
+    "type": "module",
+    "files": [
+        "src",
+        "LICENSE",
+        "README.md"
+    ],
+    "exports": {
+        ".": "./index.js",
+        "./list": "./src/webmention-list.js"
+    },
+    "keywords": [
+        "webmention",
+        "indieweb",
+        "web-components",
+        "custom-elements"
+    ],
+    "author": "Martin Severin Steffensen <martin.severin.steffensen@proton.me> (https://clueless.no/)",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Maritims/webmention.git"
+    }
+}

package/src/utils.js

@@ -0,0 +1,40 @@
+/**
+ * @typedef {object} Webmention
+ * @property {string} target The target URL of the webmention.
+ * @property {string} source The source URL of the webmention.
+ * @property {string} mentionText The text of the webmention.
+ */
+
+/**
+ * @typedef {object} WebmentionFetchResult
+ * @property {Webmention[]} webmentions The webmentions fetched from the endpoint.
+ * @property {boolean} ok Whether the last fetch was successful.
+ */
+
+/**
+ * Fetches webmentions from the specified endpoint.
+ * @param url The URL to fetch webmentions from.
+ * @return {Promise<WebmentionFetchResult>}
+ */
+export const fetchWebmentions = async (url) => {
+    /** @type {WebmentionFetchResult} */
+    let webmentionFetchResult = {webmentions: [], ok: false};
+
+    if (url) {
+        try {
+            const response = await fetch(url);
+            if (response.ok) {
+                const webmentions = await response.json();
+                webmentionFetchResult = {webmentions, ok: true};
+            } else {
+                console.error(`An error occurred while attempting to fetch webmentions from ${url}. Status code: ${response.status}.`);
+            }
+        } catch (error) {
+            console.error(`An error occurred while attempting to fetch webmentions from ${url}.`, error);
+        }
+    } else {
+        console.error('No endpoint specified Ensure that the endpoint attribute is set with a value pointing to the appropriate endpoint for fetching webmention entries.');
+    }
+
+    return webmentionFetchResult;
+}

package/src/webmention-list.js

@@ -0,0 +1,118 @@
+import {fetchWebmentions} from './utils.js';
+
+/**
+ * A component for displaying webmentions fetched from a specified endpoint.
+ * @attribute hide-when-empty Whether to hide the webmentions section when there are no webmentions to display. Defaults to false.
+ * @attribute endpoint The webmention endpoint to fetch from.
+ * @attribute heading The heading to display above the webmentions. Defaults to "Mentions".
+ * @example <webmention-list heading="Read what others are saying" endpoint="https://example.com/webmention/endpoint" hide-when-empty="false"></webmention-list>/
+ */
+export class WebmentionList extends HTMLElement {
+    /**
+     * @type {string} The webmention endpoint to fetch from.
+     * @private
+     */
+    _endpoint;
+    /**
+     * The webmentions fetched from the endpoint.
+     * @type {Webmention[]}
+     * @private
+     */
+    _webmentions = [];
+    /**
+     * @type {boolean} Whether the last fetch was successful.
+     * @private
+     */
+    _ok;
+
+    constructor() {
+        super();
+    }
+
+    static observedAttributes = ['endpoint', 'heading', 'hide-when-empty'];
+
+    #escapeHtml(str) {
+        if (!str) {
+            return '';
+        }
+
+        const div = document.createElement('div');
+        div.textContent = str;
+        return div.innerHTML;
+    }
+
+    /**
+     * Sanitizes a URL to ensure it is a valid protocol relative URL.
+     * @param url The URL to sanitize.
+     * @return {string} The sanitized URL.
+     */
+    #sanitizeUrl(url) {
+        try {
+            const protocol = new URL(url, window.location.href).protocol;
+            return (protocol === 'http:' || protocol === 'https:') ? url : '#';
+        } catch (error) {
+            return '#';
+        }
+    }
+
+    async attributeChangedCallback(name, oldValue, newValue) {
+        if (oldValue !== newValue) {
+            switch (name) {
+                case 'endpoint':
+                    this._endpoint = newValue;
+                    break;
+                case 'heading':
+                    this._heading = newValue;
+                    break;
+                case 'hide-when-empty':
+                    this._hideWhenEmpty = newValue === 'true';
+                    break;
+                default:
+                    break;
+            }
+
+            if (this.isConnected) {
+                if (name === 'endpoint') {
+                    await this.fetch();
+                }
+                this.render();
+            }
+        }
+    }
+
+    connectedCallback() {
+        this._hideWhenEmpty = this.getAttribute('hide-when-empty') === 'true' || false;
+        this._endpoint = this.getAttribute('endpoint');
+        this._heading = this.getAttribute('heading') || 'Mentions';
+        this.fetch().then(() => this.render());
+    }
+
+    render() {
+        if (this._hideWhenEmpty && this._webmentions.length === 0) {
+            this.innerHTML = '';
+            return;
+        }
+
+        this.innerHTML = `
+            <section class="webmention">
+                <h2>${this.#escapeHtml(this._heading)}</h2>
+                <ul>${this._webmentions.map(webmention => `
+                    <li>
+                        <a href="${this.#sanitizeUrl(webmention.target)}">${this.#escapeHtml(webmention.mentionText)}</a> (from: <a href="${this.#sanitizeUrl(webmention.source)}">${this.#escapeHtml(webmention.source)})</a>
+                    </li>
+                `).join('')}                
+                </ul>
+            </section>`;
+    }
+
+    async fetch() {
+        const webmentionFetchResult =  fetchWebmentions(this._endpoint);
+        const { webmentions, ok } = await webmentionFetchResult;
+        this._webmentions = webmentions;
+        this._ok = ok;
+    }
+}
+
+if (!customElements.get('webmention-list')) {
+    customElements.define('webmention-list', WebmentionList);
+}