rehype-toc - npm Package Compare versions

Comparing version 2.1.0 to 2.2.0

CHANGELOG.md

@@ -6,2 +6,9 @@ # Change Log
 
+## [v2.2.0](https://github.com/JS-DevTools/rehype-toc/tree/v2.2.0) (2019-07-31)
+
+- Added a new `customizeTOCItem` option that allows you to customize each item in the table-of-contents before it's added to the page
+
+[Full Changelog](https://github.com/JS-DevTools/rehype-toc/compare/v2.1.0...v2.2.0)
+
+
 ## [v2.1.0](https://github.com/JS-DevTools/rehype-toc/tree/v2.1.0) (2019-07-11)
@@ -8,0 +15,0 @@

lib/create-toc.d.ts

@@ -1,2 +0,2 @@
-import { Options } from "./options";
+import { NormalizedOptions } from "./options";
 import { HeadingNode, HtmlElementNode } from "./types";
@@ -6,2 +6,2 @@ /**
  */
-export declare function createTOC(headings: HeadingNode[], options: Options): HtmlElementNode;
+export declare function createTOC(headings: HeadingNode[], options: NormalizedOptions): HtmlElementNode;

lib/create-toc.js

@@ -15,3 +15,3 @@ "use strict";
             properties: {
-                class: options.cssClasses.toc || undefined,
+                className: options.cssClasses.toc || undefined,
             },
@@ -22,3 +22,4 @@ children: [list],
     else {
-        list.properties.class = [options.cssClasses.toc, list.properties.class].filter(Boolean).join(" ") || undefined;
+        list.properties.className =
+            [options.cssClasses.toc, list.properties.className].filter(Boolean).join(" ") || undefined;
         return list;
@@ -92,3 +93,3 @@ }
         properties: {
-            class: options_1.buildClass(options.cssClasses.list, depth),
+            className: options_1.buildClass(options.cssClasses.list, depth),
         },
@@ -110,4 +111,7 @@ children: [],
         tagName: "li",
+        data: {
+            hookArgs: [heading],
+        },
         properties: {
-            class: options_1.buildClass(options.cssClasses.listItem, heading.tagName),
+            className: options_1.buildClass(options.cssClasses.listItem, heading.tagName),
         },
@@ -119,3 +123,3 @@ children: [
                 properties: {
-                    class: options_1.buildClass(options.cssClasses.link, heading.tagName),
+                    className: options_1.buildClass(options.cssClasses.link, heading.tagName),
                     href: `#${heading.properties.id || ""}`,
@@ -122,0 +126,0 @@ },

lib/fiind-headings.d.ts

 import { Node } from "unist";
-import { Options } from "./options";
+import { NormalizedOptions } from "./options";
 import { HeadingNode } from "./types";
@@ -7,2 +7,2 @@ /**
  */
-export declare function findHeadings(node: Node, options: Options): HeadingNode[];
+export declare function findHeadings(node: Node, options: NormalizedOptions): HeadingNode[];

lib/index.d.ts

 import { toc } from "./rehype-toc";
-export { InsertPosition, Options, PartialOptions } from "./options";
+export { CssClasses, InsertPosition, Options } from "./options";
 export * from "./types";
 export { toc };
 export default toc;

lib/insert-toc.d.ts

 import { Node } from "unist";
-import { Options } from "./options";
+import { NormalizedOptions } from "./options";
 import { HtmlElementNode } from "./types";
@@ -12,2 +12,2 @@ /**
  */
-export declare function insertTOC(toc: Node, target: HtmlElementNode, parent: HtmlElementNode, { position }: Options): void;
+export declare function insertTOC(toc: Node, target: HtmlElementNode, parent: HtmlElementNode, { position }: NormalizedOptions): void;

lib/options.d.ts

 import { Node } from "unist";
-import { HeadingTagName, HtmlElementNode } from "./types";
+import { CustomizationHook } from "./customization-hooks";
+import { HeadingTagName, HtmlElementNode, ListItemNode } from "./types";
 /**
@@ -17,3 +18,3 @@ * The different positions at which the table of contents can be inserted,
      */
-    nav: boolean;
+    nav?: boolean;
     /**
@@ -27,3 +28,3 @@ * The position at which the table of contents should be inserted, relative to the `<main>`
      */
-    position: InsertPosition;
+    position?: InsertPosition;
     /**
@@ -34,32 +35,7 @@ * HTML heading elements to include in the table of contents.
      */
-    headings: HeadingTagName[];
+    headings?: HeadingTagName[];
     /**
      * CSS class names for various parts of the table of contents.
      */
-    cssClasses: {
-        /**
-         * The CSS class name for the top-level `<nav>` or `<ol>` element that contains the whole table of contents.
-         *
-         * Defaults to "toc".
-         */
-        toc: string;
-        /**
-         * The CSS class name for all `<ol>` elements in the table of contents, including the top-level one.
-         *
-         * Defaults to "toc-level", which also adds "toc-level-1", "toc-level-2", etc.
-         */
-        list: string;
-        /**
-         * The CSS class name for all `<li>` elements in the table of contents.
-         *
-         * Defaults to "toc-item", which also adds "toc-item-h1", "toc-item-h2", etc.
-         */
-        listItem: string;
-        /**
-         * The CSS class name for all `<a>` elements in the table of contents.
-         *
-         * Defaults to "toc-link", which also adds "toc-link-h1", "toc-link-h2", etc.
-         */
-        link: string;
-    };
+    cssClasses?: CssClasses;
     /**
@@ -73,21 +49,63 @@ * Allows you to customize the table of contents before it is added to the page.
      */
-    customizeTOC(toc: HtmlElementNode): Node | undefined | false;
+    customizeTOC?(toc: HtmlElementNode): Node | boolean | undefined;
+    /**
+     * Allows you to customize an item before it is added to the table of contents.
+     *
+     * @param tocItem - A HAST node tree containing an `<li>` and `<a>`
+     * @param heading - The original heading (e.g. `<h1>`, `<h2>`, etc.) that `tocItem` is a referene to
+     *
+     * @returns - Return the modified node, a new node to replace it with, or `undefined` to use the
+     * existing node. You can return a falsy value to prevent the item from being added to the
+     * table of contents.
+     */
+    customizeTOCItem?(tocItem: ListItemNode, heading: HtmlElementNode): Node | boolean | undefined;
 }
 /**
- * Options for the Rehype TOC plugin. All fields are optional.
+ * CSS class names for various parts of the table of contents.
  */
-export declare type PartialOptions = DeepPartial<Options>;
+export interface CssClasses {
+    /**
+     * The CSS class name for the top-level `<nav>` or `<ol>` element that contains the whole table of contents.
+     *
+     * Defaults to "toc".
+     */
+    toc?: string;
+    /**
+     * The CSS class name for all `<ol>` elements in the table of contents, including the top-level one.
+     *
+     * Defaults to "toc-level", which also adds "toc-level-1", "toc-level-2", etc.
+     */
+    list?: string;
+    /**
+     * The CSS class name for all `<li>` elements in the table of contents.
+     *
+     * Defaults to "toc-item", which also adds "toc-item-h1", "toc-item-h2", etc.
+     */
+    listItem?: string;
+    /**
+     * The CSS class name for all `<a>` elements in the table of contents.
+     *
+     * Defaults to "toc-link", which also adds "toc-link-h1", "toc-link-h2", etc.
+     */
+    link?: string;
+}
 /**
- * Recursively makes all object properties optional
+ * Normalized, sanitized, and complete settings,
+ * with default values for anything that wasn't specified by the caller.
  */
-export declare type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends string | number | boolean | Function | any[] ? T[P] : DeepPartial<T[P]>;
-};
+export declare class NormalizedOptions {
+    readonly nav: boolean;
+    readonly position: InsertPosition;
+    readonly headings: HeadingTagName[];
+    readonly cssClasses: Required<CssClasses>;
+    readonly customizeTOC?: CustomizationHook;
+    readonly customizeTOCItem?: CustomizationHook;
+    /**
+     * Applies default values for any unspecified options
+     */
+    constructor(options?: Options);
+}
 /**
- * Applies default values for any unspecified options
- */
-export declare function applyDefaults(config?: PartialOptions): Options;
-/**
  * Builds a CSS class string from the given user-defined class name
  */
 export declare function buildClass(name: string, suffix: string | number): string | undefined;

