@m3e/toc 1.0.0-rc.1

package/src/TocGenerator.ts

@@ -0,0 +1,74 @@
+import { getTextContent, guid } from "@m3e/core";
+
+/** A node in a table of contents. */
+export interface TocNode {
+  /** An opaque identifier that uniquely identifies the node. */
+  id: string;
+
+  /** The level of the node. */
+  level: number;
+
+  /** The text to display for the node. */
+  label: string;
+
+  /** The element of the node. */
+  element: HTMLElement;
+
+  /** The child nodes. */
+  nodes: TocNode[];
+}
+
+/** Provides functionality used to generate a table of contents used for in-page navigation. */
+export class TocGenerator {
+  /**
+   * Generates nodes from which to construct a table of contents for in-page navigation.
+   * @param {HTMLElement} element The element for which to generate a table of contents.
+   * @param {number} [maxDepth=6] The maximum depth of the table of contents.
+   * @returns {Array<TocNode>} The top-level nodes of the table of contents.
+   */
+  static generate(element: HTMLElement, maxDepth: number = 6): Array<TocNode> {
+    const maxLevel = 6;
+    let topLevel = maxLevel;
+    const nodes = new Array<TocNode>();
+    element
+      .querySelectorAll<HTMLElement>(
+        "h1:not([m3e-toc-ignore]),h2:not([m3e-toc-ignore]),h3:not([m3e-toc-ignore]),h4:not([m3e-toc-ignore]),h5:not([m3e-toc-ignore]),h6:not([m3e-toc-ignore]),m3e-heading[level]:not([m3e-toc-ignore])"
+      )
+      .forEach((element) => {
+        const level = TocGenerator.#getHeaderLevel(element);
+        topLevel = Math.min(level, topLevel);
+        nodes.push({
+          id: element.id || guid(),
+          element,
+          level,
+          label: getTextContent(element, true),
+          nodes: new Array<TocNode>(),
+        });
+      });
+
+    for (let level = topLevel + maxDepth - 1; level > topLevel; level--) {
+      for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        if (node.level === level) {
+          for (let j = i; j >= 0; j--) {
+            const prev = nodes[j];
+            if (prev.level < level) {
+              prev.nodes.push(node);
+              break;
+            }
+          }
+        }
+      }
+    }
+
+    nodes.forEach((x) => (x.level -= topLevel - 1));
+    return nodes.filter((x) => x.level === 1);
+  }
+
+  /** @internal */
+  static #getHeaderLevel(element: HTMLElement): number {
+    return element.tagName.startsWith("H")
+      ? parseInt(element.tagName.substring(1))
+      : parseInt(element.getAttribute("level") ?? "0");
+  }
+}

package/src/TocItemElement.ts

