perf(explorer): client side explorer (#1810)

* start work on client side explorer

* fix tests

* fmt

* generic test flag

* add prenav hook

* add highlight class

* make flex more consistent, remove transition

* open folders that are prefixes of current path

* make mobile look nice

* more style fixes

quartz/util/clone.ts

@@ -0,0 +1,3 @@
+import rfdc from "rfdc"
+
+export const clone = rfdc()

quartz/util/fileTrie.test.ts

@@ -0,0 +1,190 @@
+import test, { describe, beforeEach } from "node:test"
+import assert from "node:assert"
+import { FileTrieNode } from "./fileTrie"
+
+interface TestData {
+  title: string
+  slug: string
+}
+
+describe("FileTrie", () => {
+  let trie: FileTrieNode<TestData>
+
+  beforeEach(() => {
+    trie = new FileTrieNode<TestData>("")
+  })
+
+  describe("constructor", () => {
+    test("should create an empty trie", () => {
+      assert.deepStrictEqual(trie.children, [])
+      assert.strictEqual(trie.slugSegment, "")
+      assert.strictEqual(trie.displayName, "")
+      assert.strictEqual(trie.data, null)
+      assert.strictEqual(trie.depth, 0)
+    })
+
+    test("should set displayName from data title", () => {
+      const data = {
+        title: "Test Title",
+        slug: "test",
+      }
+
+      trie.add(data)
+      assert.strictEqual(trie.children[0].displayName, "Test Title")
+    })
+  })
+
+  describe("add", () => {
+    test("should add a file at root level", () => {
+      const data = {
+        title: "Test",
+        slug: "test",
+      }
+
+      trie.add(data)
+      assert.strictEqual(trie.children.length, 1)
+      assert.strictEqual(trie.children[0].slugSegment, "test")
+      assert.strictEqual(trie.children[0].data, data)
+    })
+
+    test("should handle index files", () => {
+      const data = {
+        title: "Index",
+        slug: "index",
+      }
+
+      trie.add(data)
+      assert.strictEqual(trie.data, data)
+      assert.strictEqual(trie.children.length, 0)
+    })
+
+    test("should add nested files", () => {
+      const data1 = {
+        title: "Nested",
+        slug: "folder/test",
+      }
+
+      const data2 = {
+        title: "Really nested index",
+        slug: "a/b/c/index",
+      }
+
+      trie.add(data1)
+      trie.add(data2)
+      assert.strictEqual(trie.children.length, 2)
+      assert.strictEqual(trie.children[0].slugSegment, "folder")
+      assert.strictEqual(trie.children[0].children.length, 1)
+      assert.strictEqual(trie.children[0].children[0].slugSegment, "test")
+      assert.strictEqual(trie.children[0].children[0].data, data1)
+
+      assert.strictEqual(trie.children[1].slugSegment, "a")
+      assert.strictEqual(trie.children[1].children.length, 1)
+      assert.strictEqual(trie.children[1].data, null)
+
+      assert.strictEqual(trie.children[1].children[0].slugSegment, "b")
+      assert.strictEqual(trie.children[1].children[0].children.length, 1)
+      assert.strictEqual(trie.children[1].children[0].data, null)
+
+      assert.strictEqual(trie.children[1].children[0].children[0].slugSegment, "c")
+      assert.strictEqual(trie.children[1].children[0].children[0].data, data2)
+      assert.strictEqual(trie.children[1].children[0].children[0].children.length, 0)
+    })
+  })
+
+  describe("filter", () => {
+    test("should filter nodes based on condition", () => {
+      const data1 = { title: "Test1", slug: "test1" }
+      const data2 = { title: "Test2", slug: "test2" }
+
+      trie.add(data1)
+      trie.add(data2)
+
+      trie.filter((node) => node.slugSegment !== "test1")
+      assert.strictEqual(trie.children.length, 1)
+      assert.strictEqual(trie.children[0].slugSegment, "test2")
+    })
+  })
+
+  describe("map", () => {
+    test("should apply function to all nodes", () => {
+      const data1 = { title: "Test1", slug: "test1" }
+      const data2 = { title: "Test2", slug: "test2" }
+
+      trie.add(data1)
+      trie.add(data2)
+
+      trie.map((node) => {
+        if (node.data) {
+          node.displayName = "Modified"
+        }
+      })
+
+      assert.strictEqual(trie.children[0].displayName, "Modified")
+      assert.strictEqual(trie.children[1].displayName, "Modified")
+    })
+  })
+
+  describe("entries", () => {
+    test("should return all entries", () => {
+      const data1 = { title: "Test1", slug: "test1" }
+      const data2 = { title: "Test2", slug: "a/b/test2" }
+
+      trie.add(data1)
+      trie.add(data2)
+
+      const entries = trie.entries()
+      assert.deepStrictEqual(
+        entries.map(([path, node]) => [path, node.data]),
+        [
+          ["", trie.data],
+          ["test1", data1],
+          ["a/index", null],
+          ["a/b/index", null],
+          ["a/b/test2", data2],
+        ],
+      )
+    })
+  })
+
+  describe("getFolderPaths", () => {
+    test("should return all folder paths", () => {
+      const data1 = {
+        title: "Root",
+        slug: "index",
+      }
+      const data2 = {
+        title: "Test",
+        slug: "folder/subfolder/test",
+      }
+      const data3 = {
+        title: "Folder Index",
+        slug: "abc/index",
+      }
+
+      trie.add(data1)
+      trie.add(data2)
+      trie.add(data3)
+      const paths = trie.getFolderPaths()
+
+      assert.deepStrictEqual(paths, ["folder/index", "folder/subfolder/index", "abc/index"])
+    })
+  })
+
+  describe("sort", () => {
+    test("should sort nodes according to sort function", () => {
+      const data1 = { title: "A", slug: "a" }
+      const data2 = { title: "B", slug: "b" }
+      const data3 = { title: "C", slug: "c" }
+
+      trie.add(data3)
+      trie.add(data1)
+      trie.add(data2)
+
+      trie.sort((a, b) => a.slugSegment.localeCompare(b.slugSegment))
+      assert.deepStrictEqual(
+        trie.children.map((n) => n.slugSegment),
+        ["a", "b", "c"],
+      )
+    })
+  })
+})

quartz/util/fileTrie.ts

@@ -0,0 +1,128 @@
+import { ContentDetails } from "../plugins/emitters/contentIndex"
+import { FullSlug, joinSegments } from "./path"
+
+interface FileTrieData {
+  slug: string
+  title: string
+}
+
+export class FileTrieNode<T extends FileTrieData = ContentDetails> {
+  children: Array<FileTrieNode<T>>
+  slugSegment: string
+  displayName: string
+  data: T | null
+  depth: number
+  isFolder: boolean
+
+  constructor(segment: string, data?: T, depth: number = 0) {
+    this.children = []
+    this.slugSegment = segment
+    this.displayName = data?.title ?? segment
+    this.data = data ?? null
+    this.depth = depth
+    this.isFolder = segment === "index"
+  }
+
+  private insert(path: string[], file: T) {
+    if (path.length === 0) return
+
+    const nextSegment = path[0]
+
+    // base case, insert here
+    if (path.length === 1) {
+      if (nextSegment === "index") {
+        // index case (we are the root and we just found index.md)
+        this.data ??= file
+        const title = file.title
+        if (title !== "index") {
+          this.displayName = title
+        }
+      } else {
+        // direct child
+        this.children.push(new FileTrieNode(nextSegment, file, this.depth + 1))
+        this.isFolder = true
+      }
+
+      return
+    }
+
+    // find the right child to insert into, creating it if it doesn't exist
+    path = path.splice(1)
+    let child = this.children.find((c) => c.slugSegment === nextSegment)
+    if (!child) {
+      child = new FileTrieNode<T>(nextSegment, undefined, this.depth + 1)
+      this.children.push(child)
+      child.isFolder = true
+    }
+
+    child.insert(path, file)
+  }
+
+  // Add new file to trie
+  add(file: T) {
+    this.insert(file.slug.split("/"), file)
+  }
+
+  /**
+   * Filter trie nodes. Behaves similar to `Array.prototype.filter()`, but modifies tree in place
+   */
+  filter(filterFn: (node: FileTrieNode<T>) => boolean) {
+    this.children = this.children.filter(filterFn)
+    this.children.forEach((child) => child.filter(filterFn))
+  }
+
+  /**
+   * Map over trie nodes. Behaves similar to `Array.prototype.map()`, but modifies tree in place
+   */
+  map(mapFn: (node: FileTrieNode<T>) => void) {
+    mapFn(this)
+    this.children.forEach((child) => child.map(mapFn))
+  }
+
+  /**
+   * Sort trie nodes according to sort/compare function
+   */
+  sort(sortFn: (a: FileTrieNode<T>, b: FileTrieNode<T>) => number) {
+    this.children = this.children.sort(sortFn)
+    this.children.forEach((e) => e.sort(sortFn))
+  }
+
+  static fromEntries<T extends FileTrieData>(entries: [FullSlug, T][]) {
+    const trie = new FileTrieNode<T>("")
+    entries.forEach(([, entry]) => trie.add(entry))
+    return trie
+  }
+
+  /**
+   * Get all entries in the trie
+   * in the a flat array including the full path and the node
+   */
+  entries(): [FullSlug, FileTrieNode<T>][] {
+    const traverse = (
+      node: FileTrieNode<T>,
+      currentPath: string,
+    ): [FullSlug, FileTrieNode<T>][] => {
+      const segments = [currentPath, node.slugSegment]
+      const fullPath = joinSegments(...segments) as FullSlug
+
+      const indexQualifiedPath =
+        node.isFolder && node.depth > 0 ? (joinSegments(fullPath, "index") as FullSlug) : fullPath
+
+      const result: [FullSlug, FileTrieNode<T>][] = [[indexQualifiedPath, node]]
+
+      return result.concat(...node.children.map((child) => traverse(child, fullPath)))
+    }
+
+    return traverse(this, "")
+  }
+
+  /**
+   * Get all folder paths in the trie
+   * @returns array containing folder state for trie
+   */
+  getFolderPaths() {
+    return this.entries()
+      .filter(([_, node]) => node.isFolder)
+      .map(([path, _]) => path)
+  }
+}

quartz/util/path.ts

@@ -1,9 +1,6 @@
 import { slug as slugAnchor } from "github-slugger"
 import type { Element as HastElement } from "hast"
-import rfdc from "rfdc"
-
-export const clone = rfdc()
-
+import { clone } from "./clone"
 // this file must be isomorphic so it can't use node libs (e.g. path)
 
 export const QUARTZ = "quartz"