Support hash-only transitions in proper-links (#336)

* Support hash-only transitions in proper-links

* Add example to docs

* Add unit tests for shouldHandle

Author: mmun

docs-app/public/docs/4-routing/proper-links.md

@@ -25,13 +25,14 @@ import `properLinks` and apply it to your Router.
 
 Once `@properLinks` is installed and setup, you can use plain `<a>` tags for navigation like this
 
-```gjs live preview 
+```gjs live preview
 <template>
-  <nav style="display: flex; gap: 0.5rem">
-    <a href="/">Home</a> 
-    <a href="/4-routing/link">Link docs</a> 
-    <a href="/4-routing/external-link">ExternalLink docs</a> 
-    <a href="https://developer.mozilla.org">MDN ➚</a> 
+  <nav id="example" style="display: flex; gap: 0.5rem">
+    <a href="/">Home</a>
+    <a href="#example">Link using a hash</a>
+    <a href="/4-routing/link">Link docs</a>
+    <a href="/4-routing/external-link">ExternalLink docs</a>
+    <a href="https://developer.mozilla.org">MDN ➚</a>
   </nav>
 </template>
 ```

ember-primitives/src/proper-links.ts

@@ -109,13 +109,63 @@ export function handle(
   ignore: string[],
   event: MouseEvent
 ) {
-  if (!element) return;
+  if (!shouldHandle(location.href, element, ignore, event)) {
+    return;
+  }
+
+  let url = new URL(element.href);
+
+  let fullHref = `${url.pathname}${url.search}${url.hash}`;
+
+  let rootURL = router.rootURL;
+
+  let withoutRootURL = fullHref.slice(rootURL.length);
+
+  // re-add the "root" sigil
+  // we removed it when we chopped off the rootURL,
+  // because the rootURL often has this attached to it as well
+  if (!withoutRootURL.startsWith('/')) {
+    withoutRootURL = `/${withoutRootURL}`;
+  }
+
+  try {
+    let routeInfo = router.recognize(fullHref);
+
+    if (routeInfo) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      event.stopPropagation();
+
+      router.transitionTo(withoutRootURL);
+
+      return false;
+    }
+  } catch (e) {
+    if (e instanceof Error && e.name === 'UnrecognizedURLError') {
+      return;
+    }
+
+    throw e;
+  }
+}
+
+/**
+ * Returns `true` if the link should be handled by the Ember router
+ * Returns `false` if the link should be handled by the browser
+ */
+export function shouldHandle(
+  href: string,
+  element: HTMLAnchorElement,
+  ignore: string[],
+  event: MouseEvent
+) {
+  if (!element) return false;
   /**
    * If we don't have an href, the <a> is invalid.
    * If you're debugging your code and end up finding yourself
    * early-returning here, please add an href ;)
    */
-  if (!element.href) return;
+  if (!element.href) return false;
 
   /**
    * This is partially an escape hatch, but any time target is set,
@@ -129,91 +179,75 @@ export function handle(
    * "proper links" is to do what is expected, always -- for in-app SPA links
    * as well as external, cross-domain links
    */
-  if (element.target) return;
+  if (element.target) return false;
 
   /**
    * If the click is not a "left click" we don't want to intercept the event.
    * This allows folks to
    * - middle click (usually open the link in a new tab)
    * - right click (usually opens the context menu)
    */
-  if (event.button !== 0) return;
+  if (event.button !== 0) return false;
 
   /**
    * for MacOS users, this default behavior opens the link in a new tab
    */
-  if (event.metaKey) return;
+  if (event.metaKey) return false;
 
   /**
    * for for everyone else, this default behavior opens the link in a new tab
    */
-  if (event.ctrlKey) return;
+  if (event.ctrlKey) return false;
 
   /**
    * The default behavior here downloads the link content
    */
-  if (event.altKey) return;
+  if (event.altKey) return false;
 
   /**
    * The default behavior here opens the link in a new window
    */
-  if (event.shiftKey) return;
+  if (event.shiftKey) return false;
 
   /**
    * If another event listener called event.preventDefault(), we don't want to proceed.
    */
-  if (event.defaultPrevented) return;
+  if (event.defaultPrevented) return false;
 
   /**
    * The href includes the protocol/host/etc
    * In order to not have the page look like a full page refresh,
    * we need to chop that "origin" off, and just use the path
    */
   let url = new URL(element.href);
+  let location = new URL(href);
 
   /**
    * If the domains are different, we want to fall back to normal link behavior
    *
    */
-  if (location.origin !== url.origin) return;
+  if (location.origin !== url.origin) return false;
 
   /**
-   * We can optionally declare some paths as ignored,
-   * or "let the browser do its default thing,
-   * because there is other server-based routing to worry about"
+   * Hash-only links are handled by the browser, except for the case where the
+   * hash is being removed entirely, e.g. /foo#bar to /foo. In that case the
+   * browser will do a full page refresh which is not what we want. Instead
+   * we let the router handle such transitions. The current implementation of
+   * the Ember router will skip the transition in this case because the path
+   * is the same.
    */
-  if (ignore.includes(url.pathname)) return;
-
-  let fullHref = `${url.pathname}${url.search}${url.hash}`;
-
-  let rootURL = router.rootURL;
+  let [prehash, posthash] = url.href.split('#');
 
-  let withoutRootURL = fullHref.slice(rootURL.length);
-
-  // re-add the "root" sigil
-  // we removed it when we chopped off the rootURL,
-  // because the rootURL often has this attached to it as well
-  if (!withoutRootURL.startsWith('/')) {
-    withoutRootURL = `/${withoutRootURL}`;
+  if (posthash !== undefined && prehash === location.href.split('#')[0]) {
+    return false;
   }
 
-  try {
-    let routeInfo = router.recognize(fullHref);
-
-    if (routeInfo) {
-      event.preventDefault();
-      event.stopImmediatePropagation();
-      event.stopPropagation();
-
-      router.transitionTo(withoutRootURL);
-
-      return false;
-    }
-  } catch (e) {
-    if (e instanceof Error && e.name === 'UnrecognizedURLError') {
-      return;
-    }
+  /**
+   * We can optionally declare some paths as ignored,
+   * or "let the browser do its default thing,
+   * because there is other server-based routing to worry about"
+   */
+  if (ignore.includes(url.pathname)) return false;
 
-    throw e;
-  }
+  return true;
 }

test-app/tests/proper-links/unit-test.ts

@@ -0,0 +1,33 @@
+import { module, test } from 'qunit';
+
+import { shouldHandle } from 'ember-primitives/proper-links';
+
+module('@properLinks', function () {
+  module('shouldHandle', function () {
+    test('hash-only links', async function (assert) {
+      function assertShouldHandle(
+        expected: boolean,
+        { location, href }: { location: string; href: string }
+      ) {
+        let url = new URL(location, 'https://example.com');
+
+        let anchor = document.createElement('a');
+
+        anchor.href = new URL(href, url).href;
+
+        let ignored: string[] = [];
+        let simpleClickEvent = new MouseEvent('click');
+
+        assert.strictEqual(shouldHandle(url.href, anchor, ignored, simpleClickEvent), expected);
+      }
+
+      assertShouldHandle(false, { location: '/foo', href: '/foo#bar' });
+      assertShouldHandle(false, { location: '/foo', href: '#bar' });
+      assertShouldHandle(false, { location: '/foo#bar', href: '/foo#other' });
+
+      assertShouldHandle(true, { location: '/foo', href: '/abc#xyz' });
+      assertShouldHandle(true, { location: '/foo#bar', href: '/abc#xyz' });
+      assertShouldHandle(true, { location: '/foo#bar', href: '/foo' });
+    });
+  });
+});