File Tree Diff: initial implementation (#424)

Added a new addon to show all the filenames and URLs that were added,
deleted or modified in the current PR compared to the LATEST version.


![Screenshot_2024-11-07_12-44-02](https://github.com/user-attachments/assets/dfdba906-1eb1-4755-a1e6-eaddbfa51144)

I'm rendering this data in a new notification decoupled from the
existing one on purpose. I don't want to entangle the code of these two
different addons for now, in particular while we are under
development/testing. I also see that in the future they may have
different UI elements, or the data will be integrated in a more bigger
UI element (eg. toolbar) or similar.

We can discuss more how this addon will grow and where is a good place
to add this data and make that work in a following PR. For now, I want
something that we can start testing internally in our own projects.

### Examples


![Screenshot_2024-11-07_14-15-37](https://github.com/user-attachments/assets/d0265b34-8ade-4348-bc8e-e6a3ff8ae0d1)



![Screenshot_2024-11-07_14-35-41](https://github.com/user-attachments/assets/403b6860-60c1-468e-ae5d-2491f6f47b38)



![Screenshot_2024-11-07_14-51-06](https://github.com/user-attachments/assets/0e24664d-672f-40c0-9be4-bd76b2cf4f04)


Closes #409
Requires readthedocs/readthedocs.org#11749

Author: humitos

dist/readthedocs-addons.js

@@ -239,6 +239,36 @@ const addons_flyout = {
   },
 };
 
+// Validator for File Tree Diff Addon
+const addons_filetreediff = {
+  $id: "http://v1.schemas.readthedocs.org/addons.filetreediff.json",
+  type: "object",
+  required: ["addons"],
+  properties: {
+    addons: {
+      type: "object",
+      required: ["filetreediff"],
+      properties: {
+        filetreediff: {
+          type: "object",
+          required: ["enabled", "diff"],
+          properties: {
+            enabled: { type: "boolean" },
+            diff: {
+              type: "object",
+              properties: {
+                added: { type: "array" },
+                deleted: { type: "array" },
+                modified: { type: "array" },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
 // Validator for Hotkeys Addon
 const addons_hotkeys = {
   $id: "http://v1.schemas.readthedocs.org/addons.hotkeys.json",
@@ -443,6 +473,7 @@ export const ajv = new Ajv({
     addons_hotkeys,
     addons_notifications,
     addons_search,
+    addons_filetreediff,
   ],
 });
 

dist/readthedocs-addons.js.map

@@ -0,0 +1,86 @@
+:host > div {
+  margin: 1rem 0rem;
+  padding-top: 1rem;
+  padding-bottom: 1rem;
+  overflow: auto;
+  border-radius: 0.5rem;
+  font-family: "Lato", "proxima-nova", "Helvetica Neue", "Arial", "sans-serif";
+  font-size: 1rem;
+  color: rgb(64, 64, 64);
+  background-color: rgb(234, 234, 234);
+}
+
+:host > div > div.content > ul {
+  margin: 0;
+  padding-left: 20px;
+}
+
+:host(.toast) > div {
+  position: fixed;
+  padding-top: calc(1rem * 0.75);
+  padding-bottom: calc(1rem * 0.75);
+  margin: 0.75rem 0rem;
+  top: 7rem;
+  right: 2rem;
+  z-index: 1750;
+  font-size: calc(1rem * 0.85);
+  width: 35rem;
+  max-width: calc(100vw - 4rem);
+}
+
+@media (max-width: 640px) {
+  :host(.toast) > div {
+    right: 0.5rem;
+  }
+}
+
+:host > div > svg.header.icon {
+  height: calc(1rem * 2);
+  padding: 0.5rem 1.5rem;
+  float: left;
+}
+
+:host(.toast) > div > svg.header.icon {
+  height: calc(1rem * 1.5);
+}
+
+:host > div a {
+  color: rgb(8, 140, 219);
+  text-decoration: none;
+}
+
+:host > div > .title {
+  padding: 0.25rem 1rem;
+  margin-bottom: 0.25rem;
+  line-height: 1rem;
+  font-weight: bold;
+  font-size: 0.85rem;
+}
+:host > div > div.content {
+  line-height: 1rem;
+  font-size: calc(1rem * 0.85);
+  padding-left: 66px;
+}
+
+:host(.toast) > div > .title {
+  padding: 0rem 1rem;
+}
+
+:host > div > .title > .right {
+  float: right;
+}
+
+:host > div > .title > .right > svg {
+  display: inline-block;
+  height: 1rem;
+  vertical-align: middle;
+  cursor: pointer;
+  color: rgba(96, 96, 96);
+  font-weight: normal;
+}
+
+:host(.raised) > div {
+  box-shadow:
+    0 2px 4px 0 rgba(34, 36, 38, 0.12),
+    0 2px 10px 0 rgba(34, 36, 38, 0.15);
+}

src/data-validation.js

@@ -0,0 +1,181 @@
+import { library, icon } from "@fortawesome/fontawesome-svg-core";
+import { faCircleXmark, faFile } from "@fortawesome/free-solid-svg-icons";
+import { html, nothing, render, LitElement } from "lit";
+import { repeat } from "lit/directives/repeat.js";
+import { default as objectPath } from "object-path";
+import styleSheet from "./filetreediff.css";
+
+import { AddonBase } from "./utils";
+
+export class FileTreeDiffElement extends LitElement {
+  static elementName = "readthedocs-filetreediff";
+
+  static properties = {
+    config: { state: true },
+    dismissed: { state: true },
+  };
+
+  static styles = styleSheet;
+
+  constructor() {
+    super();
+    this.config = null;
+    this.dismissed = false;
+  }
+
+  firstUpdated() {
+    // Add CSS classes to the element on ``firstUpdated`` because we need the
+    // HTML element to exist in the DOM before being able to add tag attributes.
+    this.className = this.className || "raised toast";
+  }
+
+  loadConfig(config) {
+    if (!FileTreeDiffAddon.isEnabled(config)) {
+      return;
+    }
+
+    this.config = config;
+  }
+
+  render() {
+    if (this.dismissed) {
+      return nothing;
+    }
+
+    library.add(faFile);
+    const iconFile = icon(faFile, {
+      title: "This version is a pull request version",
+      classes: ["header", "icon"],
+    });
+
+    const diffdata = objectPath.get(this.config, "addons.filetreediff.diff");
+
+    let diffAddedUrls = diffdata.added.length
+      ? html`
+          <span>Added</span>
+          <ul>
+            ${repeat(
+              diffdata.added,
+              (f) => f.filename,
+              (f, index) =>
+                html`<li><a href=${f.urls.version_a}>${f.filename}</a></li>`,
+            )}
+          </ul>
+        `
+      : nothing;
+
+    let diffDeletedUrls = diffdata.deleted.length
+      ? html`
+          <span>Deleted</span>
+          <ul>
+            ${repeat(
+              diffdata.deleted,
+              (f) => f.filename,
+              (f, index) =>
+                html`<li><a href=${f.urls.version_a}>${f.filename}</a></li>`,
+            )}
+          </ul>
+        `
+      : nothing;
+
+    let diffModifiedUrls = diffdata.modified.length
+      ? html`
+          <span>Modified</span>
+          <ul>
+            ${repeat(
+              diffdata.modified,
+              (f) => f.filename,
+              (f, index) =>
+                html`<li><a href=${f.urls.version_a}>${f.filename}</a></li>`,
+            )}
+          </ul>
+        `
+      : nothing;
+
+    return html`
+      <div>
+        ${iconFile.node[0]}
+        <div class="title">
+          List of files changed in this pull request ${this.renderCloseButton()}
+        </div>
+        <div class="content">
+          ${diffAddedUrls} ${diffModifiedUrls} ${diffDeletedUrls}
+        </div>
+      </div>
+    `;
+  }
+
+  renderCloseButton() {
+    library.add(faCircleXmark);
+    const xmark = icon(faCircleXmark, {
+      title: "Close notification",
+    });
+    return html`
+      <a href="#" class="right" @click=${this.closeNotification}>
+        ${xmark.node[0]}
+      </a>
+    `;
+  }
+
+  closeNotification(e) {
+    // Avoid going back to the top of the page when closing the notification
+    e.preventDefault();
+    this.dismissed = true;
+
+    // Avoid event propagation
+    return false;
+  }
+}
+
+/**
+ * File Tree Diff addon
+ *
+ * UNDER DEVELOPMENT.
+ *
+ * Currently, this addon shows in the console all the file changed compared to
+ * the LATEST version of the project.
+ *
+ * @param {Object} config - Addon configuration object
+ */
+export class FileTreeDiffAddon extends AddonBase {
+  static jsonValidationURI =
+    "http://v1.schemas.readthedocs.org/addons.filetreediff.json";
+  static addonEnabledPath = "addons.filetreediff.enabled";
+  static addonName = "File Tree Diff";
+
+  constructor(config) {
+    super();
+
+    this.config = config;
+    this.showDiff();
+
+    // If there are no elements found, inject one
+    let elems = document.querySelectorAll("readthedocs-filetreediff");
+    if (!elems.length) {
+      elems = [new FileTreeDiffElement()];
+      document.body.append(elems[0]);
+      elems[0].requestUpdate();
+    }
+
+    for (const elem of elems) {
+      elem.loadConfig(config);
+    }
+  }
+
+  showDiff() {
+    // const outdated = objectPath.get(this.config, "addons.filetreediff.oudated", false);
+    const diffData = objectPath.get(this.config, "addons.filetreediff.diff");
+
+    for (let f of diffData.added) {
+      console.debug(`File: ${f.filename}, URL: ${f.urls.version_a}`);
+    }
+    for (let f of diffData.modified) {
+      console.debug(`File: ${f.filename}, URL: ${f.urls.version_a}`);
+    }
+    for (let f of diffData.deleted) {
+      console.debug(`File: ${f.filename}, URL: ${f.urls.version_a}`);
+    }
+  }
+}
+
+customElements.define("readthedocs-filetreediff", FileTreeDiffElement);

src/filetreediff.css

@@ -6,6 +6,7 @@ import * as docdiff from "./docdiff";
 import * as flyout from "./flyout";
 import * as ethicalads from "./ethicalads";
 import * as hotkeys from "./hotkeys";
+import * as filetreediff from "./filetreediff";
 import {
   domReady,
   isReadTheDocsEmbedPresent,
@@ -29,6 +30,7 @@ export function setup() {
     search.SearchAddon,
     docdiff.DocDiffAddon,
     hotkeys.HotKeysAddon,
+    filetreediff.FileTreeDiffAddon,
   ];
 
   return new Promise((resolve) => {

src/filetreediff.js

@@ -0,0 +1,51 @@
+import { expect, assert, fixture, html } from "@open-wc/testing";
+import { FileTreeDiffAddon } from "../src/filetreediff";
+
+describe("FileTreeDiff addon", () => {
+  it("invalid configuration disables the addon", () => {
+    expect(
+      FileTreeDiffAddon.isEnabled({
+        addons: {
+          filetreediff: {
+            enabled: true,
+            diff: 52, // invalid value
+          },
+        },
+      }),
+    ).to.be.false;
+  });
+
+  it("is disabled", () => {
+    expect(
+      FileTreeDiffAddon.isEnabled({
+        addons: {
+          filetreediff: {
+            enabled: false,
+            diff: {
+              added: [],
+              modified: [],
+              deleted: [],
+            },
+          },
+        },
+      }),
+    ).to.be.false;
+  });
+
+  it("valid data and enabled", () => {
+    expect(
+      FileTreeDiffAddon.isEnabled({
+        addons: {
+          filetreediff: {
+            enabled: true,
+            diff: {
+              added: [],
+              modified: [],
+              deleted: [],
+            },
+          },
+        },
+      }),
+    ).to.be.true;
+  });
+});