@fullstackdatasolutions/articles 1.2.2 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackdatasolutions/articles",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "private": false,
   "license": "MIT",
   "funding": {

package/src/__tests__/linkClassification.test.ts

@@ -0,0 +1,55 @@
+import { isExternalHttpLink, isNonBrowserNavigationLink } from '../linkClassification'
+
+describe('isNonBrowserNavigationLink', () => {
+  it('returns true for mailto: links', () => {
+    expect(isNonBrowserNavigationLink('mailto:hello@example.com')).toBe(true)
+  })
+
+  it('returns true for tel: links', () => {
+    expect(isNonBrowserNavigationLink('tel:+15551234567')).toBe(true)
+  })
+
+  it('returns false for http:// links', () => {
+    expect(isNonBrowserNavigationLink('http://example.com')).toBe(false)
+  })
+
+  it('returns false for https:// links', () => {
+    expect(isNonBrowserNavigationLink('https://example.com')).toBe(false)
+  })
+
+  it('returns false for root-relative links', () => {
+    expect(isNonBrowserNavigationLink('/articles/some-article')).toBe(false)
+  })
+
+  it('returns false for in-page hash anchors', () => {
+    expect(isNonBrowserNavigationLink('#section')).toBe(false)
+  })
+})
+
+describe('isExternalHttpLink', () => {
+  it('returns false for a root-relative link regardless of siteUrl', () => {
+    expect(isExternalHttpLink('/articles/some-article', 'https://example.com')).toBe(false)
+  })
+
+  it('returns false for an in-page hash anchor', () => {
+    expect(isExternalHttpLink('#section')).toBe(false)
+  })
+
+  it('returns true for an http(s) link when no siteUrl is configured', () => {
+    expect(isExternalHttpLink('https://other-site.com')).toBe(true)
+  })
+
+  it('returns false for a same-origin absolute link when siteUrl is configured', () => {
+    expect(isExternalHttpLink('https://example.com/articles/other', 'https://example.com')).toBe(
+      false
+    )
+  })
+
+  it('returns true for a different-origin absolute link when siteUrl is configured', () => {
+    expect(isExternalHttpLink('https://other-site.com/page', 'https://example.com')).toBe(true)
+  })
+
+  it('returns true when siteUrl is malformed and cannot be parsed', () => {
+    expect(isExternalHttpLink('https://example.com', 'not-a-valid-url')).toBe(true)
+  })
+})

package/src/__tests__/renderMdx.test.tsx

@@ -14,7 +14,18 @@ jest.mock('rehype-slug', () => () => () => {})
 jest.mock('rehype-prism-plus', () => () => () => {})
 jest.mock('remark-gfm', () => () => () => {})
 jest.mock('remark-github-blockquote-alert', () => () => () => {})
+// customRenderer runs the real rehype/hast pipeline, not needed for these
+// unit tests. linkClassification.ts is not mocked - it's dependency-free,
+// and the internal-link-routing tests below rely on its real logic.
 jest.mock('../markdown', () => ({ customRenderer: () => () => {} }))
+jest.mock('next/link', () => ({
+  __esModule: true,
+  default: ({ href, children }: { href: string; children: React.ReactNode }) => (
+    <a href={href} data-testid="next-link">
+      {children}
+    </a>
+  ),
+}))
 
 const originalNodeEnv = process.env.NODE_ENV
 
@@ -203,6 +214,152 @@ describe('renderMdxSource', () => {
     })
   })
 
