From 34894e2876c52db7f848dc1907f7d44a6624b54b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marina=20A=C3=ADsa?= <marina.aisa@apple.com>
Date: Mon, 24 Nov 2025 16:35:52 +0000
Subject: [PATCH 1/6] Normalize URL for CallToActionButton

It prefixes the URL with the baseUrl value if the path is relative and
the baseUrl is provided. If the path is absolute or the baseUrl is not
provided, it does not prefixes the URL.
---
 src/components/CallToActionButton.vue         |  6 +-
 .../components/CallToActionButton.spec.js     | 58 +++++++++++++------
 2 files changed, 45 insertions(+), 19 deletions(-)

diff --git a/src/components/CallToActionButton.vue b/src/components/CallToActionButton.vue
index c8d0893ce..fb8f7d317 100644
--- a/src/components/CallToActionButton.vue
+++ b/src/components/CallToActionButton.vue
@@ -11,7 +11,7 @@
 <template>
   <DestinationDataProvider v-if="action" :destination="action" v-slot="{ url, title }">
     <ButtonLink
-      :url="url"
+      :url="normalizePath(url)"
       :isDark="isDark"
     >
       {{ title }}
@@ -22,6 +22,7 @@
 
 import ButtonLink from 'docc-render/components/ButtonLink.vue';
 import DestinationDataProvider from 'docc-render/components/DestinationDataProvider.vue';
