@substrate-system/markdown-toc 1.3.8 → 1.4.1

package/README.md

@@ -11,6 +11,10 @@ This is a fork of [jonschlinkert/markdown-toc](https://github.com/jonschlinkert/
 <details>
 <summary><h2>Contents</h2></summary>
 
+- [Install](#install)
+- [Quickstart](#quick-start)
+- [CLI](#cli)
+- [SPA](#spa)
 - [Highlights](#highlights)
 - [Usage](#usage)
 - [API](#api)
@@ -32,24 +36,12 @@ This is a fork of [jonschlinkert/markdown-toc](https://github.com/jonschlinkert/
 
 ## Install
 
-Install with [npm](https://www.npmjs.com/):
+Install with [npm](https://www.npmjs.com/).
 
 ```sh
-npm i @substrate-system/markdown-toc
+npm i -D @substrate-system/markdown-toc
 ```
 
-# Sponsors
-
-Thanks to the following companies, organizations, and individuals for supporting the ongoing maintenance and development of markdown-toc! [Become a Sponsor](https://github.com/sponsors/jonschlinkert) to add your logo to this README, or any of [my other projects](https://github.com/jonschlinkert?tab=repositories&q=&type=&language=&sort=stargazers)
-
-## Gold Sponsors
-
-| [<img src="https://github.com/jonschlinkert/clone-deep/assets/383994/98036489-2cae-48a2-8d29-7dec58ea05c4" alt="https://jaake.tech/" width="100"/>](https://jaake.tech/) |
-|:---:|
-| [https://jaake.tech/](https://jaake.tech/) |
-
-<br />
-
 ## Quick Start
 
 Assuming you want to add a TOC to README.md:
@@ -106,6 +98,74 @@ _(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](
                 (to specify a tab, use the bash-escaped $'\t')
 ```
 
+## SPA
+
+Create a table of contents in a client-side-rendered app.
+
+Pass `toc` an element, or a ref to an element, instead of a markdown
+string. It reads the headings inside that element, gives each heading
+without an `id` a slug `id`, and returns the same result object as the
+markdown version (see [API](#api)). Options like `maxdepth` work the same
+way, and `json` only includes headings within `maxdepth`.
+
+```ts
+import { toc, type TocHeading } from '@substrate-system/markdown-toc'
+import { html } from 'htm/preact'
+import { type FunctionComponent } from 'preact'
+import { useLayoutEffect, useRef, useState } from 'preact/hooks'
+
+export const Main:FunctionComponent = function () {
+  const div = useRef<HTMLDivElement>(null)
+  const [tocJson, setTocJson] = useState<TocHeading[]>([])
+
+  // after the first render, so the headings are in the DOM
+  useLayoutEffect(() => {
+    if (!div.current) return
+    setTocJson(toc(div, { maxdepth: 3 }).json)
+  }, [])
+
+  return html`<div ref=${div} class="example">
+    <h2>Contents</h2>
+    <ul>
+      ${tocJson.map((t) => {
+        return html`<li><a href="#${t.slug}">${t.content}</a></li>`
+      })}
+    </ul>
+    <h2>Example</h2>
+    <h3>Level 3</h3>
+    hello
+    <h4>Level 4</h4>
+  </div>`
+}
+```
+
+### Preact
+
+Because I like `preact`, this includes a ready-to-use preact component.
+`preact` is an optional peer dependency.
+
+`<TOC />` renders a `<nav>` with a nested list of links to the headings
+that come *after* it in the document, so a heading above it (like the
+`Contents` title here) is left out. It takes the same options as `toc`,
+as props. The list updates when headings are added, removed, or changed.
+
+```tsx
+import { TOC } from '@substrate-system/markdown-toc/preact'
+import { type FunctionComponent } from 'preact'
+
+export const Main:FunctionComponent = function () {
+  return <main>
+    <details>
+      <summary><h2>Contents</h2></summary>
+      <TOC maxdepth={3} />
+    </details>
+
+    <h2>Hello Table of Contents</h2>
+    <h3>more testing</h3>
+  </main>
+}
+```
+
 ## Highlights
 
 **Features**
@@ -126,7 +186,7 @@ _(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](
 ## Usage
 
 ```js
-import {toc} from '@substrate-system/markdown-toc'
+import { toc } from '@substrate-system/markdown-toc'
 
 toc('# One\n\n# Two').content;
 // Results in:
@@ -147,7 +207,7 @@ To allow customization of the output, an object is returned with the following p
 Use as a [remarkable](https://github.com/jonschlinkert/remarkable) plugin.
 
 ```js
-import {Remarkable, toc} from '@substrate-system/markdown-toc'
+import { Remarkable, toc } from '@substrate-system/markdown-toc'
 
 function render(str, options) {
   return new Remarkable()
@@ -175,7 +235,7 @@ Results in:
 Object for creating a custom TOC.
 
 ```js
-import {toc} from '@substrate-system/markdown-toc'
+import { toc } from '@substrate-system/markdown-toc'
 
 toc('# AAA\n## BBB\n### CCC\nfoo').json;
 
@@ -187,9 +247,12 @@ toc('# AAA\n## BBB\n### CCC\nfoo').json;
 
 ### toc.insert
 
-Insert a table of contents immediately after an _opening_ `<!-- toc -->` code comment, or replace an existing TOC if both an _opening_ comment and a _closing_ comment (`<!-- tocstop -->`) are found.
+Insert a table of contents immediately after an _opening_ `<!-- toc -->` code
+comment, or replace an existing TOC if both an _opening_ comment and
+a _closing_ comment (`<!-- tocstop -->`) are found.
 
-_(This strategy works well since code comments in markdown are hidden when viewed as HTML, like when viewing a README on GitHub README for example)._
+_(This strategy works well since code comments in markdown are hidden when_
+_viewed as HTML, like when viewing a README on GitHub README for example)._
 
 **Example**
 

package/dist/dom.js

@@ -0,0 +1,80 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+import { renderBullets, slugify, titleize } from "./markdown-toc.js";
+const HEADINGS = "h1, h2, h3, h4, h5, h6";
+function domToc(target, options = {}) {
+  const root = resolveTarget(target);
+  return headingsToc(Array.from(root.querySelectorAll(HEADINGS)), options);
+}
+__name(domToc, "domToc");
+function headingsToc(elements, options = {}) {
+  const maxdepth = options.maxdepth ?? 6;
+  const headings = elements.filter((el) => headingLevel(el) <= maxdepth);
+  const used = new Set(headings.map((el) => el.id).filter(Boolean));
+  const seen = {};
+  const json = [];
+  const tokens = [];
+  headings.forEach((el, i) => {
+    const content2 = (el.textContent ?? "").trim();
+    const seenCount = seen[content2] ?? 0;
+    seen[content2] = seenCount + 1;
+    if (!el.id) {
+      el.id = uniqueSlug(content2, seenCount, used, options);
+      used.add(el.id);
+    }
+    const slug = el.id;
+    const lvl = headingLevel(el);
+    const text = titleize(content2, options);
+    json.push({ content: content2, slug, lvl, i, seen: seenCount });
+    tokens.push({
+      type: "inline",
+      content: `[${text}](#${encodeURIComponent(slug)})`,
+      lvl,
+      i,
+      seen: seenCount,
+      slug
+    });
+  });
+  const highest = tokens.reduce((min, token) => {
+    return Math.min(min, token.lvl ?? 0);
+  }, tokens.length ? Number.POSITIVE_INFINITY : 0);
+  const content = renderBullets(
+    options.firsth1 === false ? tokens.slice(1) : tokens,
+    { ...options, highest }
+  ) + (options.append ?? "");
+  return { content, highest, json, tokens };
+}
+__name(headingsToc, "headingsToc");
+function headingLevel(el) {
+  return Number(el.tagName.slice(1));
+}
+__name(headingLevel, "headingLevel");
+function resolveTarget(target) {
+  if ("current" in target) {
+    if (!target.current) {
+      throw new TypeError("toc: the ref has no element yet");
+    }
+    return target.current;
+  }
+  return target;
+}
+__name(resolveTarget, "resolveTarget");
+function uniqueSlug(content, seenCount, used, options) {
+  let num = seenCount;
+  let slug = slugify(content, { ...options, num });
+  while (used.has(slug)) {
+    num++;
+    const next = slugify(content, { ...options, num });
+    if (next === slug) break;
+    slug = next;
+  }
+  return slug;
+}
+__name(uniqueSlug, "uniqueSlug");
+export {
+  HEADINGS,
+  domToc,
+  headingLevel,
+  headingsToc
+};
+//# sourceMappingURL=dom.js.map

package/dist/dom.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/dom.ts"],
+  "sourcesContent": ["import { renderBullets, slugify, titleize } from './markdown-toc.js'\nimport type {\n    TocHeading,\n    TocOptions,\n    TocResult,\n    TocToken,\n} from './types.js'\n\n/**\n * Something we can read headings from: an element, a document, or a\n * ref object like the one returned by preact's `useRef`.\n */\nexport type TocTarget = ParentNode|{ readonly current:ParentNode|null }\n\nexport const HEADINGS = 'h1, h2, h3, h4, h5, h6'\n\n/**\n * Create a table of contents from the headings inside `target`.\n * Headings without an `id` get one, so the generated links work.\n */\nexport function domToc (\n    target:TocTarget,\n    options:Readonly<TocOptions> = {},\n):TocResult {\n    const root = resolveTarget(target)\n    return headingsToc(Array.from(root.querySelectorAll(HEADINGS)), options)\n}\n\n/**\n * Create a table of contents from a list of heading elements.\n */\nexport function headingsToc (\n    elements:ReadonlyArray<Element>,\n    options:Readonly<TocOptions> = {},\n):TocResult {\n    const maxdepth = options.maxdepth ?? 6\n    const headings = elements.filter(el => headingLevel(el) <= maxdepth)\n    const used = new Set(headings.map(el => el.id).filter(Boolean))\n    const seen:Record<string, number> = {}\n    const json:Array<TocHeading> = []\n    const tokens:Array<TocToken> = []\n\n    headings.forEach((el, i) => {\n        const content = (el.textContent ?? '').trim()\n        const seenCount = seen[content] ?? 0\n        seen[content] = seenCount + 1\n\n        if (!el.id) {\n            el.id = uniqueSlug(content, seenCount, used, options)\n            used.add(el.id)\n        }\n\n        const slug = el.id\n        const lvl = headingLevel(el)\n        const text = titleize(content, options)\n        json.push({ content, slug, lvl, i, seen:seenCount })\n        tokens.push({\n            type:'inline',\n            content:`[${text}](#${encodeURIComponent(slug)})`,\n            lvl,\n            i,\n            seen:seenCount,\n            slug,\n        })\n    })\n\n    const highest = tokens.reduce((min, token) => {\n        return Math.min(min, token.lvl ?? 0)\n    }, tokens.length ? Number.POSITIVE_INFINITY : 0)\n    const content = renderBullets(\n        options.firsth1 === false ? tokens.slice(1) : tokens,\n        { ...options, highest }\n    ) + (options.append ?? '')\n\n    return { content, highest, json, tokens }\n}\n\n/**\n * Get the heading level from the tag name, `h3` -> 3.\n */\nexport function headingLevel (el:Element):number {\n    return Number(el.tagName.slice(1))\n}\n\nfunction resolveTarget (target:TocTarget):ParentNode {\n    if ('current' in target) {\n        if (!target.current) {\n            throw new TypeError('toc: the ref has no element yet')\n        }\n        return target.current\n    }\n    return target\n}\n\n/**\n * Slugify the heading text, then bump the number suffix until the slug\n * does not collide with an id that is already in use.\n */\nfunction uniqueSlug (\n    content:string,\n    seenCount:number,\n    used:ReadonlySet<string>,\n    options:Readonly<TocOptions>,\n):string {\n    let num = seenCount\n    let slug = slugify(content, { ...options, num })\n    while (used.has(slug)) {\n        num++\n        const next = slugify(content, { ...options, num })\n        // a custom slugify, or `slugify:false`, may ignore `num`\n        if (next === slug) break\n        slug = next\n    }\n    return slug\n}\n"],
+  "mappings": ";;AAAA,SAAS,eAAe,SAAS,gBAAgB;AAc1C,MAAM,WAAW;AAMjB,SAAS,OACZ,QACA,UAA+B,CAAC,GACxB;AACR,QAAM,OAAO,cAAc,MAAM;AACjC,SAAO,YAAY,MAAM,KAAK,KAAK,iBAAiB,QAAQ,CAAC,GAAG,OAAO;AAC3E;AANgB;AAWT,SAAS,YACZ,UACA,UAA+B,CAAC,GACxB;AACR,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,WAAW,SAAS,OAAO,QAAM,aAAa,EAAE,KAAK,QAAQ;AACnE,QAAM,OAAO,IAAI,IAAI,SAAS,IAAI,QAAM,GAAG,EAAE,EAAE,OAAO,OAAO,CAAC;AAC9D,QAAM,OAA8B,CAAC;AACrC,QAAM,OAAyB,CAAC;AAChC,QAAM,SAAyB,CAAC;AAEhC,WAAS,QAAQ,CAAC,IAAI,MAAM;AACxB,UAAMA,YAAW,GAAG,eAAe,IAAI,KAAK;AAC5C,UAAM,YAAY,KAAKA,QAAO,KAAK;AACnC,SAAKA,QAAO,IAAI,YAAY;AAE5B,QAAI,CAAC,GAAG,IAAI;AACR,SAAG,KAAK,WAAWA,UAAS,WAAW,MAAM,OAAO;AACpD,WAAK,IAAI,GAAG,EAAE;AAAA,IAClB;AAEA,UAAM,OAAO,GAAG;AAChB,UAAM,MAAM,aAAa,EAAE;AAC3B,UAAM,OAAO,SAASA,UAAS,OAAO;AACtC,SAAK,KAAK,EAAE,SAAAA,UAAS,MAAM,KAAK,GAAG,MAAK,UAAU,CAAC;AACnD,WAAO,KAAK;AAAA,MACR,MAAK;AAAA,MACL,SAAQ,IAAI,IAAI,MAAM,mBAAmB,IAAI,CAAC;AAAA,MAC9C;AAAA,MACA;AAAA,MACA,MAAK;AAAA,MACL;AAAA,IACJ,CAAC;AAAA,EACL,CAAC;AAED,QAAM,UAAU,OAAO,OAAO,CAAC,KAAK,UAAU;AAC1C,WAAO,KAAK,IAAI,KAAK,MAAM,OAAO,CAAC;AAAA,EACvC,GAAG,OAAO,SAAS,OAAO,oBAAoB,CAAC;AAC/C,QAAM,UAAU;AAAA,IACZ,QAAQ,YAAY,QAAQ,OAAO,MAAM,CAAC,IAAI;AAAA,IAC9C,EAAE,GAAG,SAAS,QAAQ;AAAA,EAC1B,KAAK,QAAQ,UAAU;AAEvB,SAAO,EAAE,SAAS,SAAS,MAAM,OAAO;AAC5C;AA5CgB;AAiDT,SAAS,aAAc,IAAmB;AAC7C,SAAO,OAAO,GAAG,QAAQ,MAAM,CAAC,CAAC;AACrC;AAFgB;AAIhB,SAAS,cAAe,QAA6B;AACjD,MAAI,aAAa,QAAQ;AACrB,QAAI,CAAC,OAAO,SAAS;AACjB,YAAM,IAAI,UAAU,iCAAiC;AAAA,IACzD;AACA,WAAO,OAAO;AAAA,EAClB;AACA,SAAO;AACX;AARS;AAcT,SAAS,WACL,SACA,WACA,MACA,SACK;AACL,MAAI,MAAM;AACV,MAAI,OAAO,QAAQ,SAAS,EAAE,GAAG,SAAS,IAAI,CAAC;AAC/C,SAAO,KAAK,IAAI,IAAI,GAAG;AACnB;AACA,UAAM,OAAO,QAAQ,SAAS,EAAE,GAAG,SAAS,IAAI,CAAC;AAEjD,QAAI,SAAS,KAAM;AACnB,WAAO;AAAA,EACX;AACA,SAAO;AACX;AAhBS;",
+  "names": ["content"]
+}

package/dist/index.js

@@ -13,8 +13,9 @@ import {
   titleize as titleizeHeading
 } from "./markdown-toc.js";
 import { insertMarkdown } from "./insert-markdown.js";
-function toc(markdown, options = {}) {
-  return generateToc(markdown, options);
+import { domToc } from "./dom.js";
+function toc(source, options = {}) {
+  return typeof source === "string" ? generateToc(source, options) : domToc(source, options);
 }
 __name(toc, "toc");
 const utils = {

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["import Remarkable from 'remarkable'\nimport {\n    generatePlugin,\n    generateToc,\n    getHighest,\n    getTitle,\n    linkify as linkifyHeading,\n    renderBullets,\n    slugify as slugifyHeading,\n    strip as stripHeading,\n    titleize as titleizeHeading,\n} from './markdown-toc.js'\nimport { insertMarkdown } from './insert-markdown.js'\nimport type { TocOptions, TocResult, TocUtils } from './types.js'\n\nexport type * from './types.js'\nexport { Remarkable }\nexport {\n    generatePlugin as plugin,\n    generateToc,\n    getHighest,\n    getTitle,\n    insertMarkdown,\n    linkifyHeading as linkify,\n    renderBullets,\n    slugifyHeading as slugify,\n    stripHeading as strip,\n    titleizeHeading as titleize,\n}\nexport { renderBullets as bullets }\n\nexport function toc (\n    markdown:string,\n    options:Readonly<TocOptions> = {},\n):TocResult {\n    return generateToc(markdown, options)\n}\n\nexport const utils:TocUtils = {\n    Remarkable,\n    getTitle,\n    slugify:slugifyHeading,\n    strip:stripHeading,\n    titleize:titleizeHeading,\n}\n"],
-  "mappings": ";;AAAA,OAAO,gBAAgB;AACvB;AAAA,EACI;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,WAAW;AAAA,EACX;AAAA,EACA,WAAW;AAAA,EACX,SAAS;AAAA,EACT,YAAY;AAAA,OACT;AACP,SAAS,sBAAsB;AAmBxB,SAAS,IACZ,UACA,UAA+B,CAAC,GACxB;AACR,SAAO,YAAY,UAAU,OAAO;AACxC;AALgB;AAOT,MAAM,QAAiB;AAAA,EAC1B;AAAA,EACA;AAAA,EACA,SAAQ;AAAA,EACR,OAAM;AAAA,EACN,UAAS;AACb;",
+  "sourcesContent": ["import Remarkable from 'remarkable'\nimport {\n    generatePlugin,\n    generateToc,\n    getHighest,\n    getTitle,\n    linkify as linkifyHeading,\n    renderBullets,\n    slugify as slugifyHeading,\n    strip as stripHeading,\n    titleize as titleizeHeading,\n} from './markdown-toc.js'\nimport { insertMarkdown } from './insert-markdown.js'\nimport { domToc, type TocTarget } from './dom.js'\nimport type { TocOptions, TocResult, TocUtils } from './types.js'\n\nexport type * from './types.js'\nexport type { TocTarget }\nexport { Remarkable }\nexport {\n    generatePlugin as plugin,\n    generateToc,\n    getHighest,\n    getTitle,\n    insertMarkdown,\n    linkifyHeading as linkify,\n    renderBullets,\n    slugifyHeading as slugify,\n    stripHeading as strip,\n    titleizeHeading as titleize,\n}\nexport { renderBullets as bullets }\n\n/**\n * Create a table of contents from a markdown string, or, in a browser,\n * from the headings inside an element (or a ref to an element).\n */\nexport function toc (\n    markdown:string,\n    options?:Readonly<TocOptions>,\n):TocResult\nexport function toc (\n    target:TocTarget,\n    options?:Readonly<TocOptions>,\n):TocResult\nexport function toc (\n    source:string|TocTarget,\n    options:Readonly<TocOptions> = {},\n):TocResult {\n    return typeof source === 'string' ?\n        generateToc(source, options) :\n        domToc(source, options)\n}\n\nexport const utils:TocUtils = {\n    Remarkable,\n    getTitle,\n    slugify:slugifyHeading,\n    strip:stripHeading,\n    titleize:titleizeHeading,\n}\n"],
+  "mappings": ";;AAAA,OAAO,gBAAgB;AACvB;AAAA,EACI;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,WAAW;AAAA,EACX;AAAA,EACA,WAAW;AAAA,EACX,SAAS;AAAA,EACT,YAAY;AAAA,OACT;AACP,SAAS,sBAAsB;AAC/B,SAAS,cAA8B;AAgChC,SAAS,IACZ,QACA,UAA+B,CAAC,GACxB;AACR,SAAO,OAAO,WAAW,WACrB,YAAY,QAAQ,OAAO,IAC3B,OAAO,QAAQ,OAAO;AAC9B;AAPgB;AAST,MAAM,QAAiB;AAAA,EAC1B;AAAA,EACA;AAAA,EACA,SAAQ;AAAA,EACR,OAAM;AAAA,EACN,UAAS;AACb;",
   "names": []
 }

package/dist/meta.json

@@ -1,7 +1,7 @@
 {
   "inputs": {
     "src/index.ts": {
-      "bytes": 1028,
+      "bytes": 1507,
       "imports": [],
       "format": "esm"
     },
@@ -19,6 +19,16 @@
       "bytes": 1454,
       "imports": [],
       "format": "esm"
+    },
+    "src/dom.ts": {
+      "bytes": 3320,
+      "imports": [],
+      "format": "esm"
+    },
+    "src/preact.ts": {
+      "bytes": 3742,
+      "imports": [],
+      "format": "esm"
     }
   },
   "outputs": {
@@ -26,7 +36,7 @@
       "imports": [],
       "exports": [],
       "inputs": {},
-      "bytes": 1510
+      "bytes": 2059
     },
     "dist/index.js": {
       "imports": [
@@ -44,6 +54,11 @@
           "path": "./insert-markdown.js",
           "kind": "import-statement",
           "external": true
+        },
+        {
+          "path": "./dom.js",
+          "kind": "import-statement",
+          "external": true
         }
       ],
       "exports": [
@@ -65,10 +80,10 @@
       "entryPoint": "src/index.ts",
       "inputs": {
         "src/index.ts": {
-          "bytesInOutput": 543
+          "bytesInOutput": 629
         }
       },
-      "bytes": 993
+      "bytes": 1079
     },
     "dist/cli.js.map": {
       "imports": [],
@@ -172,6 +187,74 @@
         }
       },
       "bytes": 1518
+    },
+    "dist/dom.js.map": {
+      "imports": [],
+      "exports": [],
+      "inputs": {},
+      "bytes": 5277
+    },
+    "dist/dom.js": {
+      "imports": [
+        {
+          "path": "./markdown-toc.js",
+          "kind": "import-statement",
+          "external": true
+        }
+      ],
+      "exports": [
+        "HEADINGS",
+        "domToc",
+        "headingLevel",
+        "headingsToc"
+      ],
+      "entryPoint": "src/dom.ts",
+      "inputs": {
+        "src/dom.ts": {
+          "bytesInOutput": 2254
+        }
+      },
+      "bytes": 2479
+    },
+    "dist/preact.js.map": {
+      "imports": [],
+      "exports": [],
+      "inputs": {},
+      "bytes": 6030
+    },
+    "dist/preact.js": {
+      "imports": [
+        {
+          "path": "preact",
+          "kind": "import-statement",
+          "external": true
+        },
+        {
+          "path": "preact/hooks",
+          "kind": "import-statement",
+          "external": true
+        },
+        {
+          "path": "./dom.js",
+          "kind": "import-statement",
+          "external": true
+        },
+        {
+          "path": "./markdown-toc.js",
+          "kind": "import-statement",
+          "external": true
+        }
+      ],
+      "exports": [
+        "TOC"
+      ],
+      "entryPoint": "src/preact.ts",
+      "inputs": {
+        "src/preact.ts": {
+          "bytesInOutput": 2680
+        }
+      },
+      "bytes": 2862
     }
   }
 }

package/dist/preact.js

@@ -0,0 +1,93 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+import { h } from "preact";
+import { useLayoutEffect, useRef, useState } from "preact/hooks";
+import { HEADINGS, headingsToc } from "./dom.js";
+import { titleize } from "./markdown-toc.js";
+const TOC = /* @__PURE__ */ __name(function TOC2(props) {
+  const { class: className, children: _children, ...options } = props;
+  const nav = useRef(null);
+  const latestOptions = useRef(options);
+  latestOptions.current = options;
+  const update = useRef(() => {
+  });
+  const [headings, setHeadings] = useState([]);
+  useLayoutEffect(() => {
+    const el = nav.current;
+    if (!el) return;
+    update.current = () => {
+      const next = headingsToc(
+        headingsAfter(el),
+        latestOptions.current
+      ).json;
+      setHeadings((prev) => isSame(prev, next) ? prev : next);
+    };
+    const observer = new MutationObserver(() => update.current());
+    observer.observe(el.ownerDocument.body, {
+      childList: true,
+      subtree: true,
+      characterData: true
+    });
+    return () => {
+      observer.disconnect();
+      update.current = () => {
+      };
+    };
+  }, []);
+  useLayoutEffect(() => update.current());
+  return h("nav", {
+    ref: nav,
+    class: className,
+    "aria-label": "Table of contents"
+  }, headings.length ? renderList(toTree(headings)) : null);
+}, "TOC");
+function headingsAfter(el) {
+  const all = Array.from(el.ownerDocument.querySelectorAll(HEADINGS));
+  return all.filter((heading) => {
+    const position = el.compareDocumentPosition(heading);
+    return Boolean(position & Node.DOCUMENT_POSITION_FOLLOWING) && !el.contains(heading);
+  });
+}
+__name(headingsAfter, "headingsAfter");
+function toTree(headings) {
+  const roots = [];
+  const stack = [];
+  for (const heading of headings) {
+    const node = { heading, children: [] };
+    while (stack.length && stack[stack.length - 1].heading.lvl >= heading.lvl) {
+      stack.pop();
+    }
+    const parent = stack[stack.length - 1];
+    if (parent) parent.children.push(node);
+    else roots.push(node);
+    stack.push(node);
+  }
+  return roots;
+}
+__name(toTree, "toTree");
+function renderList(nodes) {
+  return h("ul", null, nodes.map(({ heading, children }) => {
+    return h(
+      "li",
+      { key: heading.slug },
+      h(
+        "a",
+        { href: "#" + encodeURIComponent(heading.slug) },
+        titleize(heading.content)
+      ),
+      children.length ? renderList(children) : null
+    );
+  }));
+}
+__name(renderList, "renderList");
+function isSame(a, b) {
+  return a.length === b.length && a.every((heading, i) => {
+    const other = b[i];
+    return heading.slug === other.slug && heading.content === other.content && heading.lvl === other.lvl;
+  });
+}
+__name(isSame, "isSame");
+export {
+  TOC
+};
+//# sourceMappingURL=preact.js.map

package/dist/preact.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/preact.ts"],
+  "sourcesContent": ["import { h, type FunctionComponent, type VNode } from 'preact'\nimport { useLayoutEffect, useRef, useState } from 'preact/hooks'\nimport { HEADINGS, headingsToc } from './dom.js'\nimport { titleize } from './markdown-toc.js'\nimport type { TocHeading, TocOptions } from './types.js'\n\nexport type TocProps = TocOptions&{\n    class?:string;\n}\n\ntype TocNode = {\n    heading:TocHeading;\n    children:TocNode[];\n}\n\n/**\n * Render a nested list of links to the headings that come after this\n * component in the document. Headings without an `id` get one. The list\n * updates when the document changes.\n */\nexport const TOC:FunctionComponent<TocProps> = function TOC (props) {\n    const { class:className, children:_children, ...options } = props\n    const nav = useRef<HTMLElement>(null)\n    const latestOptions = useRef<TocOptions>(options)\n    latestOptions.current = options\n    const update = useRef<() => void>(() => {})\n    const [headings, setHeadings] = useState<TocHeading[]>([])\n\n    useLayoutEffect(() => {\n        const el = nav.current\n        if (!el) return\n\n        update.current = () => {\n            const next = headingsToc(\n                headingsAfter(el),\n                latestOptions.current\n            ).json\n            setHeadings(prev => isSame(prev, next) ? prev : next)\n        }\n\n        // Watch structure and text only. Adding an `id` is an attribute\n        // change, so it does not trigger another update.\n        const observer = new MutationObserver(() => update.current())\n        observer.observe(el.ownerDocument.body, {\n            childList:true,\n            subtree:true,\n            characterData:true,\n        })\n\n        return () => {\n            observer.disconnect()\n            update.current = () => {}\n        }\n    }, [])\n\n    // re-check after every render, in case the options changed\n    useLayoutEffect(() => update.current())\n\n    return h('nav', {\n        ref:nav,\n        class:className,\n        'aria-label':'Table of contents',\n    }, headings.length ? renderList(toTree(headings)) : null)\n}\n\n/**\n * Headings that come after `el` in document order.\n */\nfunction headingsAfter (el:Element):Element[] {\n    const all = Array.from(el.ownerDocument.querySelectorAll(HEADINGS))\n    return all.filter(heading => {\n        const position = el.compareDocumentPosition(heading)\n        return Boolean(position & Node.DOCUMENT_POSITION_FOLLOWING) &&\n            !el.contains(heading)\n    })\n}\n\n/**\n * Nest each heading under the closest previous heading with a lower\n * level.\n */\nfunction toTree (headings:ReadonlyArray<TocHeading>):TocNode[] {\n    const roots:TocNode[] = []\n    const stack:TocNode[] = []\n\n    for (const heading of headings) {\n        const node:TocNode = { heading, children:[] }\n        while (stack.length && stack[stack.length - 1]!.heading.lvl >=\n            heading.lvl) {\n            stack.pop()\n        }\n        const parent = stack[stack.length - 1]\n        if (parent) parent.children.push(node)\n        else roots.push(node)\n        stack.push(node)\n    }\n\n    return roots\n}\n\nfunction renderList (nodes:ReadonlyArray<TocNode>):VNode {\n    return h('ul', null, nodes.map(({ heading, children }) => {\n        return h('li', { key:heading.slug },\n            h('a', { href:'#' + encodeURIComponent(heading.slug) },\n                titleize(heading.content)),\n            children.length ? renderList(children) : null\n        )\n    }))\n}\n\nfunction isSame (\n    a:ReadonlyArray<TocHeading>,\n    b:ReadonlyArray<TocHeading>,\n):boolean {\n    return a.length === b.length && a.every((heading, i) => {\n        const other = b[i]!\n        return heading.slug === other.slug &&\n            heading.content === other.content &&\n            heading.lvl === other.lvl\n    })\n}\n"],
+  "mappings": "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",
+  "names": ["TOC"]
+}

package/dist/src/dom.d.ts

@@ -0,0 +1,23 @@
+import type { TocOptions, TocResult } from './types.js';
+/**
+ * Something we can read headings from: an element, a document, or a
+ * ref object like the one returned by preact's `useRef`.
+ */
+export type TocTarget = ParentNode | {
+    readonly current: ParentNode | null;
+};
+export declare const HEADINGS = "h1, h2, h3, h4, h5, h6";
+/**
+ * Create a table of contents from the headings inside `target`.
+ * Headings without an `id` get one, so the generated links work.
+ */
+export declare function domToc(target: TocTarget, options?: Readonly<TocOptions>): TocResult;
+/**
+ * Create a table of contents from a list of heading elements.
+ */
+export declare function headingsToc(elements: ReadonlyArray<Element>, options?: Readonly<TocOptions>): TocResult;
+/**
+ * Get the heading level from the tag name, `h3` -> 3.
+ */
+export declare function headingLevel(el: Element): number;
+//# sourceMappingURL=dom.d.ts.map

package/dist/src/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/dom.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAER,UAAU,EACV,SAAS,EAEZ,MAAM,YAAY,CAAA;AAEnB;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAC;IAAE,QAAQ,CAAC,OAAO,EAAC,UAAU,GAAC,IAAI,CAAA;CAAE,CAAA;AAEvE,eAAO,MAAM,QAAQ,2BAA2B,CAAA;AAEhD;;;GAGG;AACH,wBAAgB,MAAM,CAClB,MAAM,EAAC,SAAS,EAChB,OAAO,GAAC,QAAQ,CAAC,UAAU,CAAM,GACnC,SAAS,CAGV;AAED;;GAEG;AACH,wBAAgB,WAAW,CACvB,QAAQ,EAAC,aAAa,CAAC,OAAO,CAAC,EAC/B,OAAO,GAAC,QAAQ,CAAC,UAAU,CAAM,GACnC,SAAS,CAyCV;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAE,EAAE,EAAC,OAAO,GAAE,MAAM,CAE/C"}

package/dist/src/index.d.ts

@@ -1,11 +1,18 @@
 import Remarkable from 'remarkable';
 import { generatePlugin, generateToc, getHighest, getTitle, linkify as linkifyHeading, renderBullets, slugify as slugifyHeading, strip as stripHeading, titleize as titleizeHeading } from './markdown-toc.js';
 import { insertMarkdown } from './insert-markdown.js';
+import { type TocTarget } from './dom.js';
 import type { TocOptions, TocResult, TocUtils } from './types.js';
 export type * from './types.js';
+export type { TocTarget };
 export { Remarkable };
 export { generatePlugin as plugin, generateToc, getHighest, getTitle, insertMarkdown, linkifyHeading as linkify, renderBullets, slugifyHeading as slugify, stripHeading as strip, titleizeHeading as titleize, };
 export { renderBullets as bullets };
+/**
+ * Create a table of contents from a markdown string, or, in a browser,
+ * from the headings inside an element (or a ref to an element).
+ */
 export declare function toc(markdown: string, options?: Readonly<TocOptions>): TocResult;
+export declare function toc(target: TocTarget, options?: Readonly<TocOptions>): TocResult;
 export declare const utils: TocUtils;
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,YAAY,CAAA;AACnC,OAAO,EACH,cAAc,EACd,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,IAAI,cAAc,EACzB,aAAa,EACb,OAAO,IAAI,cAAc,EACzB,KAAK,IAAI,YAAY,EACrB,QAAQ,IAAI,eAAe,EAC9B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAEjE,mBAAmB,YAAY,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,OAAO,EACH,cAAc,IAAI,MAAM,EACxB,WAAW,EACX,UAAU,EACV,QAAQ,EACR,cAAc,EACd,cAAc,IAAI,OAAO,EACzB,aAAa,EACb,cAAc,IAAI,OAAO,EACzB,YAAY,IAAI,KAAK,EACrB,eAAe,IAAI,QAAQ,GAC9B,CAAA;AACD,OAAO,EAAE,aAAa,IAAI,OAAO,EAAE,CAAA;AAEnC,wBAAgB,GAAG,CACf,QAAQ,EAAC,MAAM,EACf,OAAO,GAAC,QAAQ,CAAC,UAAU,CAAM,GACnC,SAAS,CAEV;AAED,eAAO,MAAM,KAAK,EAAC,QAMlB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,YAAY,CAAA;AACnC,OAAO,EACH,cAAc,EACd,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,IAAI,cAAc,EACzB,aAAa,EACb,OAAO,IAAI,cAAc,EACzB,KAAK,IAAI,YAAY,EACrB,QAAQ,IAAI,eAAe,EAC9B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAU,KAAK,SAAS,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAEjE,mBAAmB,YAAY,CAAA;AAC/B,YAAY,EAAE,SAAS,EAAE,CAAA;AACzB,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,OAAO,EACH,cAAc,IAAI,MAAM,EACxB,WAAW,EACX,UAAU,EACV,QAAQ,EACR,cAAc,EACd,cAAc,IAAI,OAAO,EACzB,aAAa,EACb,cAAc,IAAI,OAAO,EACzB,YAAY,IAAI,KAAK,EACrB,eAAe,IAAI,QAAQ,GAC9B,CAAA;AACD,OAAO,EAAE,aAAa,IAAI,OAAO,EAAE,CAAA;AAEnC;;;GAGG;AACH,wBAAgB,GAAG,CACf,QAAQ,EAAC,MAAM,EACf,OAAO,CAAC,EAAC,QAAQ,CAAC,UAAU,CAAC,GAC/B,SAAS,CAAA;AACX,wBAAgB,GAAG,CACf,MAAM,EAAC,SAAS,EAChB,OAAO,CAAC,EAAC,QAAQ,CAAC,UAAU,CAAC,GAC/B,SAAS,CAAA;AAUX,eAAO,MAAM,KAAK,EAAC,QAMlB,CAAA"}

package/dist/src/preact.d.ts

@@ -0,0 +1,12 @@
+import { type FunctionComponent } from 'preact';
+import type { TocOptions } from './types.js';
+export type TocProps = TocOptions & {
+    class?: string;
+};
+/**
+ * Render a nested list of links to the headings that come after this
+ * component in the document. Headings without an `id` get one. The list
+ * updates when the document changes.
+ */
+export declare const TOC: FunctionComponent<TocProps>;
+//# sourceMappingURL=preact.d.ts.map

package/dist/src/preact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preact.d.ts","sourceRoot":"","sources":["../../src/preact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAK,KAAK,iBAAiB,EAAc,MAAM,QAAQ,CAAA;AAI9D,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,YAAY,CAAA;AAExD,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAC;IAC9B,KAAK,CAAC,EAAC,MAAM,CAAC;CACjB,CAAA;AAOD;;;;GAIG;AACH,eAAO,MAAM,GAAG,EAAC,iBAAiB,CAAC,QAAQ,CA2C1C,CAAA"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@substrate-system/markdown-toc",
   "description": "Generate a markdown TOC (table of contents) with Remarkable.",
-  "version": "1.3.8",
+  "version": "1.4.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,8 +20,10 @@
   },
   "scripts": {
     "lint": "eslint \"./**/*.{ts,js}\"",
-    "test": "esbuild test/index.ts --platform=node --format=esm --keep-names --bundle --external:gray-matter --external:remarkable --external:diacritics-map | node --input-type=module | tap-spec",
-    "build-esm": "esbuild src/index.ts src/cli.ts src/markdown-toc.ts src/insert-markdown.ts --format=esm --metafile=dist/meta.json --keep-names --tsconfig=tsconfig.build.json --outdir=./dist --sourcemap && tsc --emitDeclarationOnly --project tsconfig.build.json --outDir dist",
+    "test": "npm run test:node && npm run test:browser",
+    "test:node": "esbuild test/index.ts --platform=node --format=esm --keep-names --bundle --external:gray-matter --external:remarkable --external:diacritics-map | node --input-type=module | tap-spec",
+    "test:browser": "esbuild test/browser.ts --bundle --keep-names | tapout | tap-spec",
+    "build-esm": "esbuild src/index.ts src/cli.ts src/markdown-toc.ts src/insert-markdown.ts src/dom.ts src/preact.ts --format=esm --metafile=dist/meta.json --keep-names --tsconfig=tsconfig.build.json --outdir=./dist --sourcemap && tsc --emitDeclarationOnly --project tsconfig.build.json --outDir dist",
     "build": "mkdir -p ./dist && rm -rf ./dist/* && npm run build-esm",
     "preversion": "npm run lint",
     "version": "auto-changelog -p --template keepachangelog --breaking-pattern 'BREAKING CHANGE:' && git add CHANGELOG.md README.md",
@@ -34,13 +36,25 @@
     "gray-matter": "^4.0.3",
     "remarkable": "^1.7.1"
   },
+  "peerDependencies": {
+    "preact": "^10.0.0 || ^11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "preact": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@substrate-system/redeye": "^0.1.7",
+    "@substrate-system/tapout": "^0.1.1",
     "@substrate-system/tapzero": "^0.10.16",
     "@types/node": "^24.0.3",
     "auto-changelog": "^2.6.1",
     "esbuild": "^0.28.2",
     "eslint": "^10.10.0",
+    "htm": "^3.1.1",
     "newneostandard": "^0.14.3",
+    "preact": "^11.2.0",
     "tap-spec": "^5.0.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.70.0"
@@ -50,5 +64,8 @@
   "repository": "substrate-system/markdown-toc",
   "engines": {
     "node": ">=18"
+  },
+  "allowScripts": {
+    "esbuild": true
   }
 }