@fullstackdatasolutions/articles 0.9.0 → 0.11.0

package/src/__tests__/AuthorCard.test.tsx

@@ -0,0 +1,98 @@
+import { render, screen } from '@testing-library/react'
+import type React from 'react'
+import { AuthorCard } from '../AuthorCard'
+
+jest.mock('next/link', () => ({
+  __esModule: true,
+  default: ({
+    href,
+    children,
+    ...rest
+  }: {
+    href: string
+    children: React.ReactNode
+    [key: string]: unknown
+  }) => (
+    <a href={href} {...rest}>
+      {children}
+    </a>
+  ),
+}))
+
+const author = {
+  name: 'Andrew Blase',
+  slug: 'andrew-blase',
+  bio: 'Writer focused on civic technology.',
+  social: {
+    github: 'blazestudios23',
+    website: 'https://fullstackdatasolutions.com',
+  },
+}
+
+describe('AuthorCard', () => {
+  it('renders author name as a link by default', () => {
+    render(<AuthorCard author={author} />)
+
+    expect(screen.getByRole('link', { name: 'Andrew Blase' })).toHaveAttribute(
+      'href',
+      '/articles/authors/andrew-blase'
+    )
+  })
+
+  it('can show bio and social links', () => {
+    render(<AuthorCard author={author} showBio showSocial />)
+
+    expect(screen.getByText('Writer focused on civic technology.')).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: 'Andrew Blase on GitHub' })).toHaveAttribute(
+      'href',
+      'https://github.com/blazestudios23'
+    )
+    expect(screen.getByRole('link', { name: 'Andrew Blase on Website' })).toHaveAttribute(
+      'href',
+      'https://fullstackdatasolutions.com'
+    )
+  })
+
+  it('only renders social links that are provided', () => {
+    render(
+      <AuthorCard
+        author={{
+          ...author,
+          social: {
+            facebook: 'andrew.blase',
+            linkedin: 'andrewblase',
+            instagram: '@andrewblase',
+            other: {
+              Podcast: 'https://example.com/podcast',
+            },
+          },
+        }}
+        showSocial
+      />
+    )
+
+    expect(screen.getByRole('link', { name: 'Andrew Blase on Facebook' })).toHaveAttribute(
+      'href',
+      'https://www.facebook.com/andrew.blase'
+    )
+    expect(screen.getByRole('link', { name: 'Andrew Blase on LinkedIn' })).toHaveAttribute(
+      'href',
+      'https://www.linkedin.com/in/andrewblase'
+    )
+    expect(screen.getByRole('link', { name: 'Andrew Blase on Instagram' })).toHaveAttribute(
+      'href',
+      'https://www.instagram.com/andrewblase'
+    )
+    expect(screen.getByRole('link', { name: 'Andrew Blase on Podcast' })).toHaveAttribute(
+      'href',
+      'https://example.com/podcast'
+    )
+    expect(screen.queryByRole('link', { name: 'Andrew Blase on GitHub' })).not.toBeInTheDocument()
+  })
+
+  it('does not render social links when no social fields are provided', () => {
+    render(<AuthorCard author={{ ...author, social: undefined }} showSocial />)
+
+    expect(screen.queryByLabelText(/Andrew Blase on/i)).not.toBeInTheDocument()
+  })
+})

package/src/__tests__/AuthorDetailHero.test.tsx

@@ -0,0 +1,51 @@
+/**
+ * @jest-environment jsdom
+ */
+import { render, screen } from '@testing-library/react'
+import { AuthorDetailHero } from '../AuthorDetailHero'
+import type { AuthorProfile } from '../articleTypes'
+
+jest.mock('next/image', () => ({
+  __esModule: true,
+  default: (props: React.ComponentProps<'img'>) => <img {...props} alt={props.alt ?? ''} />,
+}))
+
+const author: AuthorProfile = {
+  name: 'Andrew Blase',
+  slug: 'andrew-blase',
+  bio: 'Writer focused on civic technology.',
+  social: {
+    website: 'https://fullstackdatasolutions.com/',
+  },
+}
+
+describe('AuthorDetailHero', () => {
+  it('renders author details, plural article count, and social links', () => {
+    render(<AuthorDetailHero author={author} articleCount={2} />)
+
+    expect(screen.getByRole('heading', { name: 'Andrew Blase' })).toBeInTheDocument()
+    expect(screen.getByText('Writer focused on civic technology.')).toBeInTheDocument()
+    expect(screen.getByText('2 articles')).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: 'Andrew Blase on Website' })).toHaveAttribute(
+      'href',
+      'https://fullstackdatasolutions.com/'
+    )
+  })
+
+  it('renders initials and singular article count when no avatar is configured', () => {
+    render(<AuthorDetailHero author={author} articleCount={1} />)
+
+    expect(screen.getByText('AB')).toBeInTheDocument()
+    expect(screen.getByText('1 article')).toBeInTheDocument()
+  })
+
+  it('renders the author avatar and hides count when articleCount is omitted', () => {
+    render(<AuthorDetailHero author={{ ...author, avatar: 'avatar.jpg' }} />)
+
+    expect(screen.getByAltText('Andrew Blase')).toHaveAttribute(
+      'src',
+      '/articles/authors/andrew-blase/avatar.jpg'
+    )
+    expect(screen.queryByText(/article/i)).not.toBeInTheDocument()
+  })
+})

