Implement hasProvidedEmail functionality for Download CTA, update other components to use also

Author: webstackdev

src/components/CallToAction/Download/__tests__/index.spec.ts

@@ -2,6 +2,8 @@ import { beforeEach, describe, expect, test } from 'vitest'
 import { experimental_AstroContainer as AstroContainer } from 'astro/container'
 import { withJsdomEnvironment } from '@test/unit/helpers/litRuntime'
 
+const existingResource = 'performance-testing-load-models-benchmark-accuracy'
+
 describe('Download CallToAction (Astro)', () => {
   let container: AstroContainer
 
@@ -21,7 +23,9 @@ describe('Download CallToAction (Astro)', () => {
     await withJsdomEnvironment(async ({ window }) => {
       window.document.body.innerHTML = renderedHtml
 
+      const host = window.document.querySelector('download-cta')
       const section = window.document.querySelector('section')
+      expect(host).toBeTruthy()
       expect(section).toBeTruthy()
       expect(section?.getAttribute('aria-labelledby')).toBe('download-cta-title')
       expect(section?.getAttribute('aria-describedby')).toBe('download-cta-description')
@@ -38,6 +42,31 @@ describe('Download CallToAction (Astro)', () => {
     })
   })
 
+  test('renders direct and landing download URLs for the web component host', async () => {
+    const Download = (await import('@components/CallToAction/Download/index.astro')).default
+
+    const renderedHtml = await container.renderToString(Download, {
+      props: {
+        resource: existingResource,
+      },
+    })
+
+    await withJsdomEnvironment(async ({ window }) => {
+      window.document.body.innerHTML = renderedHtml
+
+      const host = window.document.querySelector('download-cta')
+      const primaryLink = window.document.querySelector('[data-download-cta-primary]')
+
+      expect(host?.getAttribute('data-landing-url')).toBe(
+        `/downloads/${existingResource}`
+      )
+      expect(host?.getAttribute('data-direct-download-url')).toBe(
+        '/downloads/performance-testing-load-models-benchmark-accuracy.pdf'
+      )
+      expect(primaryLink?.getAttribute('href')).toBe(`/downloads/${existingResource}`)
+    })
+  })
+
   test('supports a custom id base for aria relationships', async () => {
     const Download = (await import('@components/CallToAction/Download/index.astro')).default
 

src/components/CallToAction/Download/client/__tests__/__fixtures__/downloadCta.fixture.astro

@@ -0,0 +1,5 @@
+---
+import Download from '@components/CallToAction/Download/index.astro'
+---
+
+<Download resource="performance-testing-load-models-benchmark-accuracy" />

src/components/CallToAction/Download/client/__tests__/index.spec.ts

@@ -0,0 +1,39 @@
+import { afterEach, beforeAll, describe, expect, it } from 'vitest'
+import {
+  __resetEmailCollectionForTests,
+  markEmailCollected,
+} from '@components/scripts/store/emailCollection'
+
+let renderDownloadCta: typeof import('./testUtils').renderDownloadCta
+
+beforeAll(async () => {
+  ;({ renderDownloadCta } = await import('./testUtils'))
+})
+
+describe('download-cta web component', () => {
+  afterEach(() => {
+    if (typeof localStorage !== 'undefined') {
+      localStorage.clear()
+    }
+    __resetEmailCollectionForTests()
+  })
+
+  it('uses the download landing page link until an email has been collected', async () => {
+    await renderDownloadCta(async ({ elements, urls }) => {
+      expect(elements.host.dataset['emailState']).toBe('gated')
+      expect(elements.primaryLink.getAttribute('href')).toBe(urls.landingUrl)
+    })
+  })
+
+  it('switches the primary link to the direct download after email collection', async () => {
+    await renderDownloadCta(async ({ elements, urls }) => {
+      expect(elements.primaryLink.getAttribute('href')).toBe(urls.landingUrl)
+
+      markEmailCollected('reader@example.com', 'newsletter_form')
+      await Promise.resolve()
+
+      expect(elements.host.dataset['emailState']).toBe('ready')
+      expect(elements.primaryLink.getAttribute('href')).toBe(urls.directDownloadUrl)
+    })
+  })
+})

src/components/CallToAction/Download/client/__tests__/testUtils.ts

@@ -0,0 +1,71 @@
+import { expect } from 'vitest'
+import { experimental_AstroContainer as AstroContainer } from 'astro/container'
+import DownloadCtaFixture from './__fixtures__/downloadCta.fixture.astro'
+import type { DownloadCtaElement } from '@components/CallToAction/Download/client'
+import { TestError } from '@test/errors'
+import {
+  getDownloadCtaHost,
+  getDownloadCtaPrimaryLink,
+  getDownloadCtaUrls,
+} from '@components/CallToAction/Download/client/selectors'
+import type { WebComponentModule } from '@components/scripts/@types/webComponentModule'
+import { executeRender } from '@test/unit/helpers/litRuntime'
+
+export type DownloadCtaModule = WebComponentModule<DownloadCtaElement>
+
+export interface DownloadCtaElements {
+  host: HTMLElement
+  primaryLink: HTMLAnchorElement
+}
+
+export interface RenderDownloadCtaContext {
+  element: DownloadCtaElement
+  module: DownloadCtaModule
+  window: Window & typeof globalThis
+  elements: DownloadCtaElements
+  urls: {
+    landingUrl: string
+    directDownloadUrl: string
+  }
+}
+
+export type RenderDownloadCtaAssertion = (
+  _context: RenderDownloadCtaContext
+) => Promise<void> | void
+
+export const renderDownloadCta = async (assertion: RenderDownloadCtaAssertion): Promise<void> => {
+  const container = await AstroContainer.create()
+
+  await executeRender<DownloadCtaModule>({
+    container,
+    component: DownloadCtaFixture,
+    moduleSpecifier: '@components/CallToAction/Download/client/index',
+    selector: 'download-cta',
+    waitForReady: async element => {
+      element.initialize()
+      await Promise.resolve()
+    },
+    assert: async ({ element, module, window, renderResult }) => {
+      if (!window) {
+        throw new TestError('Download CTA tests require a DOM-like window environment')
+      }
+
+      const domWindow = window as Window & typeof globalThis
+      const host = getDownloadCtaHost(domWindow.document)
+      const primaryLink = getDownloadCtaPrimaryLink(domWindow.document)
+
+      expect(renderResult).toContain(`<${module.registeredName}`)
+
+      await assertion({
+        element,
+        module,
+        window: domWindow,
+        elements: {
+          host,
+          primaryLink,
+        },
+        urls: getDownloadCtaUrls(domWindow.document),
+      })
+    },
+  })
+}

src/components/CallToAction/Download/client/index.ts

@@ -0,0 +1,103 @@
+import { LitElement } from 'lit'
+import {
+	getEmailCollectionSnapshot,
+	subscribeToEmailCollection,
+	type EmailCollectionState,
+} from '@components/scripts/store'
+import { addScriptBreadcrumb } from '@components/scripts/errors'
+import { handleScriptError } from '@components/scripts/errors/handler'
+import { defineCustomElement } from '@components/scripts/utils'
+import type { WebComponentModule } from '@components/scripts/@types/webComponentModule'
+import { getDownloadCtaPrimaryLink, getDownloadCtaUrls } from './selectors'
+
+const scriptName = 'DownloadCtaElement'
+
+export class DownloadCtaElement extends LitElement {
+	static registeredName = 'download-cta'
+
+	private primaryLink: HTMLAnchorElement | null = null
+	private unsubscribeFromEmailCollection: (() => void) | null = null
+	private isInitialized = false
+
+	protected override createRenderRoot(): HTMLElement {
+		return this
+	}
+
+	override connectedCallback(): void {
+		super.connectedCallback()
+
+		queueMicrotask(() => {
+			this.initialize()
+		})
+	}
+
+	override disconnectedCallback(): void {
+		this.unsubscribeFromEmailCollection?.()
+		this.unsubscribeFromEmailCollection = null
+		this.isInitialized = false
+		super.disconnectedCallback()
+	}
+
+	public initialize(): void {
+		const context = { scriptName, operation: 'initialize' }
+		addScriptBreadcrumb(context)
+
+		try {
+			if (this.isInitialized) {
+				return
+			}
+
+			this.primaryLink = getDownloadCtaPrimaryLink(this)
+			const { landingUrl, directDownloadUrl } = getDownloadCtaUrls(this)
+
+			this.syncPrimaryLink(getEmailCollectionSnapshot(), {
+				landingUrl,
+				directDownloadUrl,
+			})
+
+			this.unsubscribeFromEmailCollection = subscribeToEmailCollection(state => {
+				this.syncPrimaryLink(state, {
+					landingUrl,
+					directDownloadUrl,
+				})
+			})
+
+			this.isInitialized = true
+		} catch (error) {
+			handleScriptError(error, context)
+		}
+	}
+
+	private syncPrimaryLink(
+		state: EmailCollectionState,
+		urls: { landingUrl: string; directDownloadUrl: string }
+	): void {
+		if (!this.primaryLink) {
+			return
+		}
+
+		const hasProvidedEmail = state.hasProvidedEmail === true
+		const nextHref = hasProvidedEmail ? urls.directDownloadUrl : urls.landingUrl
+		const nextState = hasProvidedEmail ? 'ready' : 'gated'
+
+		this.primaryLink.href = nextHref
+		this.primaryLink.dataset['emailState'] = nextState
+		this.dataset['emailState'] = nextState
+	}
+}
+
+export const registerDownloadCtaWebComponent = (tagName = DownloadCtaElement.registeredName) => {
+	if (typeof window === 'undefined') {
+		return
+	}
+
+	defineCustomElement(tagName, DownloadCtaElement)
+}
+
+export const registerWebComponent = registerDownloadCtaWebComponent
+
+export const webComponentModule: WebComponentModule<DownloadCtaElement> = {
+	registeredName: DownloadCtaElement.registeredName,
+	componentCtor: DownloadCtaElement,
+	registerWebComponent: registerDownloadCtaWebComponent,
+}

src/components/CallToAction/Download/client/selectors.ts

@@ -0,0 +1,66 @@
+import { isAnchorElement, isType1Element } from '@components/scripts/assertions/elements'
+import { ClientScriptError } from '@components/scripts/errors'
+
+const HOST_TAG_NAME = 'DOWNLOAD-CTA'
+
+export const SELECTORS = {
+  host: 'download-cta',
+  primaryLink: '[data-download-cta-primary]',
+} as const
+
+type SelectorRoot = Document | DocumentFragment | Element
+
+const resolveRoot = (root?: SelectorRoot): SelectorRoot => {
+  return root ?? document
+}
+
+const isDownloadCtaHost = (element: unknown): element is HTMLElement => {
+  return isType1Element(element) && element.tagName === HOST_TAG_NAME
+}
+
+export const getDownloadCtaHost = (root?: SelectorRoot): HTMLElement => {
+  const resolvedRoot = resolveRoot(root)
+  const host = isDownloadCtaHost(resolvedRoot)
+    ? resolvedRoot
+    : resolvedRoot.querySelector(SELECTORS.host)
+
+  if (!isDownloadCtaHost(host)) {
+    throw new ClientScriptError({
+      message: 'Download CTA host element not found',
+    })
+  }
+
+  return host
+}
+
+export const getDownloadCtaPrimaryLink = (root?: SelectorRoot): HTMLAnchorElement => {
+  const primaryLink = getDownloadCtaHost(root).querySelector(SELECTORS.primaryLink)
+
+  if (!isAnchorElement(primaryLink)) {
+    throw new ClientScriptError({
+      message: 'Download CTA primary link not found',
+    })
+  }
+
+  return primaryLink
+}
+
+export const getDownloadCtaUrls = (root?: SelectorRoot): {
+  landingUrl: string
+  directDownloadUrl: string
+} => {
+  const host = getDownloadCtaHost(root)
+  const landingUrl = host.dataset['landingUrl']?.trim() ?? ''
+  const directDownloadUrl = host.dataset['directDownloadUrl']?.trim() ?? ''
+
+  if (!landingUrl || !directDownloadUrl) {
+    throw new ClientScriptError({
+      message: 'Download CTA URLs are missing required data attributes',
+    })
+  }
+
+  return {
+    landingUrl,
+    directDownloadUrl,
+  }
+}