Refactor: URL utils (#596)

* [rdar://96841531] refactor: normalize urls

* [rdar://96841531] fix: data url

* [rdar://96841531] fix: address feedback

* [rdar://96841531] test: fix calls `fetchData` with a configurable base url test

* fix: issue with navigator not being fetched properly. Fix JSDoc comments. Properly assert navigator data fetching in test

---------

Co-authored-by: Dobromir Hristov <dhristov@apple.com>

Author: marinaaisa

src/components/DocumentationTopic.vue

@@ -149,6 +149,7 @@
 import Language from 'docc-render/constants/Language';
 import metadata from 'theme/mixins/metadata.js';
 import { buildUrl } from 'docc-render/utils/url-helper';
+import { normalizeRelativePath } from 'docc-render/utils/assets';
 
 import Aside from 'docc-render/components/ContentNode/Aside.vue';
 import BetaLegalText from 'theme/components/DocumentationTopic/BetaLegalText.vue';
@@ -382,14 +383,13 @@ export default {
     };
   },
   computed: {
-    normalizedSwiftPath: ({ normalizePath, swiftPath }) => (normalizePath(swiftPath)),
+    normalizedSwiftPath: ({ swiftPath }) => (normalizeRelativePath(swiftPath)),
     normalizedObjcPath: ({
-      normalizePath,
       objcPath,
       swiftPath,
     }) => (
       // do not append language query parameter if no swiftPath exists
-      normalizePath((objcPath && swiftPath) ? buildUrl(objcPath, {
+      normalizeRelativePath((objcPath && swiftPath) ? buildUrl(objcPath, {
         language: Language.objectiveC.key.url,
       }) : objcPath)
     ),
@@ -517,12 +517,6 @@ export default {
     },
   },
   methods: {
-    normalizePath(path) {
-      // Sometimes `paths` data from `variants` are prefixed with a leading
-      // slash and sometimes they aren't
-      if (!path) return path;
-      return path.startsWith('/') ? path : `/${path}`;
-    },
     extractProps(json) {
       const {
         abstract,
@@ -618,7 +612,7 @@ export default {
 
       this.$nextTick().then(() => {
         this.$router.replace({
-          path: this.normalizePath(this.objcPath),
+          path: normalizeRelativePath(this.objcPath),
           query: {
             ...query,
             language: Language.objectiveC.key.url,

src/components/DocumentationTopic/DocumentationNav/LanguageToggle.vue

@@ -84,6 +84,7 @@
 
 <script>
 import { waitFrames } from 'docc-render/utils/loading';
+import { normalizeRelativePath } from 'docc-render/utils/assets';
 import Language from 'docc-render/constants/Language';
 import throttle from 'docc-render/utils/throttle';
 import NavMenuItemBase from 'docc-render/components/NavMenuItemBase.vue';
@@ -164,7 +165,7 @@ export default {
       return {
         // make sure we dont loose any extra query params on the way
         query: { ...this.$route.query, language },
-        path: this.isCurrentPath(route.path) ? null : this.normalizePath(route.path),
+        path: this.isCurrentPath(route.path) ? null : normalizeRelativePath(route.path),
       };
     },
     async pushRoute(route) {
@@ -182,11 +183,6 @@ export default {
       // include a leading slash, while the router provided path does
       return this.$route.path.replace(/^\//, '') === path;
     },
-    normalizePath(path) {
-      // Sometimes `paths` data from `variants` are prefixed with a leading
-      // slash and sometimes they aren't
-      return path.startsWith('/') ? path : `/${path}`;
-    },
     /**
      * Calculated the width of the select by fetching it from the faux select.
      * @return {Promise<void>}

src/components/DocumentationTopic/Summary/LanguageSwitcher.vue

@@ -34,6 +34,7 @@
 
 <script>
 import { buildUrl } from 'docc-render/utils/url-helper';
+import { normalizeRelativePath } from 'docc-render/utils/assets';
 import Language from 'docc-render/constants/Language';
 
 import LanguageSwitcherLink from './LanguageSwitcherLink.vue';
@@ -81,26 +82,24 @@ export default {
     // current URL.
     objc: ({
       interfaceLanguage,
-      normalizePath,
       objcPath,
       $route: { query },
     }) => ({
       ...Language.objectiveC,
       active: Language.objectiveC.key.api === interfaceLanguage,
-      url: buildUrl(normalizePath(objcPath), {
+      url: buildUrl(normalizeRelativePath(objcPath), {
         ...query,
         language: Language.objectiveC.key.url,
       }),
     }),
     swift: ({
       interfaceLanguage,
-      normalizePath,
       swiftPath,
       $route: { query },
     }) => ({
       ...Language.swift,
       active: Language.swift.key.api === interfaceLanguage,
-      url: buildUrl(normalizePath(swiftPath), {
+      url: buildUrl(normalizeRelativePath(swiftPath), {
         ...query,
         language: undefined,
       }),
@@ -114,11 +113,6 @@ export default {
 
       this.$router.push(language.url);
     },
-    normalizePath(path) {
-      // Sometimes `paths` data from `variants` are prefixed with a leading
-      // slash and sometimes they aren't
-      return path.startsWith('/') ? path : `/${path}`;
-    },
   },
 };
 </script>

src/components/ImageAsset.vue

@@ -62,20 +62,20 @@ import imageAsset from 'docc-render/mixins/imageAsset';
 import AppStore from 'docc-render/stores/AppStore';
 import ColorScheme from 'docc-render/constants/ColorScheme';
 import noImage from 'theme/assets/img/no-image@2x.png';
-import { getIntrinsicDimensions, normalizeAssetUrl } from 'docc-render/utils/assets';
+import { getIntrinsicDimensions, normalizePath } from 'docc-render/utils/assets';
 
 const RADIX_DECIMAL = 10;
 
 function constructAttributes(sources) {
   if (!sources.length) {
     return null;
   }
-  const srcSet = sources.map(s => `${normalizeAssetUrl(s.src)} ${s.density}`).join(', ');
+  const srcSet = sources.map(s => `${normalizePath(s.src)} ${s.density}`).join(', ');
   const defaultSource = sources[0];
 
   const attrs = {
     srcSet,
-    src: normalizeAssetUrl(defaultSource.src),
+    src: normalizePath(defaultSource.src),
   };
 
   // All the variants should have the same size, so use the size of the first

src/components/Tutorial/Hero.vue

@@ -73,7 +73,7 @@ import LinkableElement from 'docc-render/components/LinkableElement.vue';
 
 import GenericModal from 'docc-render/components/GenericModal.vue';
 import PlayIcon from 'theme/components/Icons/PlayIcon.vue';
-import { normalizeAssetUrl, toCSSUrl } from 'docc-render/utils/assets';
+import { normalizePath, toCSSUrl } from 'docc-render/utils/assets';
 import referencesProvider from 'docc-render/mixins/referencesProvider';
 import HeroMetadata from './HeroMetadata.vue';
 
@@ -141,10 +141,10 @@ export default {
         variant.traits.includes('light')
       ));
 
-      return (lightVariant || {}).url;
+      return normalizePath((lightVariant || {}).url);
     },
     projectFilesUrl() {
-      return this.projectFiles ? normalizeAssetUrl(this.references[this.projectFiles].url) : null;
+      return this.projectFiles ? normalizePath(this.references[this.projectFiles].url) : null;
     },
     bgStyle() {
       return {

src/components/VideoAsset.vue

@@ -33,15 +33,15 @@
         is handled with JavaScript media query listeners unlike the `<source>`
         based implementation being used for image assets.
       -->
-      <source :src="normalizeAssetUrl(videoAttributes.url)">
+      <source :src="normalizePath(videoAttributes.url)">
     </video>
   </ConditionalWrapper>
 </template>
 
 <script>
 import {
   separateVariantsByAppearance,
-  normalizeAssetUrl,
+  normalizePath,
   getIntrinsicDimensions,
   extractDensities,
 } from 'docc-render/utils/assets';
@@ -142,7 +142,7 @@ export default {
       : variants.light[0] || {}
     ),
     normalisedPosterPath: ({ defaultPosterAttributes }) => (
-      normalizeAssetUrl(defaultPosterAttributes.src)
+      normalizePath(defaultPosterAttributes.src)
     ),
     videoAttributes: ({
       darkVideoVariantAttributes,
@@ -160,7 +160,7 @@ export default {
     },
   },
   methods: {
-    normalizeAssetUrl,
+    normalizePath,
     async getPosterDimensions(path) {
       if (!path) {
         this.optimalWidth = null;

src/utils/assets.js

@@ -8,11 +8,6 @@
  * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-/**
- * Utility functions for working with Assets
- */
-import { baseUrl } from 'docc-render/utils/theme-settings';
-
 /**
  * Separate array of variants by light/dark mode
  * @param {array} variants
@@ -65,23 +60,37 @@ export function pathJoin(parts) {
 }
 
 /**
- * Normalizes asset urls, by prefixing the baseUrl path to them.
- * @param {String} url
- * @return {String}
+ * Normalizes paths, by prefixing the baseUrl path to them.
+ * @param {string | string[]} rawPath
+ * @return {string}
  */
-export function normalizeAssetUrl(url) {
-  if (!url || typeof url !== 'string' || url.startsWith(baseUrl) || !url.startsWith('/')) {
-    return url;
+export function normalizePath(rawPath) {
+  const { baseUrl } = window;
+  const path = Array.isArray(rawPath) ? pathJoin(rawPath) : rawPath;
+  if (!path || typeof path !== 'string' || path.startsWith(baseUrl) || !path.startsWith('/')) {
+    return path;
   }
-  return pathJoin([baseUrl, url]);
+  return pathJoin([baseUrl, path]);
+}
+
+/**
+ * Normalizes relative paths, by making them start with /.
+ * @param {string} path
+ * @return {string}
+ */
+export function normalizeRelativePath(path) {
+  // Sometimes `paths` data from `variants` are prefixed with a leading
+  // slash and sometimes they aren't
+  if (!path) return path;
+  return path.startsWith('/') ? path : `/${path}`;
 }
 
 /**
  * Transforms a URL string into a normalized css `url(/path)` format.
  * @param {String} url
  * @returns {string|undefined}
  */
-export function toCSSUrl(url) { return url ? `url('${normalizeAssetUrl(url)}')` : undefined; }
+export function toCSSUrl(url) { return url ? `url('${normalizePath(url)}')` : undefined; }
 
 /**
  * Loads an image and gets its dimensions

src/utils/data.js

@@ -8,10 +8,11 @@
  * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-import { pathJoin } from 'docc-render/utils/assets';
-import { queryStringForParams, areEquivalentLocations } from 'docc-render/utils/url-helper';
+import { normalizePath } from 'docc-render/utils/assets';
+import {
+  queryStringForParams, areEquivalentLocations, getAbsoluteUrl,
+} from 'docc-render/utils/url-helper';
 import emitWarningForSchemaVersionMismatch from 'docc-render/utils/schema-version-check';
-import { baseUrl } from 'docc-render/utils/theme-settings';
 import RedirectError from 'docc-render/errors/RedirectError';
 import FetchError from 'docc-render/errors/FetchError';
 
@@ -30,7 +31,7 @@ export async function fetchData(path, params = {}, options = {}) {
     return !response.ok;
   }
 
-  const url = new URL(path, window.location.href);
+  const url = getAbsoluteUrl(path);
   const queryString = queryStringForParams(params);
   if (queryString) {
     url.search = queryString;
@@ -56,7 +57,7 @@ export async function fetchData(path, params = {}, options = {}) {
 
 function createDataPath(path) {
   const dataPath = path.replace(/\/$/, '');
-  return `${pathJoin([baseUrl, 'data', dataPath])}.json`;
+  return `${normalizePath(['/data', dataPath])}.json`;
 }
 
 /**
@@ -137,6 +138,6 @@ export function clone(jsonObject) {
 }
 
 export async function fetchIndexPathsData({ slug }) {
-  const path = new URL(`${pathJoin([baseUrl, 'index/', slug, 'index.json'])}`, window.location.href);
+  const path = getAbsoluteUrl(['/index/', slug, 'index.json']);
   return fetchData(path);
 }

src/utils/theme-settings.js

@@ -9,6 +9,7 @@
 */
 
 import get from 'docc-render/utils/get';
+import { resolveAbsoluteUrl } from 'docc-render/utils/url-helper';
 
 /**
  * Theme settings state.
@@ -27,8 +28,8 @@ export const { baseUrl } = window;
  * @return {Promise<{}>}
  */
 export async function fetchThemeSettings() {
-  const url = new URL(`${baseUrl}theme-settings.json`, window.location.href);
-  return fetch(url.href)
+  const url = resolveAbsoluteUrl('/theme-settings.json');
+  return fetch(url)
     .then(r => r.json())
     .catch(() => ({}));
 }