From f14c6e2fc61afef7d280546b17b31c90e73ed391 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 0ea1c1571c8fda3fb5424f18dc08c37fc49e6c6e 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 5cd7053301c622f98d4681712a86cf11c988eacc 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 b919fb95f7a3b795fd807d89cd6a7293d66248b7 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 d2906407875e1b524b88b00a1701f88b17c4c769 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 e3ae6c5c9c3ced8d4be5dd1977ec4d9392dadb6f 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);