@zachleat/table-of-contents 1.0.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # `<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.
+A zero-dependency web component that progressively enhances (or optionally client renders) a table of contents from the headings on the page and highlights visible sections. This component includes no styles (all visuals are app-code controlled).
 
 ## Installation
 
@@ -22,6 +22,10 @@ npm install @zachleat/table-of-contents
 
 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.
 
+Entries for headings hidden by CSS (e.g. `display: none` on an ancestor) get the `hidden` attribute and update when visibility changes. The element is hidden when every heading is hidden.
+
+A child `<ol>` or `<ul>` (for example, server-rendered) is used instead of generating one, and its `#` links are highlighted for headings matching `selector`.
+
 Add `?nodefine` to skip auto-registration and define it yourself:
 
 ```js
@@ -39,3 +43,7 @@ TableOfContents.define("my-toc");
 ## Styling
 
 No styles are included. Links for sections in view get the `toc-in-view` class.
+
+# Changelog
+
+- `v2.0.0` tracks display of heading elements (and hides links when display is toggled off)

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "2.0.0",
+  "description": "A zero-dependency web component that progressively enhances (or optionally client renders) a table of contents from the headings on the page and highlights visible sections.",
   "type": "module",
   "main": "table-of-contents.js",
   "exports": {

package/table-of-contents.js

@@ -26,7 +26,12 @@ export class TableOfContents extends HTMLElement {
 		return text.replace(/\s+/g, " ");
 	}
 
-	static generate(headings) {
+	static isVisible(heading) {
+		return heading.checkVisibility?.() ?? true;
+	}
+
+	// `items` (optional) receives each generated <li> mapped to its heading.
+	static generate(headings, items) {
 		let root = document.createElement("ol");
 		let stack = [{ level: this.getLevel(headings[0]), list: root }];
 		for(let heading of headings) {
@@ -65,6 +70,7 @@ export class TableOfContents extends HTMLElement {
 			}
 
 			top.list.append(top.item);
+			items?.set(top.item, heading);
 		}
 
 		return root;
@@ -80,6 +86,18 @@ export class TableOfContents extends HTMLElement {
 
 	disconnectedCallback() {
 		this.observer?.disconnect();
+		this.resizeObserver?.disconnect();
+	}
+
+	// Hides the element without overriding an author-set `hidden`.
+	setAutoHidden(force) {
+		if(this.autoHidden) {
+			this.hidden = false;
+		}
+		this.autoHidden = force && !this.hidden;
+		if(force) {
+			this.hidden = true;
+		}
 	}
 
 	init() {
@@ -90,24 +108,62 @@ export class TableOfContents extends HTMLElement {
 		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();
+		this.resizeObserver?.disconnect();
+		this.generatedList?.remove();
+		this.generatedList = undefined;
 
-		// 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;
+		// A child list (e.g. server-rendered) is used as-is.
+		this.list = this.querySelector(":scope > :is(ol, ul)");
+
+		let empty = !this.list && headings.length === 0;
+		this.setAutoHidden(empty);
+		if(empty) {
 			return;
 		}
 
-		this.list = TableOfContents.generate(headings);
-		this.append(this.list);
+		let items = new Map();
+		if(this.list) {
+			for(let heading of headings) {
+				if(heading.id) {
+					for(let link of this.list.querySelectorAll(`a[href="#${CSS.escape(heading.id)}"]`)) {
+						items.set(link.closest("li"), heading);
+					}
+				}
+			}
+			items.delete(null);
+		} else {
+			// Existing child content is kept before the generated list.
+			this.list = this.generatedList = TableOfContents.generate(headings, items);
+			this.append(this.list);
+		}
+
 		this.observe(headings);
+		this.observeVisibility(headings, items);
+	}
+
+	// Hides entries for headings hidden by CSS (e.g. `display: none` on an ancestor).
+	observeVisibility(headings, items) {
+		let update = () => {
+			let visible = new Map(headings.map(h => [h, TableOfContents.isVisible(h)]));
+
+			// Reverse order so nested entries are updated before their parents.
+			for(let li of Array.from(this.list.querySelectorAll("li")).reverse()) {
+				let heading = items.get(li);
+				if(heading) {
+					li.hidden = !visible.get(heading) && !li.querySelector("li:not([hidden])");
+				}
+			}
+
+			this.setAutoHidden(headings.length > 0 && !headings.some(h => visible.get(h)));
+		};
+
+		update();
+
+		this.resizeObserver = new ResizeObserver(update);
+		for(let heading of headings) {
+			this.resizeObserver.observe(heading);
+		}
 	}
 
 	// A heading is active while it or any content before the next heading is visible.