+  describe('internal link routing', () => {
+    it('routes a root-relative internal link through next/link, not a plain page-reload anchor', async () => {
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const A = components?.a as React.ComponentType<
+            React.AnchorHTMLAttributes<HTMLAnchorElement>
+          >
+          return A
+            ? React.createElement(A, { href: '/articles/other-article' }, 'Other article')
+            : React.createElement('a', { href: '/articles/other-article' }, 'Other article')
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource('[Other article](/articles/other-article)')
+      const { container } = render(el as React.ReactElement)
+
+      const link = container.querySelector('a[href="/articles/other-article"]')
+      expect(link).not.toBeNull()
+      expect(link?.textContent).toBe('Other article')
+      // Confirms next/link (mocked above) actually handled this render,
+      // not a bare intrinsic <a> - this is the assertion that would have
+      // caught the original bug (every in-article link forcing a full
+      // page reload instead of client-side navigation).
+      expect(link?.getAttribute('data-testid')).toBe('next-link')
+    })
+
+    it('leaves an external link as a plain anchor, not routed through next/link', async () => {
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const A = components?.a as React.ComponentType<
+            React.AnchorHTMLAttributes<HTMLAnchorElement>
+          >
+          return A
+            ? React.createElement(
+                A,
+                {
+                  href: 'https://external.example.com',
+                  target: '_blank',
+                  rel: 'noopener noreferrer',
+                },
+                'External'
+              )
+            : null
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource('[External](https://external.example.com)')
+      const { container } = render(el as React.ReactElement)
+
+      const link = container.querySelector('a[href="https://external.example.com"]')
+      expect(link).not.toBeNull()
+      expect(link?.getAttribute('data-testid')).toBeNull()
+      expect(link?.getAttribute('target')).toBe('_blank')
+    })
+
+    it('routes a same-origin absolute link through next/link when siteUrl is configured', async () => {
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const A = components?.a as React.ComponentType<
+            React.AnchorHTMLAttributes<HTMLAnchorElement>
+          >
+          return A
+            ? React.createElement(A, { href: 'https://example.com/articles/other' }, 'Same origin')
+            : null
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource(
+        '[Same origin](https://example.com/articles/other)',
+        undefined,
+        { siteUrl: 'https://example.com', siteName: 'Example' }
+      )
+      const { container } = render(el as React.ReactElement)
+
+      const link = container.querySelector('a[href="https://example.com/articles/other"]')
+      expect(link).not.toBeNull()
+      expect(link?.getAttribute('data-testid')).toBe('next-link')
+    })
+
+    it('leaves an in-page hash anchor as a plain anchor, not routed through next/link', async () => {
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const A = components?.a as React.ComponentType<
+            React.AnchorHTMLAttributes<HTMLAnchorElement>
+          >
+          return A ? React.createElement(A, { href: '#section' }, 'Jump') : null
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource('[Jump](#section)')
+      const { container } = render(el as React.ReactElement)
+
+      const link = container.querySelector('a[href="#section"]')
+      expect(link).not.toBeNull()
+      expect(link?.getAttribute('data-testid')).toBeNull()
+    })
+
+    it('leaves a mailto: link as a plain anchor, not routed through next/link', async () => {
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const A = components?.a as React.ComponentType<
+            React.AnchorHTMLAttributes<HTMLAnchorElement>
+          >
+          return A ? React.createElement(A, { href: 'mailto:hello@example.com' }, 'Email us') : null
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource('[Email us](mailto:hello@example.com)')
+      const { container } = render(el as React.ReactElement)
+
+      const link = container.querySelector('a[href="mailto:hello@example.com"]')
+      expect(link).not.toBeNull()
+      expect(link?.getAttribute('data-testid')).toBeNull()
+    })
+  })
+
   describe('basePath image resolution', () => {
     it('resolves relative img src to absolute path when basePath is provided', async () => {
       mockEvaluate.mockResolvedValue({
@@ -318,7 +475,7 @@ describe('renderMdxSource', () => {
       expect(capturedSrc).not.toBe('/articles/my-article/[object Blob]')
     })
 
-    it('does not inject img component when basePath is not provided', async () => {
+    it('does not inject img component when basePath is not provided, but always injects the link override', async () => {
       let capturedComponents: Record<string, unknown> | undefined
       mockEvaluate.mockResolvedValue({
         default: ({ components }: { components?: Record<string, unknown> }) => {
@@ -329,9 +486,11 @@ describe('renderMdxSource', () => {
       Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
 
       const { renderMdxSource } = await import('../renderMdx')
-      await renderMdxSource('# Test')
+      const el = await renderMdxSource('# Test')
+      render(el as React.ReactElement)
 
-      expect(capturedComponents).toBeUndefined()
+      expect(capturedComponents?.img).toBeUndefined()
+      expect(capturedComponents?.a).toBeInstanceOf(Function)
     })
   })
 

package/src/linkClassification.ts

@@ -0,0 +1,30 @@
+// Pure href classification helpers with no dependency on the rehype/hast
+// pipeline - kept separate from markdown.ts (which pulls in ESM-only
+// rehype/remark plugins Jest can't transform without extra config) so
+// consumers that only need "is this link internal/external/navigable"
+// (like renderMdx.tsx's next/link routing decision) don't have to import
+// that whole transitive dependency chain, in production or in tests.
+
+export function isNonBrowserNavigationLink(href: string): boolean {
+  return (
+    /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(href) &&
+    !href.startsWith('http://') &&
+    !href.startsWith('https://')
+  )
+}
+
+function getOrigin(url: string | undefined): string | null {
+  if (!url) return null
+  try {
+    return new URL(url).origin
+  } catch {
+    return null
+  }
+}
+
+export function isExternalHttpLink(href: string, siteUrl?: string): boolean {
+  if (!href.startsWith('http://') && !href.startsWith('https://')) return false
+  const siteOrigin = getOrigin(siteUrl)
+  if (!siteOrigin) return true
+  return getOrigin(href) !== siteOrigin
+}

package/src/markdown.ts

@@ -13,6 +13,9 @@ import { visit } from 'unist-util-visit'
 import type { TocItem } from './articleTypes'
 import type { ArticlesConfig, LinkTargetStrategy } from './articlesConfig'
 import { reportArticlesError } from './errorReporting'
+import { isExternalHttpLink, isNonBrowserNavigationLink } from './linkClassification'
+
+export { isExternalHttpLink, isNonBrowserNavigationLink }
 
 type LinkTargetOptions = Readonly<{
   strategy?: LinkTargetStrategy
@@ -21,30 +24,6 @@ type LinkTargetOptions = Readonly<{
 
 const DEFAULT_LINK_TARGET_STRATEGY: LinkTargetStrategy = 'external-new-tab'
 
-function isNonBrowserNavigationLink(href: string): boolean {
-  return (
-    /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(href) &&
-    !href.startsWith('http://') &&
-    !href.startsWith('https://')
-  )
-}
-
-function getOrigin(url: string | undefined): string | null {
-  if (!url) return null
-  try {
-    return new URL(url).origin
-  } catch {
-    return null
-  }
-}
-
-function isExternalHttpLink(href: string, siteUrl?: string): boolean {
-  if (!href.startsWith('http://') && !href.startsWith('https://')) return false
-  const siteOrigin = getOrigin(siteUrl)
-  if (!siteOrigin) return true
-  return getOrigin(href) !== siteOrigin
-}
-
 function shouldOpenInNewTab(href: string, options: LinkTargetOptions = {}): boolean {
   if (!href || href.startsWith('#') || isNonBrowserNavigationLink(href)) return false
 

package/src/renderMdx.tsx

@@ -4,7 +4,8 @@
 //   Correct:   className="..."
 //   Incorrect: class="..."
 import React from 'react'
-import type { ComponentType, ImgHTMLAttributes } from 'react'
+import type { AnchorHTMLAttributes, ComponentType, ImgHTMLAttributes } from 'react'
+import Link from 'next/link'
 import * as devRuntime from 'react/jsx-dev-runtime'
 import * as runtime from 'react/jsx-runtime'
 import { evaluate } from '@mdx-js/mdx'
@@ -13,6 +14,7 @@ import rehypeSlug from 'rehype-slug'
 import remarkGfm from 'remark-gfm'
 import remarkGithubBlockquoteAlert from 'remark-github-blockquote-alert'
 import { customRenderer } from './markdown'
+import { isExternalHttpLink, isNonBrowserNavigationLink } from './linkClassification'
 import type { ArticlesConfig } from './articlesConfig'
 
 type MdxContent = ComponentType<{
@@ -29,6 +31,35 @@ function makeImgComponent(basePath: string) {
   }
 }
 
+// Same internal/external classification `customRenderer`'s rehype pass
+// already used to decide target="_blank" (see `applyLinkTarget` in
+// markdown.ts) - reused rather than reimplemented so the two decisions
+// can never drift apart. An in-page anchor (#section) or a non-browser
+// scheme (mailto:, tel:) is never routed through next/link either; only a
+// same-origin, browser-navigable href gets client-side routing.
+function isInternalNavigableHref(href: string, siteUrl?: string): boolean {
+  if (!href || href.startsWith('#') || isNonBrowserNavigationLink(href)) return false
+  return !isExternalHttpLink(href, siteUrl)
+}
+
+function makeLinkComponent(siteUrl?: string) {
+  return function MdxLink({ href, children, ...props }: AnchorHTMLAttributes<HTMLAnchorElement>) {
+    if (typeof href === 'string' && isInternalNavigableHref(href, siteUrl)) {
+      // React.createElement, not JSX, for the same reason makeImgComponent
+      // above uses it: next/link's own (duplicate) @types/react copy in
+      // this monorepo's node_modules is structurally incompatible with
+      // this file's DOM attribute types, and JSX's prop-checking is
+      // stricter about that mismatch than createElement's is.
+      return React.createElement(Link, { href, ...props } as never, children)
+    }
+    return (
+      <a href={href} {...props}>
+        {children}
+      </a>
+    )
+  }
+}
+
 export async function renderMdxSource(source: string, basePath?: string, config?: ArticlesConfig) {
   const isDevelopment = process.env.NODE_ENV === 'development'
 
@@ -45,10 +76,16 @@ export async function renderMdxSource(source: string, basePath?: string, config?
   })
 
   const Content = mdxModule.default as MdxContent
-  const internalComponents = basePath ? { img: makeImgComponent(basePath) } : undefined
-  const components =
-    internalComponents || config?.mdxComponents
-      ? { ...internalComponents, ...config?.mdxComponents }
-      : undefined
+  // `a` is always overridden - unlike `img`, internal-link routing isn't
+  // conditional on basePath being provided. Every article's markdown
+  // links otherwise compile to a plain `<a>` (a full page reload on
+  // click, since @mdx-js/mdx's evaluate() has no knowledge of Next's
+  // router), which was silently forcing a hard navigation - and a fresh
+  // same-site document.referrer - on every single in-article link click.
+  const internalComponents = {
+    a: makeLinkComponent(config?.siteUrl),
+    ...(basePath ? { img: makeImgComponent(basePath) } : {}),
+  }
+  const components = { ...internalComponents, ...config?.mdxComponents }
   return <Content components={components as Record<string, ComponentType<unknown>>} />
 }