@zachleat/table-of-contents 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zach Leatherman
+
+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,41 @@
+# `<table-of-contents>`
+
+A zero-dependency web component that client renders a table of contents from the headings on the page and highlights the sections currently in view.
+
+## Installation
+
+```sh
+npm install @zachleat/table-of-contents
+```
+
+## Usage
+
+```html
+<script type="module" src="table-of-contents.js"></script>
+
+<nav aria-labelledby="toc-title">
+	<table-of-contents>
+		<h2 id="toc-title">Table of Contents</h2>
+	</table-of-contents>
+</nav>
+```
+
+Child content is kept and the list is added after it. Wrap it in a labeled `<nav>` so assistive technology can find it. The element is hidden when no headings match.
+
+Add `?nodefine` to skip auto-registration and define it yourself:
+
+```js
+import { TableOfContents } from "./table-of-contents.js?nodefine";
+
+TableOfContents.define("my-toc");
+```
+
+`?nodefine` reads `import.meta.url`, so it only works with unbundled ES modules.
+
+## Attributes
+
+- `selector`: headings to include (default `main :is(h2, h3, h4, h5, h6)`). Headings without an `id` are listed without a link.
+
+## Styling
+
+No styles are included. Links for sections in view get the `toc-in-view` class.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@zachleat/table-of-contents",
+  "version": "1.0.0",
+  "description": "A zero-dependency web component that client renders a table of contents from the headings on the page.",
+  "type": "module",
+  "main": "table-of-contents.js",
+  "exports": {
+    ".": "./table-of-contents.js",
+    "./table-of-contents.js": "./table-of-contents.js"
+  },
+  "files": [
+    "table-of-contents.js"
+  ],
+  "keywords": [
+    "web-components",
+    "custom-elements",
+    "table-of-contents"
+  ],
+  "author": "Zach Leatherman",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zachleat/table-of-contents.git"
+  },
+  "homepage": "https://github.com/zachleat/table-of-contents#readme",
+  "bugs": {
+    "url": "https://github.com/zachleat/table-of-contents/issues"
+  }
+}

package/table-of-contents.js

@@ -0,0 +1,149 @@
+export class TableOfContents extends HTMLElement {
+	static tagName = "table-of-contents";
+
+	static defaults = {
+		selector: "main :is(h2, h3, h4, h5, h6)",
+		activeClass: "toc-in-view",
+	};
+
+	static define(tagName = this.tagName, registry = globalThis.customElements) {
+		if(registry && !registry.get(tagName)) {
+			registry.define(tagName, this);
+		}
+	}
+
+	static getLevel(heading) {
+		return parseInt(heading.tagName.slice(1), 10);
+	}
+
+	// Ignores same-page anchor links and hidden decorations inside headings.
+	static getText(heading) {
+		let clone = heading.cloneNode(true);
+		for(let el of clone.querySelectorAll("a[href^='#'], button, script, style, template, [hidden], [aria-hidden='true']")) {
+			el.remove();
+		}
+		let text = clone.textContent.trim() || heading.textContent.trim();
+		return text.replace(/\s+/g, " ");
+	}
+
+	static generate(headings) {
+		let root = document.createElement("ol");
+		let stack = [{ level: this.getLevel(headings[0]), list: root }];
+		for(let heading of headings) {
+			let level = this.getLevel(heading);
+			let top = stack.at(-1);
+			let popped;
+
+			while(stack.length > 1 && level < top.level) {
+				popped = stack.pop();
+				top = stack.at(-1);
+			}
+
+			if(stack.length === 1 && level < top.level) {
+				top.level = level;
+			} else if(level > top.level) {
+				if(popped) {
+					popped.level = level;
+				} else {
+					popped = { level, list: document.createElement("ol") };
+					top.item.append(popped.list);
+				}
+				stack.push(popped);
+				top = popped;
+			}
+
+			let text = this.getText(heading);
+			top.item = document.createElement("li");
+
+			if(heading.id) {
+				let link = document.createElement("a");
+				link.setAttribute("href", `#${heading.id}`);
+				link.textContent = text;
+				top.item.append(link);
+			} else {
+				top.item.append(text);
+			}
+
+			top.list.append(top.item);
+		}
+
+		return root;
+	}
+
+	connectedCallback() {
+		if(document.readyState === "loading") {
+			document.addEventListener("DOMContentLoaded", () => this.init(), { once: true });
+		} else {
+			this.init();
+		}
+	}
+
+	disconnectedCallback() {
+		this.observer?.disconnect();
+	}
+
+	init() {
+		if(!this.isConnected) {
+			return;
+		}
+
+		let selector = this.getAttribute("selector") || TableOfContents.defaults.selector;
+		let headings = Array.from(document.querySelectorAll(selector)).filter(h => !this.contains(h));
+
+		// Existing child content is kept before the list.
+		this.list?.remove();
+		this.list = undefined;
+		this.observer?.disconnect();
+
+		// Hide when empty, without overriding an author-set `hidden`.
+		if(this.hiddenWhenEmpty) {
+			this.hidden = false;
+		}
+		this.hiddenWhenEmpty = headings.length === 0 && !this.hidden;
+		if(headings.length === 0) {
+			this.hidden = true;
+			return;
+		}
+
+		this.list = TableOfContents.generate(headings);
+		this.append(this.list);
+		this.observe(headings);
+	}
+
+	// A heading is active while it or any content before the next heading is visible.
+	observe(headings) {
+		this.observer?.disconnect();
+
+		let headingSet = new Set(headings);
+		let targets = new Map();
+		let visible = new Set();
+
+		this.observer = new IntersectionObserver(entries => {
+			for(let entry of entries) {
+				visible[entry.isIntersecting ? "add" : "delete"](entry.target);
+			}
+
+			let activeIds = new Set(Array.from(visible, el => targets.get(el)));
+			for(let link of this.list.querySelectorAll("a[href^='#']")) {
+				let id = link.getAttribute("href").slice(1);
+				link.classList.toggle(TableOfContents.defaults.activeClass, activeIds.has(id));
+			}
+		});
+
+		for(let heading of headings) {
+			if(!heading.id) {
+				continue;
+			}
+
+			let el = heading;
+			do {
+				targets.set(el, heading.id);
+				this.observer.observe(el);
+			} while((el = el.nextElementSibling) && !headingSet.has(el));
+		}
+	}
+}
+
+if(!new URL(import.meta.url).searchParams.has("nodefine")) {
+	TableOfContents.define();
+}