feature/Issue-97: Implement the Edit on GitHub component (#111)

Co-authored-by: Owen Buckley <owenbuckley13@gmail.com>

src/components/edit-on-github/edit-on-github.js

@@ -0,0 +1,33 @@
+import styles from "./edit-on-github.module.css";
+
+const REPO_PREFIX = "https://github.com/ProjectEvergreen/www.greenwoodjs.dev/edit/main/src/pages";
+const MAX_ROUTE_DEPTH = 5;
+
+// one / two segments - /guides/ -> /guides/index.md
+// three (max) segments - /guides/getting-started/key-concepts/ -> /guides/getting-started/key-concepts.md
+function convertRouteToEditLink(route) {
+  const segments = route.split("/");
+
+  // https://stackoverflow.com/a/5497365/417806
+  return segments.length === MAX_ROUTE_DEPTH
+    ? `${route.replace(/\/([^/]*)$/, "")}.md`
+    : `${route}index.md`;
+}
+
+export default class EditOnGitHub extends HTMLElement {
+  connectedCallback() {
+    const label = "Edit on GitHub";
+    const route = this.getAttribute("route");
+    const href = `${REPO_PREFIX}${convertRouteToEditLink(route)}`;
+
+    this.innerHTML = `
+      <div class="${styles.container}">
+        <a title="${label}" href="${href}" target="_blank">
+          ${label}
+        </a>
+      </div>
+    `;
+  }
+}
+
+customElements.define("app-edit-on-github", EditOnGitHub);

src/components/edit-on-github/edit-on-github.module.css

@@ -0,0 +1,20 @@
+.container {
+  margin: 0;
+  padding: 0;
+}
+
+.container a,
+.container a:active,
+.container a:focus,
+.container a:visited {
+  padding: calc(var(--size-1) + var(--size-2));
+  border-radius: var(--size-px-2);
+  background-color: var(--color-prism-bg);
+  color: var(--color-accent);
+  text-decoration: none;
+  box-shadow: 0 0 calc(var(--size-1) + var(--size-2)) var(--size-px-00) var(--color-white);
+}
+
+.container a:hover {
+  text-decoration: underline;
+}

src/components/edit-on-github/edit-on-github.spec.js

@@ -0,0 +1,98 @@
+import { expect } from "@esm-bundle/chai";
+import "./edit-on-github.js";
+
+// attributes
+const ROUTE = "/";
+
+describe("Components/Edit on GitHub", () => {
+  let editWrapper;
+  let editLink;
+
+  before(async () => {
+    editWrapper = document.createElement("app-edit-on-github");
+    editWrapper.setAttribute("route", ROUTE);
+
+    document.body.appendChild(editWrapper);
+
+    await editWrapper.updateComplete;
+
+    editLink = editWrapper.querySelector("a");
+  });
+
+  it("should not be undefined", () => {
+    expect(editWrapper).not.equal(undefined);
+  });
+
+  describe("Anchor tag to GitHub", () => {
+    const EXPECTED_BASE =
+      "https://github.com/ProjectEvergreen/www.greenwoodjs.dev/edit/main/src/pages/"; // including trailing
+
+    it("should render an anchor tag targeting a new window", () => {
+      expect(editLink).not.equal(undefined);
+      expect(editLink.getAttribute("target")).equal("_blank");
+    });
+
+    it("should include a title attribute with the label 'Edit on GitHub'", () => {
+      expect(editLink.getAttribute("title")).equal("Edit on GitHub");
+    });
+
+    it("should render the text 'Edit on GitHub'", () => {
+      // use trim to allow backtick use in code
+      expect(editLink.text.trim()).equal("Edit on GitHub");
+    });
+
+    describe("when the route is ONLY a slash", () => {
+      it("should return 'index.md' for root-level ('/')", () => {
+        const expected = `${EXPECTED_BASE}index.md`;
+
+        expect(editLink.getAttribute("href")).equal(expected);
+      });
+    });
+
+    describe("when the route IS NOT a directory", () => {
+      let staticFilepath;
+
+      before(async () => {
+        staticFilepath = "/some/static/filename/"; // ie: "/guides/hosting/netlify/"
+
+        editWrapper = document.createElement("app-edit-on-github");
+        editWrapper.setAttribute("route", staticFilepath);
+
+        document.body.appendChild(editWrapper);
+
+        await editWrapper.updateComplete;
+
+        editLink = editWrapper.querySelector("a");
+      });
+
+      it("should include a href attribute which includes filepath.md", () => {
+        const expected = `${EXPECTED_BASE}some/static/filename.md`;
+
+        expect(editLink.getAttribute("href")).equal(expected);
+      });
+    });
+
+    describe("when the route IS a directory", () => {
+      let missingTrailingPath;
+
+      before(async () => {
+        missingTrailingPath = "/some/path/to/hosting/"; // ie: "/guides/hosting/"
+
+        editWrapper = document.createElement("app-edit-on-github");
+        editWrapper.setAttribute("route", missingTrailingPath);
+
+        document.body.appendChild(editWrapper);
+
+        await editWrapper.updateComplete;
+
+        editLink = editWrapper.querySelector("a");
+      });
+
+      it("should include a href attribute which includes index.md", () => {
+        const expected = `${EXPECTED_BASE}some/path/to/hosting/index.md`;
+
+        expect(editLink.getAttribute("href")).equal(expected);
+      });
+    });
+  });
+});

src/components/edit-on-github/edit-on-github.stories.js

@@ -0,0 +1,40 @@
+import "./edit-on-github.js";
+
+export default {
+  title: "Components/Edit on GitHub",
+  component: "app-edit-on-github",
+};
+
+const Template = (props) => {
+  return `
+    <div style="margin:1em 0;"><p>Linked Route: ${props.args.route}</p></div>
+    <app-edit-on-github route="${props.args.route}"></app-edit-on-github>
+  `;
+};
+
+export const PageRoot = Template.bind(
+  {},
+  {
+    args: {
+      route: "/guides/",
+    },
+  },
+);
+
+export const SectionRoot = Template.bind(
+  {},
+  {
+    args: {
+      route: "/guides/hosting/",
+    },
+  },
+);
+
+export const Section = Template.bind(
+  {},
+  {
+    args: {
+      route: "/guides/hosting/netlify/",
+    },
+  },
+);

src/layouts/guides.html

@@ -12,6 +12,11 @@
       src="../components/table-of-contents/table-of-contents.js"
       data-gwd-opt="static"
     ></script>
+    <script
+      type="module"
+      src="../components/edit-on-github/edit-on-github.js"
+      data-gwd-opt="static"
+    ></script>
     <style>
       body:has(#compact-menu:popover-open) {
         overflow-y: hidden;
@@ -71,6 +76,15 @@
         }
       }
 