+import { normalizePath } from 'docc-render/utils/assets';
 
 export default {
   name: 'CallToActionButton',
@@ -29,6 +30,9 @@ export default {
     DestinationDataProvider,
     ButtonLink,
   },
+  methods: {
+    normalizePath,
+  },
   props: {
     action: {
       type: Object,
diff --git a/tests/unit/components/CallToActionButton.spec.js b/tests/unit/components/CallToActionButton.spec.js
index a4006fdfe..3cbd828d3 100644
--- a/tests/unit/components/CallToActionButton.spec.js
+++ b/tests/unit/components/CallToActionButton.spec.js
@@ -9,6 +9,7 @@
 */
 
 import { shallowMount } from '@vue/test-utils';
+import { pathJoin } from 'docc-render/utils/assets';
 import CallToActionButton from 'docc-render/components/CallToActionButton.vue';
 
 const { ButtonLink, DestinationDataProvider } = CallToActionButton.components;
@@ -23,39 +24,60 @@ describe('CallToActionButton', () => {
     },
     isDark: true,
   };
+
+  const relativePath = '/foo/bar';
+  const absolutePath = 'http://example.com/foo/bar';
+
   let wrapper;
 
-  const provide = {
+  const createProvide = references => ({
     store: {
-      state: {
-        references: {
-          [propsData.action.identifier]: {
-            title: 'Foo Bar',
-            url: '/foo/bar',
-          },
-        },
-      },
+      state: { references },
     },
-  };
+  });
 
-  beforeEach(() => {
-    wrapper = shallowMount(CallToActionButton, {
+  const createReferences = ({ url }) => ({
+    [propsData.action.identifier]: {
+      title: 'Foo Bar',
+      url,
+    },
+  });
+
+  const createWrapper = ({ provide } = {}) => (
+    shallowMount(CallToActionButton, {
       propsData,
       stubs: { DestinationDataProvider },
-      provide,
-    });
-  });
+      provide: provide || createProvide(createReferences({ url: relativePath })),
+    })
+  );
 
-  it('renders a `ButtonLink`', () => {
+  const baseUrl = '/base-prefix';
+
+  it('renders a `ButtonLink` with relative path', () => {
+    wrapper = createWrapper();
     const btn = wrapper.findComponent(ButtonLink);
     expect(btn.exists()).toBe(true);
-    expect(btn.props('url'))
-      .toBe(provide.store.state.references[propsData.action.identifier].url);
+    expect(btn.props('url')).toBe(relativePath);
     expect(btn.props('isDark')).toBe(propsData.isDark);
     expect(btn.text()).toBe(propsData.action.overridingTitle);
   });
 
+  it('prefixes `ButtonLink` URL if baseUrl is provided', () => {
+    window.baseUrl = baseUrl;
+    wrapper = createWrapper();
+
+    const btn = wrapper.findComponent(ButtonLink);
+    expect(btn.props('url')).toBe(pathJoin([baseUrl, relativePath]));
+  });
+
+  it('does not prefix `ButtonLink` URL if baseUrl is provided but path is absolute', () => {
+    window.baseUrl = baseUrl;
+    wrapper = createWrapper({ provide: createProvide(createReferences({ url: absolutePath })) });
+    expect(wrapper.findComponent(ButtonLink).props('url')).toBe(absolutePath);
+  });
+
   it('renders a `DestinationDataProvider`', () => {
+    wrapper = createWrapper();
     const provider = wrapper.findComponent(DestinationDataProvider);
     expect(provider.exists()).toBe(true);
     expect(provider.props('destination')).toBe(propsData.action);

From 3101331f0ff1275d98ee2b3d2bdddbc5518e5c03 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marina=20A=C3=ADsa?= <marina.aisa@apple.com>
Date: Mon, 24 Nov 2025 16:41:22 +0000
Subject: [PATCH 2/6] Add linksToAsset prop

We only want to normalize the URL in the case that it links to an asset,
that's why in this commit we introduce a new boolean prop for the
CallToActionButton called `linksToAsset`.
---
 src/components/CallToActionButton.vue            |  6 +++++-
 tests/unit/components/CallToActionButton.spec.js | 12 ++++++++++++
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/src/components/CallToActionButton.vue b/src/components/CallToActionButton.vue
index fb8f7d317..8cd7b4f4c 100644
--- a/src/components/CallToActionButton.vue
+++ b/src/components/CallToActionButton.vue
@@ -11,7 +11,7 @@
 <template>
   <DestinationDataProvider v-if="action" :destination="action" v-slot="{ url, title }">
     <ButtonLink
-      :url="normalizePath(url)"
+      :url="linksToAsset ? normalizePath(url) : url"
       :isDark="isDark"
     >
       {{ title }}
@@ -42,6 +42,10 @@ export default {
       type: Boolean,
       default: false,
     },
+    linksToAsset: {
+      type: Boolean,
+      default: false,
+    },
   },
 };
 </script>
diff --git a/tests/unit/components/CallToActionButton.spec.js b/tests/unit/components/CallToActionButton.spec.js
index 3cbd828d3..b833dec71 100644
--- a/tests/unit/components/CallToActionButton.spec.js
+++ b/tests/unit/components/CallToActionButton.spec.js
@@ -23,6 +23,7 @@ describe('CallToActionButton', () => {
       type: 'reference',
     },
     isDark: true,
+    linksToAsset: true,
   };
 
   const relativePath = '/foo/bar';
@@ -70,6 +71,17 @@ describe('CallToActionButton', () => {
     expect(btn.props('url')).toBe(pathJoin([baseUrl, relativePath]));
   });
 
+  it('does not prefixes `ButtonLink` URL if path should not be normalized', async () => {
+    window.baseUrl = baseUrl;
+    wrapper = createWrapper();
+    await wrapper.setProps({
+      linksToAsset: false,
+    });
+
+    const btn = wrapper.findComponent(ButtonLink);
+    expect(btn.props('url')).toBe(relativePath);
+  });
+
   it('does not prefix `ButtonLink` URL if baseUrl is provided but path is absolute', () => {
     window.baseUrl = baseUrl;
     wrapper = createWrapper({ provide: createProvide(createReferences({ url: absolutePath })) });

From bd040248564a1c0facfba6b550fd8cea7e2e44ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marina=20A=C3=ADsa?= <marina.aisa@apple.com>
Date: Mon, 24 Nov 2025 16:42:02 +0000
Subject: [PATCH 3/6] Apply linksToAsset to DownloadButton in Sample code

Now that we have the prop linksToAsset available for
CallToActionButton components, we want to pass it as true for the
download button used for Sample Codes, since the URL links to an asset.
---
 src/components/DocumentationTopic.vue | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/components/DocumentationTopic.vue b/src/components/DocumentationTopic.vue
index d7dd22134..d97b94a6b 100644
--- a/src/components/DocumentationTopic.vue
+++ b/src/components/DocumentationTopic.vue
@@ -62,7 +62,11 @@
           :content="abstract"
         />
         <div v-if="sampleCodeDownload">
-          <DownloadButton class="sample-download" :action="sampleCodeDownload.action" />
+          <DownloadButton
+            class="sample-download"
+            :action="sampleCodeDownload.action"
+            linksToAsset
+          />
         </div>
         <Availability
           v-if="shouldShowAvailability"

From 226e7736b43172809d3b197e3e72e311ff857e09 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marina=20A=C3=ADsa?= <marina.aisa@apple.com>
Date: Tue, 25 Nov 2025 14:12:14 +0000
Subject: [PATCH 4/6] Add isAbsoluteUrl helper function

We want to use this function to check if urls are absolute or not.
---
 src/utils/url-helper.js             | 21 ++++++++++++++++++
 tests/unit/utils/url-helper.spec.js | 34 +++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/src/utils/url-helper.js b/src/utils/url-helper.js
index c6211006e..20355c9e9 100644
--- a/src/utils/url-helper.js
+++ b/src/utils/url-helper.js
@@ -108,3 +108,24 @@ export function getAbsoluteUrl(path, domainPath = window.location.href) {
 export function resolveAbsoluteUrl(path, domainPath) {
   return getAbsoluteUrl(path, domainPath).href;
 }
+
+/**
+ * Check if a URL is absolute (has a protocol scheme).
+ *
+ * @param {string} url - The URL to check.
+ * @return {boolean} True if the URL is absolute, false if relative.
+ *
+ * @example
+ * isAbsoluteUrl('https://example.com/path') // true
+ * isAbsoluteUrl('/relative/path') // false
+ * isAbsoluteUrl('relative/path') // false
+ */
+export function isAbsoluteUrl(url) {
+  try {
+    // eslint-disable-next-line no-new
+    new URL(url);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
diff --git a/tests/unit/utils/url-helper.spec.js b/tests/unit/utils/url-helper.spec.js
index 70e5e7d22..0b99f6f92 100644
--- a/tests/unit/utils/url-helper.spec.js
+++ b/tests/unit/utils/url-helper.spec.js
@@ -13,6 +13,7 @@ import TechnologiesQueryParams from 'docc-render/constants/TechnologiesQueryPara
 let areEquivalentLocations;
 let buildUrl;
 let resolveAbsoluteUrl;
+let isAbsoluteUrl;
 
 const normalizePathMock = jest.fn().mockImplementation(n => n);
 
@@ -29,6 +30,7 @@ function importDeps() {
     areEquivalentLocations,
     buildUrl,
     resolveAbsoluteUrl,
+    isAbsoluteUrl,
   // eslint-disable-next-line global-require
   } = require('@/utils/url-helper'));
 }
@@ -185,3 +187,35 @@ describe('resolveAbsoluteUrl', () => {
       .toBe('https://swift.org/foo/bar');
   });
 });
+
+describe('isAbsoluteUrl', () => {
+  beforeEach(() => {
+    importDeps();
+    jest.clearAllMocks();
+  });
+
+  it('returns true for absolute URLs', () => {
+    expect(isAbsoluteUrl('https://example.com')).toBe(true);
+    expect(isAbsoluteUrl('https://example.com/path')).toBe(true);
+  });
+
+  it('returns true for other protocol schemes', () => {
+    expect(isAbsoluteUrl('mailto:test@example.com')).toBe(true);
+    expect(isAbsoluteUrl('tel:+1234567890')).toBe(true);
+  });
+
+  it('returns false for relative paths starting with /', () => {
+    expect(isAbsoluteUrl('/relative/path')).toBe(false);
+    expect(isAbsoluteUrl('/')).toBe(false);
+  });
+
+  it('returns false for relative paths not starting with /', () => {
+    expect(isAbsoluteUrl('relative/path')).toBe(false);
+    expect(isAbsoluteUrl('./current/path')).toBe(false);
+  });
+
+  it('returns false for empty or invalid URLs', () => {
+    expect(isAbsoluteUrl('')).toBe(false);
+    expect(isAbsoluteUrl('not-a-valid-url')).toBe(false);
+  });
+});

From 5a7aa9ab04de8bbbeabd4506724692408bdaafbe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marina=20A=C3=ADsa?= <marina.aisa@apple.com>
Date: Tue, 25 Nov 2025 14:13:54 +0000
Subject: [PATCH 5/6] Normalize relative path

For the normalizePath function to work, the path needs to be relative.
This means that we need to normalize the relative path first, to make
sure that the normalizePath function reads it as a relative path.

For this, we should use the function isAbsoluteUrl to see if the url is
absolute or not.
---
 src/components/CallToActionButton.vue | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/components/CallToActionButton.vue b/src/components/CallToActionButton.vue
index 8cd7b4f4c..66b8010d9 100644
--- a/src/components/CallToActionButton.vue
+++ b/src/components/CallToActionButton.vue
@@ -11,7 +11,7 @@
 <template>
   <DestinationDataProvider v-if="action" :destination="action" v-slot="{ url, title }">
     <ButtonLink
-      :url="linksToAsset ? normalizePath(url) : url"
+      :url="normalizeUrl(url)"
       :isDark="isDark"
     >
       {{ title }}
@@ -22,7 +22,8 @@
 
 import ButtonLink from 'docc-render/components/ButtonLink.vue';
 import DestinationDataProvider from 'docc-render/components/DestinationDataProvider.vue';
-import { normalizePath } from 'docc-render/utils/assets';
+import { isAbsoluteUrl } from 'docc-render/utils/url-helper';
+import { normalizePath, normalizeRelativePath } from 'docc-render/utils/assets';
 
 export default {
   name: 'CallToActionButton',
@@ -31,7 +32,10 @@ export default {
     ButtonLink,
   },
   methods: {
-    normalizePath,
+    normalizeUrl(url) {
+      if (!this.linksToAsset || isAbsoluteUrl(url)) return url;
+      return normalizePath(normalizeRelativePath(url));
+    },
   },
   props: {
     action: {

From f910276221476d00df276413358e1a109eb93a00 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marina=20A=C3=ADsa?= <marina.aisa@apple.com>
Date: Tue, 25 Nov 2025 15:33:33 +0000
Subject: [PATCH 6/6] Add new test for simple-relative paths

We want to make sure that simple-relative paths like 'foo/bar' also work
when prefixing the baseUrl.
---
 .../components/CallToActionButton.spec.js     | 27 +++++++++++++------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/tests/unit/components/CallToActionButton.spec.js b/tests/unit/components/CallToActionButton.spec.js
index b833dec71..4bb58b403 100644
--- a/tests/unit/components/CallToActionButton.spec.js
+++ b/tests/unit/components/CallToActionButton.spec.js
@@ -26,7 +26,8 @@ describe('CallToActionButton', () => {
     linksToAsset: true,
   };
 
-  const relativePath = '/foo/bar';
+  const simpleRelativePath = 'foo/bar';
+  const rootRelativePath = '/foo/bar';
   const absolutePath = 'http://example.com/foo/bar';
 
   let wrapper;
@@ -48,17 +49,17 @@ describe('CallToActionButton', () => {
     shallowMount(CallToActionButton, {
       propsData,
       stubs: { DestinationDataProvider },
-      provide: provide || createProvide(createReferences({ url: relativePath })),
+      provide: provide || createProvide(createReferences({ url: rootRelativePath })),
     })
   );
 
   const baseUrl = '/base-prefix';
 
-  it('renders a `ButtonLink` with relative path', () => {
+  it('renders a `ButtonLink` with root-relative path', () => {
     wrapper = createWrapper();
     const btn = wrapper.findComponent(ButtonLink);
     expect(btn.exists()).toBe(true);
-    expect(btn.props('url')).toBe(relativePath);
+    expect(btn.props('url')).toBe(rootRelativePath);
     expect(btn.props('isDark')).toBe(propsData.isDark);
     expect(btn.text()).toBe(propsData.action.overridingTitle);
   });
@@ -68,10 +69,20 @@ describe('CallToActionButton', () => {
     wrapper = createWrapper();
 
     const btn = wrapper.findComponent(ButtonLink);
-    expect(btn.props('url')).toBe(pathJoin([baseUrl, relativePath]));
+    expect(btn.props('url')).toBe(pathJoin([baseUrl, rootRelativePath]));
   });
 
-  it('does not prefixes `ButtonLink` URL if path should not be normalized', async () => {
+  it('prefixes `ButtonLink` URL if baseUrl is provided and path is a simple-relative path', () => {
+    window.baseUrl = baseUrl;
+    wrapper = createWrapper({
+      provide: createProvide(createReferences({ url: simpleRelativePath })),
+    });
+
+    const btn = wrapper.findComponent(ButtonLink);
+    expect(btn.props('url')).toBe(pathJoin([baseUrl, simpleRelativePath]));
+  });
+
+  it('does not prefixes `ButtonLink` URL if path does not link to asset', async () => {
     window.baseUrl = baseUrl;
     wrapper = createWrapper();
     await wrapper.setProps({
@@ -79,10 +90,10 @@ describe('CallToActionButton', () => {
     });
 
     const btn = wrapper.findComponent(ButtonLink);
-    expect(btn.props('url')).toBe(relativePath);
+    expect(btn.props('url')).toBe(rootRelativePath);
   });
 
-  it('does not prefix `ButtonLink` URL if baseUrl is provided but path is absolute', () => {
+  it('does not prefix `ButtonLink` URL if baseUrl is provided but URL is absolute', () => {
     window.baseUrl = baseUrl;
     wrapper = createWrapper({ provide: createProvide(createReferences({ url: absolutePath })) });
     expect(wrapper.findComponent(ButtonLink).props('url')).toBe(absolutePath);