lib/options.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
- * Applies default values for any unspecified options
+ * Normalized, sanitized, and complete settings,
+ * with default values for anything that wasn't specified by the caller.
  */
-function applyDefaults(config = {}) {
-    let cssClasses = config.cssClasses || {};
-    return {
-        nav: config.nav === undefined ? true : Boolean(config.nav),
-        position: config.position || "afterbegin",
-        headings: config.headings || ["h1", "h2", "h3", "h4", "h5", "h6"],
-        cssClasses: {
+class NormalizedOptions {
+    /**
+     * Applies default values for any unspecified options
+     */
+    constructor(options = {}) {
+        let cssClasses = options.cssClasses || {};
+        this.nav = options.nav === undefined ? true : Boolean(options.nav);
+        this.position = options.position || "afterbegin";
+        this.headings = options.headings || ["h1", "h2", "h3", "h4", "h5", "h6"];
+        this.cssClasses = {
             toc: cssClasses.toc === undefined ? "toc" : cssClasses.toc,
@@ -17,7 +21,8 @@ list: cssClasses.list === undefined ? "toc-level" : cssClasses.list,
             link: cssClasses.link === undefined ? "toc-link" : cssClasses.link,
-        },
-        customizeTOC: config.customizeTOC || ((toc) => toc),
-    };
+        };
+        this.customizeTOC = options.customizeTOC;
+        this.customizeTOCItem = options.customizeTOCItem;
+    }
 }
-exports.applyDefaults = applyDefaults;
+exports.NormalizedOptions = NormalizedOptions;
 /**
@@ -24,0 +29,0 @@ * Builds a CSS class string from the given user-defined class name

lib/rehype-toc.d.ts

 import { Processor, Transformer } from "unified";
-import { PartialOptions } from "./options";
+import { Options } from "./options";
 /**
@@ -7,2 +7,2 @@ * This is a Rehype plugin that adds a table of contents (TOC) that links to all
  */
-export declare function toc(this: Processor, opts?: PartialOptions): Transformer;
+export declare function toc(this: Processor, opts?: Options): Transformer;

lib/rehype-toc.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const create_toc_1 = require("./create-toc");
-const customize_toc_1 = require("./customize-toc");
+const customization_hooks_1 = require("./customization-hooks");
 const fiind_headings_1 = require("./fiind-headings");
@@ -14,3 +14,3 @@ const find_main_node_1 = require("./find-main-node");
 function toc(opts) {
-    let options = options_1.applyDefaults(opts);
+    let options = new options_1.NormalizedOptions(opts);
     return function transformer(root) {
@@ -24,3 +24,3 @@ // Find the <main> or <body> element
         // Allow the user to customize the table of contents before we add it to the page
-        let node = customize_toc_1.customizeTOC(tocNode, options);
+        let node = customization_hooks_1.customizationHooks(tocNode, options);
         if (node) {
@@ -27,0 +27,0 @@ // Add the table of contents to the <main> element

lib/type-guards.d.ts

 import { Node } from "unist";
-import { Options } from "./options";
+import { NormalizedOptions } from "./options";
 import { HeadingNode, HtmlElementNode } from "./types";
@@ -11,2 +11,2 @@ /**
  */
-export declare function isHeadingNode(node: Node, options: Options): node is HeadingNode;
+export declare function isHeadingNode(node: Node, options: NormalizedOptions): node is HeadingNode;

package.json

 {
   "name": "rehype-toc",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A rehype plugin that adds a table of contents (TOC) to the page",
@@ -49,9 +49,9 @@ "keywords": [
     "@types/mocha": "^5.2.7",
-    "@types/node": "^12.6.2",
+    "@types/node": "^12.6.8",
     "@types/unist": "^2.0.3",
     "chai": "^4.2.0",
-    "coveralls": "^3.0.4",
-    "eslint": "^6.0.1",
+    "coveralls": "^3.0.5",
+    "eslint": "^6.1.0",
     "eslint-config-modular": "^7.0.0",
-    "mocha": "^6.1.4",
+    "mocha": "^6.2.0",
     "npm-check": "^5.9.0",
@@ -67,3 +67,3 @@ "nyc": "^14.1.1",
     "typescript-tslint-plugin": "^0.5.4",
-    "unified": "^8.1.0",
+    "unified": "^8.3.2",
     "version-bump-prompt": "^5.0.4"
@@ -70,0 +70,0 @@ },

README.md

@@ -234,3 +234,4 @@ # Table of Contents plugin for rehype
 |`cssClasses.link`     |string              |toc-link               |The CSS class name for all `<a>` elements in the table of contents.
-|`customizeTOC`        |function            |no-op                  |Allows you to customize the table of contents before it is added to the page.<br><br>The function receives the TOC node tree and can modify it in any way you want. Or you can return a new node tree to use instead. Or return `false` to prevent the the TOC from being added to the page.
+|`customizeTOC`        |function(toc)       |                       |Allows you to customize the table of contents before it is added to the page.<br><br>The function receives the TOC node tree and can modify it in any way you want. Or you can return a new node tree to use instead. Or return `false` to prevent the the TOC from being added to the page.
+|`customizeTOCItem`    |function(toc, heading)|                     |Allows you to customize each item in the table of contents before it is added to the page.<br><br>The function receives the TOC item's node tree and the heading node that it refers to. You can modify the nodes in any way you want. Or you can return a new node tree to use instead. Or return `false` to prevent the the TOC from being added to the page.
 
@@ -237,0 +238,0 @@

No alert changes

Improved metrics

Total package byte prevSize

48316

12.36%

Lines of code

638

14.95%

Number of lines in readme file

273

0.37%

No dependency changes