+      app-edit-on-github {
+        display: block;
+        padding: var(--size-3) 0;
+        position: sticky;
+        bottom: 0;
+        text-align: right;
+        margin: var(--size-px-7) 0 var(--size-px-3) 0;
+      }
+
       app-heading-box {
         & .spacer {
           display: block;
@@ -108,6 +122,12 @@
           font-size: var(--font-size-1);
         }
 
+        app-edit-on-github {
+          position: fixed;
+          bottom: var(--size-10);
+          right: var(--size-6);
+        }
+
         app-side-nav {
           display: inline-block;
           width: 20%;
@@ -161,6 +181,7 @@
 
     <div class="content-outlet">
       <content-outlet></content-outlet>
+      <app-edit-on-github route="${globalThis.page.route}"></app-edit-on-github>
     </div>
   </body>
 </html>

src/stories/mocks/graph.json

@@ -1213,6 +1213,7 @@
       "../components/run-anywhere/run-anywhere.js data-gwd-opt=\"static\" type=\"module\"",
       "../components/build-with-friends/build-with-friends.js data-gwd-opt=\"static\" type=\"module\"",
       "../components/get-started/get-started.js data-gwd-opt=\"static\" type=\"module\"",
+      "../components/edit-on-github/edit-on-github.js data-gwd-opt=\"static\" type=\"module\"",
       "../styles/home.css"
     ],
     "resources": [],