package/src/__tests__/CategoryArticlesPage.test.tsx

@@ -41,10 +41,6 @@ jest.mock('../LatestArticles', () => ({
   ),
 }))
 
-jest.mock('../ArticleSchemas', () => ({
-  BreadcrumbSchema: () => null,
-}))
-
 const baseConfig: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Test Site' }
 
 const makeArticle = (overrides: Partial<Article> = {}): Article => ({
@@ -76,7 +72,37 @@ describe('CategoryArticlesPage', () => {
         config={baseConfig}
       />
     )
-    expect(screen.getByText('Campaigns')).toBeInTheDocument()
+    expect(screen.getAllByText('Campaigns').length).toBeGreaterThan(0)
+  })
+
+  it('renders visible breadcrumb navigation', () => {
+    render(
+      <CategoryArticlesPage
+        category="campaigns"
+        articles={[makeArticle({ category: 'Campaigns' })]}
+        config={baseConfig}
+      />
+    )
+    expect(screen.getByRole('navigation', { name: 'Breadcrumb' })).toBeInTheDocument()
+  })
+
+  it('renders custom category breadcrumb links from config', () => {
+    render(
+      <CategoryArticlesPage
+        category="campaigns"
+        articles={[makeArticle({ category: 'Campaigns' })]}
+        config={{
+          ...baseConfig,
+          breadcrumbs: {
+            category: ['home', { name: 'Resources', url: '/resources' }, 'category'],
+          },
+        }}
+      />
+    )
+    expect(screen.getByRole('link', { name: 'Resources' })).toHaveAttribute(
+      'href',
+      'https://example.com/resources'
+    )
   })
 
   it('renders plural article count in the hero', () => {

package/src/__tests__/articlesConfig.test.ts

@@ -1,4 +1,9 @@
-import { DEFAULT_PAGE_SIZE, DEFAULT_CATEGORIES_PAGE_SIZE, DEFAULT_LAYOUT } from '../articlesConfig'
+import {
+  DEFAULT_PAGE_SIZE,
+  DEFAULT_CATEGORIES_PAGE_SIZE,
+  DEFAULT_LAYOUT,
+  type ArticlesConfig,
+} from '../articlesConfig'
 
 describe('articlesConfig constants', () => {
   describe('DEFAULT_PAGE_SIZE', () => {
@@ -54,4 +59,18 @@ describe('articlesConfig constants', () => {
       expect(DEFAULT_LAYOUT).toContain('categories')
     })
   })
+
+  describe('mdxComponents', () => {
+    it('accepts custom components keyed by their MDX tag names', () => {
+      const config: ArticlesConfig = {
+        siteUrl: 'https://example.com',
+        siteName: 'Example',
+        mdxComponents: {
+          LeadMagnetCTA: () => null,
+        },
+      }
+
+      expect(config.mdxComponents?.LeadMagnetCTA).toEqual(expect.any(Function))
+    })
+  })
 })

package/src/__tests__/authorUtils.test.ts

@@ -0,0 +1,89 @@
+import {
+  getAuthorAvatar,
+  getAuthorSameAs,
+  getAuthorSocialLinks,
+  getAuthorUrl,
+} from '../authorUtils'
+import type { AuthorProfile } from '../articleTypes'
+
+const author: AuthorProfile = {
+  name: 'Andrew Blase',
+  slug: 'andrew-blase',
+  bio: 'Writer.',
+}
+
+describe('authorUtils', () => {
+  it('builds author URLs and avatar URLs', () => {
+    expect(getAuthorUrl(author)).toBe('/articles/authors/andrew-blase')
+    expect(getAuthorUrl({ ...author, url: 'https://example.com/andrew' })).toBe(
+      'https://example.com/andrew'
+    )
+    expect(getAuthorAvatar(author)).toBeUndefined()
+    expect(getAuthorAvatar({ ...author, avatar: 'avatar.jpg' })).toBe(
+      '/articles/authors/andrew-blase/avatar.jpg'
+    )
+    expect(getAuthorAvatar({ ...author, avatar: '/avatar.jpg' })).toBe(
+      '/articles/authors/andrew-blase/avatar.jpg'
+    )
+    expect(getAuthorAvatar({ ...author, avatar: 'https://example.com/avatar.jpg' })).toBe(
+      'https://example.com/avatar.jpg'
+    )
+    expect(
+      getAuthorAvatar(
+        { ...author, avatar: 'avatar.jpg' },
+        { siteUrl: 'https://example.com/', siteName: 'Example' }
+      )
+    ).toBe('https://example.com/articles/authors/andrew-blase/avatar.jpg')
+  })
+
+  it('normalizes configured social links and sameAs URLs', () => {
+    const socialAuthor: AuthorProfile = {
+      ...author,
+      social: {
+        website: 'https://fullstackdatasolutions.com/',
+        facebook: 'andrew.blase',
+        twitter: '@andrewblase',
+        x: 'https://x.com/andrewblase',
+        linkedin: 'andrewobrigewitsch',
+        instagram: '@andrewblase',
+        youtube: '@andrewblase',
+        tiktok: '@andrewblase',
+        github: 'blazestudios23',
+        bluesky: 'andrewblase.bsky.social',
+        threads: '@andrewblase',
+        mastodon: 'https://mastodon.social/@andrewblase',
+        medium: '@andrewblase',
+        newsletter: 'https://example.com/newsletter',
+        other: {
+          Podcast: 'https://example.com/podcast',
+          Empty: '   ',
+        },
+      },
+    }
+
+    expect(getAuthorSocialLinks(socialAuthor)).toEqual([
+      { label: 'Website', href: 'https://fullstackdatasolutions.com/' },
+      { label: 'Facebook', href: 'https://www.facebook.com/andrew.blase' },
+      { label: 'Twitter', href: 'https://twitter.com/andrewblase' },
+      { label: 'X', href: 'https://x.com/andrewblase' },
+      { label: 'LinkedIn', href: 'https://www.linkedin.com/in/andrewobrigewitsch' },
+      { label: 'Instagram', href: 'https://www.instagram.com/andrewblase' },
+      { label: 'YouTube', href: 'https://www.youtube.com/andrewblase' },
+      { label: 'TikTok', href: 'https://www.tiktok.com/@andrewblase' },
+      { label: 'GitHub', href: 'https://github.com/blazestudios23' },
+      { label: 'Bluesky', href: 'https://bsky.app/profile/andrewblase.bsky.social' },
+      { label: 'Threads', href: 'https://www.threads.net/@andrewblase' },
+      { label: 'Mastodon', href: 'https://mastodon.social/@andrewblase' },
+      { label: 'Medium', href: 'https://medium.com/@andrewblase' },
+      { label: 'Newsletter', href: 'https://example.com/newsletter' },
+      { label: 'Podcast', href: 'https://example.com/podcast' },
+    ])
+    expect(getAuthorSameAs(socialAuthor)).toEqual(
+      getAuthorSocialLinks(socialAuthor).map((link) => link.href)
+    )
+  })
+
+  it('returns no social links when no social fields are configured', () => {
+    expect(getAuthorSocialLinks(author)).toEqual([])
+  })
+})

package/src/__tests__/renderMdx.test.tsx

@@ -283,6 +283,41 @@ describe('renderMdxSource', () => {
       expect(img?.getAttribute('src')).toBe('https://example.com/img.png')
     })
 
+    it('does not modify non-string img src values', async () => {
+      const imageBlob = new Blob(['image'])
+      let capturedSrc: unknown
+
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const Img = components?.img as React.ComponentType<{
+            alt: string
+            ref?: React.Ref<HTMLImageElement>
+            src: Blob | string
+          }>
+          return Img
+            ? React.createElement(Img, {
+                src: imageBlob,
+                alt: 'test',
+                ref: (node: HTMLImageElement | null) => {
+                  capturedSrc = node?.src
+                },
+              })
+            : React.createElement('img', { alt: 'test' })
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource('![test](photo.png)', '/articles/my-article')
+      render(el as React.ReactElement)
+
+      expect(capturedSrc).not.toBe('/articles/my-article/[object Blob]')
+    })
+
     it('does not inject img component when basePath is not provided', async () => {
       let capturedComponents: Record<string, unknown> | undefined
       mockEvaluate.mockResolvedValue({
@@ -299,4 +334,82 @@ describe('renderMdxSource', () => {
       expect(capturedComponents).toBeUndefined()
     })
   })
+
+  describe('custom MDX components', () => {
+    it('renders a registered custom component with its MDX props', async () => {
+      type LeadMagnetCTAProps = Readonly<{
+        system: string
+        segment: string
+      }>
+      const LeadMagnetCTA = ({ system, segment }: LeadMagnetCTAProps) =>
+        React.createElement('div', { 'data-testid': 'lead-magnet' }, `${system}:${segment}`)
+
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const CustomCTA = components?.LeadMagnetCTA as React.ComponentType<LeadMagnetCTAProps>
+          return React.createElement(CustomCTA, { system: 'DND', segment: 'new-players' })
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const source = 'Article intro.\n\n<LeadMagnetCTA system="DND" segment="new-players" />'
+      const el = await renderMdxSource(source, undefined, {
+        siteUrl: 'https://example.com',
+        siteName: 'Example',
+        mdxComponents: { LeadMagnetCTA },
+      })
+      const { getByTestId } = render(el as React.ReactElement)
+
+      expect(getByTestId('lead-magnet')).toHaveTextContent('DND:new-players')
+      expect(mockEvaluate).toHaveBeenCalledWith(source, expect.any(Object))
+    })
+
+    it('merges registered custom components with the relative image override', async () => {
+      type LeadMagnetCTAProps = Readonly<{ label: string }>
+      const LeadMagnetCTA = ({ label }: LeadMagnetCTAProps) =>
+        React.createElement('div', { 'data-testid': 'lead-magnet' }, label)
+
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const CustomCTA = components?.LeadMagnetCTA as React.ComponentType<LeadMagnetCTAProps>
+          const Img = components?.img as React.ComponentType<
+            React.ImgHTMLAttributes<HTMLImageElement>
+          >
+          return React.createElement(
+            'div',
+            null,
+            React.createElement(CustomCTA, { label: 'Download now' }),
+            React.createElement(Img, { src: 'photo.png', alt: 'Article image' })
+          )
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource(
+        '<LeadMagnetCTA label="Download now" />\n\n![Article image](photo.png)',
+        '/articles/my-article',
+        {
+          siteUrl: 'https://example.com',
+          siteName: 'Example',
+          mdxComponents: { LeadMagnetCTA },
+        }
+      )
+      const { container, getByTestId } = render(el as React.ReactElement)
+
+      expect(getByTestId('lead-magnet')).toHaveTextContent('Download now')
+      expect(container.querySelector('img')?.getAttribute('src')).toBe(
+        '/articles/my-article/photo.png'
+      )
+    })
+  })
 })

package/src/__tests__/seoUtils-authors.test.ts

@@ -0,0 +1,160 @@
+import {
+  buildArticleBreadcrumbs,
+  buildAuthorBreadcrumbs,
+  buildCategoryBreadcrumbs,
+  generateAuthorMetadata,
+  generateAuthorStaticParams,
+} from '../seoUtils'
+
+jest.mock('react', () => ({ cache: (fn: Function) => fn }))
+jest.mock('../markdown', () => ({
+  markdownToHtml: jest.fn(async () => '<p>content</p>'),
+  extractToc: jest.fn(async () => []),
+}))
+
+const config = {
+  siteUrl: 'https://example.com',
+  siteName: 'Example',
+  authors: {
+    'andrew-blase': {
+      name: 'Andrew Blase',
+      slug: 'andrew-blase',
+      bio: 'Writer.',
+      social: { website: 'https://fullstackdatasolutions.com' },
+    },
+  },
+}
+
+describe('breadcrumb builders', () => {
+  it('builds article breadcrumbs with a primary category', () => {
+    expect(
+      buildArticleBreadcrumbs(
+        { slug: 'guides/test-article', title: 'Test Article', category: 'Civic Tech' },
+        config
+      )
+    ).toEqual([
+      { name: 'Home', url: 'https://example.com' },
+      { name: 'Articles', url: 'https://example.com/articles' },
+      { name: 'Civic Tech', url: 'https://example.com/articles/category/civic-tech' },
+      { name: 'Test Article' },
+    ])
+  })
+
+  it('builds configured article breadcrumbs from category, folder path, and title', () => {
+    expect(
+      buildArticleBreadcrumbs(
+        { slug: 'guides/field/test-article', title: 'Test Article', category: 'Civic Tech' },
+        {
+          ...config,
+          breadcrumbs: {
+            article: ['primaryCategory', 'folderPath', 'articleTitle'],
+          },
+        }
+      )
+    ).toEqual([
+      { name: 'Civic Tech', url: 'https://example.com/articles/category/civic-tech' },
+      { name: 'Guides', url: 'https://example.com/articles/guides' },
+      { name: 'Field', url: 'https://example.com/articles/guides/field' },
+      { name: 'Test Article' },
+    ])
+  })
+
+  it('supports custom URL entries anywhere in article breadcrumbs', () => {
+    expect(
+      buildArticleBreadcrumbs(
+        { slug: 'guides/test-article', title: 'Test Article', category: 'Civic Tech' },
+        {
+          ...config,
+          breadcrumbs: {
+            article: [
+              { name: 'Resources', url: '/resources' },
+              'primaryCategory',
+              { name: 'External Docs', url: 'https://docs.example.com' },
+              'articleTitle',
+            ],
+          },
+        }
+      )
+    ).toEqual([
+      { name: 'Resources', url: 'https://example.com/resources' },
+      { name: 'Civic Tech', url: 'https://example.com/articles/category/civic-tech' },
+      { name: 'External Docs', url: 'https://docs.example.com' },
+      { name: 'Test Article' },
+    ])
+  })
+
+  it('returns no breadcrumbs when breadcrumbs are disabled', () => {
+    expect(
+      buildArticleBreadcrumbs(
+        { slug: 'test-article', title: 'Test Article', category: 'Civic Tech' },
+        { ...config, breadcrumbs: false }
+      )
+    ).toEqual([])
+  })
+
+  it('builds category and author breadcrumbs', () => {
+    expect(buildCategoryBreadcrumbs('civic-tech', config)).toEqual([
+      { name: 'Home', url: 'https://example.com' },
+      { name: 'Articles', url: 'https://example.com/articles' },
+      { name: 'Civic Tech' },
+    ])
+    expect(buildAuthorBreadcrumbs(config.authors['andrew-blase'], config)).toEqual([
+      { name: 'Home', url: 'https://example.com' },
+      { name: 'Articles', url: 'https://example.com/articles' },
+      { name: 'Authors', url: 'https://example.com/articles/authors' },
+      { name: 'Andrew Blase' },
+    ])
+  })
+
+  it('supports custom URL entries in category and author breadcrumbs', () => {
+    expect(
+      buildCategoryBreadcrumbs('civic-tech', {
+        ...config,
+        breadcrumbs: {
+          category: ['home', { name: 'Knowledge Base', url: '/knowledge' }, 'category'],
+        },
+      })
+    ).toEqual([
+      { name: 'Home', url: 'https://example.com' },
+      { name: 'Knowledge Base', url: 'https://example.com/knowledge' },
+      { name: 'Civic Tech' },
+    ])
+
+    expect(
+      buildAuthorBreadcrumbs(config.authors['andrew-blase'], {
+        ...config,
+        breadcrumbs: {
+          author: [
+            { name: 'Team', url: '/team' },
+            { name: 'Editorial', url: 'https://example.org/editorial' },
+            'authorName',
+          ],
+        },
+      })
+    ).toEqual([
+      { name: 'Team', url: 'https://example.com/team' },
+      { name: 'Editorial', url: 'https://example.org/editorial' },
+      { name: 'Andrew Blase' },
+    ])
+  })
+})
+
+describe('author metadata utilities', () => {
+  it('generates author static params from configured authors', () => {
+    expect(generateAuthorStaticParams(config)).toEqual([{ author: 'andrew-blase' }])
+  })
+
+  it('returns no author static params when author pages are disabled', () => {
+    expect(generateAuthorStaticParams({ ...config, showAuthorPage: false })).toEqual([])
+  })
+
+  it('generates author metadata', async () => {
+    await expect(generateAuthorMetadata('andrew-blase', config)).resolves.toMatchObject({
+      title: 'Andrew Blase Articles | Example',
+      description: 'Writer.',
+      alternates: {
+        canonical: 'https://example.com/articles/authors/andrew-blase',
+      },
+    })
+  })
+})

package/src/__tests__/seoUtils.test.ts

@@ -15,6 +15,10 @@ jest.mock('../server-articles', () => ({
     { name: 'Campaigns', slug: 'campaigns', count: 2, featuredImage: '/campaigns.jpg' },
     { name: 'Volunteers', slug: 'volunteers', count: 1, featuredImage: '/volunteers.jpg' },
   ]),
+  getAllAuthors: jest.fn(() => []),
+  getArticleAuthors: jest.fn((article: { author?: string }) =>
+    article.author ? [{ name: article.author, slug: article.author, bio: '' }] : []
+  ),
   getArticleMetadata: jest.fn(async (slug: string) => {
     if (slug === 'article-one') {
       return {