@@ -0,0 +1,121 @@
+import { css, CSSResultGroup, html, LitElement, PropertyValues, unsafeCSS } from "lit";
+import { customElement, query, state } from "lit/decorators.js";
+
+import { AttachInternals, DesignToken, Disabled, M3eStateLayerElement, Role, Selected } from "@m3e/core";
+
+import { TocNode } from "./TocGenerator";
+
+/**
+ * An item in a table of contents.
+ * @tag m3e-toc-item
+ *
+ * @slot - Renders the label of the item.
+ *
+ * @attr disabled - A value indicating whether the element is disabled.
+ *
+ * @cssprop --m3e-toc-item-shape - Border radius of the TOC item.
+ * @cssprop --m3e-toc-item-padding-block - Block padding for the TOC item.
+ * @cssprop --m3e-toc-item-padding - Inline padding for the TOC item.
+ * @cssprop --m3e-toc-item-inset - Indentation per level for the TOC item.
+ * @cssprop --m3e-toc-active-indicator-animation-duration - Animation duration for the active indicator.
+ * @cssprop --m3e-toc-item-font-size - Font size for unselected items.
+ * @cssprop --m3e-toc-item-font-weight - Font weight for unselected items.
+ * @cssprop --m3e-toc-item-line-height - Line height for unselected items.
+ * @cssprop --m3e-toc-item-tracking - Letter spacing for unselected items.
+ * @cssprop --m3e-toc-item-color - Text color for unselected items.
+ * @cssprop --m3e-toc-item-selected-font-size - Font size for selected items.
+ * @cssprop --m3e-toc-item-selected-font-weight - Font weight for selected items.
+ * @cssprop --m3e-toc-item-selected-line-height - Line height for selected items.
+ * @cssprop --m3e-toc-item-selected-tracking - Letter spacing for selected items.
+ * @cssprop --m3e-toc-item-selected-color - Text color for selected items.
+ */
+@customElement("m3e-toc-item")
+export class M3eTocItemElement extends Selected(Disabled(AttachInternals(Role(LitElement, "link")))) {
+  /** The styles of the element. */
+  static override styles: CSSResultGroup = css`
+    :host {
+      display: inline-block;
+      position: relative;
+      user-select: none;
+      border-radius: var(--m3e-toc-item-shape, ${DesignToken.shape.corner.largeIncreased});
+      padding-block: var(--m3e-toc-item-padding-block, 0.5rem);
+    }
+    :host(:not(:disabled)) {
+      cursor: pointer;
+    }
+    .base {
+      padding-inline-start: calc(
+        var(--m3e-toc-item-padding, 1rem) + calc(var(--m3e-toc-item-inset, 0.75rem) * var(--_level, 0))
+      );
+      padding-inline-end: var(--m3e-toc-item-padding, 1rem);
+      transition: ${unsafeCSS(
+        `color var(--m3e-toc-active-indicator-animation-duration, ${DesignToken.motion.duration.long1}) ${DesignToken.motion.easing.standard}`
+      )};
+    }
+    :host(:not([selected])) {
+      font-size: var(--m3e-toc-item-font-size, ${DesignToken.typescale.standard.body.large.fontSize});
+      font-weight: var(--m3e-toc-item-font-weight, ${DesignToken.typescale.standard.body.large.fontWeight});
+      line-height: var(--m3e-toc-item-line-height, ${DesignToken.typescale.standard.body.large.lineHeight});
+      letter-spacing: var(--m3e-toc-item-tracking, ${DesignToken.typescale.standard.body.large.tracking});
+      color: var(--m3e-toc-item-color, ${DesignToken.color.onSurfaceVariant});
+    }
+    :host([selected]) {
+      font-size: var(--m3e-toc-item-selected-font-size, ${DesignToken.typescale.emphasized.body.large.fontSize});
+      font-weight: var(--m3e-toc-item-selected-font-weight, ${DesignToken.typescale.emphasized.body.large.fontWeight});
+      line-height: var(--m3e-toc-item-selected-line-height, ${DesignToken.typescale.emphasized.body.large.lineHeight});
+      letter-spacing: var(--m3e-toc-item-selected-tracking, ${DesignToken.typescale.emphasized.body.large.tracking});
+      color: var(--m3e-toc-item-selected-color, ${DesignToken.color.onSecondaryContainer});
+    }
+    .base {
+      justify-content: unset;
+    }
+    .state-layer {
+      --m3e-state-layer-focus-opacity: 0;
+    }
+    @media (prefers-reduced-motion) {
+      .base {
+        transition: none;
+      }
+    }
+  `;
+
+  /** @private */ @query(".base") private readonly _base?: HTMLElement;
+  /** @private */ @query(".state-layer") private readonly _stateLayer?: M3eStateLayerElement;
+  /** @internal */ @state() node?: TocNode;
+
+  /** @internal */
+  protected override update(changedProperties: PropertyValues<this>): void {
+    super.update(changedProperties);
+
+    if (changedProperties.has("selected")) {
+      this.ariaSelected = null;
+      this.ariaCurrent = this.selected ? "true" : null;
+    }
+
+    if (changedProperties.has("node")) {
+      if (this.node) {
+        this._base?.style.setProperty("--_level", `${this.node.level - 1}`);
+      } else {
+        this._base?.style.removeProperty("--_level");
+      }
+    }
+  }
+
+  /** @inheritdoc */
+  protected override firstUpdated(_changedProperties: PropertyValues<this>): void {
+    super.firstUpdated(_changedProperties);
+    this._stateLayer?.attach(this);
+  }
+
+  /** @inheritdoc */
+  override render(): unknown {
+    return html`<m3e-state-layer class="state-layer"></m3e-state-layer>
+      <div class="base"><slot></slot></div>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "m3e-toc-item": M3eTocItemElement;
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./TocElement";
+export * from "./TocGenerator";
+export * from "./TocItemElement";

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist/src"
+  },
+  "include": ["src/**/*.ts", "**/*.mjs", "**/*.js"],
+  "exclude": []
+}