@fullstackdatasolutions/articles 0.1.0

package/src/__tests__/ArticleCategoryGrid.test.tsx

@@ -0,0 +1,98 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import type { CategoryInfo } from '../articleTypes'
+import { ArticleCategoryGrid } from '../ArticleCategoryGrid'
+
+jest.mock('next/link', () => ({
+  __esModule: true,
+  default: ({ href, children }: { href: string; children: React.ReactNode }) => (
+    <a href={href}>{children}</a>
+  ),
+}))
+
+jest.mock('next/image', () => ({
+  __esModule: true,
+  default: (props: React.ComponentProps<'img'>) => <img alt="test" {...props} />,
+}))
+
+const mockCategories: CategoryInfo[] = [
+  {
+    name: 'Campaigns',
+    slug: 'campaigns',
+    count: 5,
+    featuredImage: '/articles/campaign-article/image.jpg',
+  },
+  {
+    name: 'Volunteer Management',
+    slug: 'volunteer-management',
+    count: 3,
+    featuredImage: '/articles/volunteer-article/image.jpg',
+  },
+  {
+    name: 'Technology',
+    slug: 'technology',
+    count: 1,
+    featuredImage: '/articles/tech-article/image.jpg',
+  },
+]
+
+describe('ArticleCategoryGrid', () => {
+  it('renders nothing when categories is empty', () => {
+    const { container } = render(<ArticleCategoryGrid categories={[]} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('renders the Browse by Category heading', () => {
+    render(<ArticleCategoryGrid categories={mockCategories} />)
+    expect(screen.getByText('Browse by Category')).toBeInTheDocument()
+  })
+
+  it('renders a card for each category', () => {
+    render(<ArticleCategoryGrid categories={mockCategories} />)
+    expect(screen.getByText('Campaigns')).toBeInTheDocument()
+    expect(screen.getByText('Volunteer Management')).toBeInTheDocument()
+    expect(screen.getByText('Technology')).toBeInTheDocument()
+  })
+
+  it('links each category to the correct category page', () => {
+    render(<ArticleCategoryGrid categories={mockCategories} />)
+
+    const campaignLink = screen.getByRole('link', { name: /Campaigns/i })
+    expect(campaignLink).toHaveAttribute('href', '/articles/category/campaigns')
+
+    const volunteerLink = screen.getByRole('link', {
+      name: /Volunteer Management/i,
+    })
+    expect(volunteerLink).toHaveAttribute('href', '/articles/category/volunteer-management')
+  })
+
+  it('renders the article image for each category', () => {
+    render(<ArticleCategoryGrid categories={mockCategories} />)
+    const images = screen.getAllByRole('img')
+    expect(images).toHaveLength(3)
+    expect(images[0]).toHaveAttribute('alt', 'Campaigns')
+    expect(images[1]).toHaveAttribute('alt', 'Volunteer Management')
+  })
+
+  const countCases: Array<{ count: number; label: string }> = [
+    { count: 1, label: '1 article' },
+    { count: 5, label: '5 articles' },
+    { count: 3, label: '3 articles' },
+  ]
+
+  countCases.forEach(({ count, label }) => {
+    it(`renders "${label}" for count ${count}`, () => {
+      const cat: CategoryInfo = {
+        name: 'Test',
+        slug: 'test',
+        count,
+        featuredImage: '/image.jpg',
+      }
+      render(<ArticleCategoryGrid categories={[cat]} />)
+      expect(screen.getByText(label)).toBeInTheDocument()
+    })
+  })
+})

package/src/__tests__/ArticleSchemas.test.tsx

@@ -0,0 +1,130 @@
+import { render } from '@testing-library/react'
+import { Article } from '../articleTypes'
+import { ArticleSchema, BreadcrumbSchema, CollectionPageSchema } from '../ArticleSchemas'
+
+const mockArticle: Article = {
+  slug: 'test-article',
+  title: 'Test Article',
+  excerpt: 'A test excerpt.',
+  date: '2025-03-01',
+  author: 'Jane Doe',
+  category: 'Campaigns',
+  categories: ['Campaigns'],
+  readTime: '3 min read',
+  featuredImage: '/articles/test/image.jpg',
+  tags: ['campaigns', 'testing'],
+}
+
+function parseSchemaScript(container: HTMLElement) {
+  const script = container.querySelector('script[type="application/ld+json"]')
+  expect(script).not.toBeNull()
+  return JSON.parse(script!.innerHTML)
+}
+
+describe('ArticleSchema', () => {
+  it('renders a ld+json script tag', () => {
+    const { container } = render(
+      <ArticleSchema
+        article={mockArticle}
+        articleUrl="https://example.com/articles/test-article"
+        siteName="Example Site"
+      />
+    )
+    expect(container.querySelector('script[type="application/ld+json"]')).not.toBeNull()
+  })
+
+  it('outputs schema.org/Article type with correct fields', () => {
+    const { container } = render(
+      <ArticleSchema
+        article={mockArticle}
+        articleUrl="https://example.com/articles/test-article"
+        siteName="Example Site"
+      />
+    )
+    const schema = parseSchemaScript(container)
+    expect(schema['@type']).toBe('Article')
+    expect(schema.headline).toBe('Test Article')
+    expect(schema.description).toBe('A test excerpt.')
+    expect(schema.author.name).toBe('Jane Doe')
+    expect(schema.publisher.name).toBe('Example Site')
+    expect(schema.mainEntityOfPage['@id']).toBe('https://example.com/articles/test-article')
+  })
+
+  it('includes ISO datePublished when article has a date', () => {
+    const { container } = render(
+      <ArticleSchema
+        article={mockArticle}
+        articleUrl="https://example.com/articles/test-article"
+        siteName="Example Site"
+      />
+    )
+    const schema = parseSchemaScript(container)
+    expect(schema.datePublished).toBe(new Date('2025-03-01').toISOString())
+  })
+
+  it('omits datePublished when article has no date', () => {
+    const { container } = render(
+      <ArticleSchema
+        article={{ ...mockArticle, date: undefined }}
+        articleUrl="https://example.com/articles/test-article"
+        siteName="Example Site"
+      />
+    )
+    const schema = parseSchemaScript(container)
+    expect(schema.datePublished).toBeUndefined()
+  })
+})
+
+describe('BreadcrumbSchema', () => {
+  const items = [
+    { name: 'Home', url: 'https://example.com' },
+    { name: 'Articles', url: 'https://example.com/articles' },
+    { name: 'Test Article', url: 'https://example.com/articles/test-article' },
+  ]
+
+  it('renders a ld+json script tag', () => {
+    const { container } = render(<BreadcrumbSchema items={items} />)
+    expect(container.querySelector('script[type="application/ld+json"]')).not.toBeNull()
+  })
+
+  it('outputs schema.org/BreadcrumbList with correct positions', () => {
+    const { container } = render(<BreadcrumbSchema items={items} />)
+    const schema = parseSchemaScript(container)
+    expect(schema['@type']).toBe('BreadcrumbList')
+    expect(schema.itemListElement).toHaveLength(3)
+    expect(schema.itemListElement[0].position).toBe(1)
+    expect(schema.itemListElement[0].name).toBe('Home')
+    expect(schema.itemListElement[2].position).toBe(3)
+    expect(schema.itemListElement[2].name).toBe('Test Article')
+  })
+})
+
+describe('CollectionPageSchema', () => {
+  it('renders a ld+json script tag', () => {
+    const { container } = render(
+      <CollectionPageSchema
+        title="Articles | Example"
+        description="All articles."
+        url="https://example.com/articles"
+        articleCount={42}
+      />
+    )
+    expect(container.querySelector('script[type="application/ld+json"]')).not.toBeNull()
+  })
+
+  it('outputs schema.org/CollectionPage with correct fields', () => {
+    const { container } = render(
+      <CollectionPageSchema
+        title="Articles | Example"
+        description="All articles."
+        url="https://example.com/articles"
+        articleCount={42}
+      />
+    )
+    const schema = parseSchemaScript(container)
+    expect(schema['@type']).toBe('CollectionPage')
+    expect(schema.name).toBe('Articles | Example')
+    expect(schema.numberOfItems).toBe(42)
+    expect(schema.url).toBe('https://example.com/articles')
+  })
+})

package/src/__tests__/ArticleSearchBar.test.tsx

@@ -0,0 +1,79 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from 'react'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { ArticleSearchBar } from '../ArticleSearchBar'
+
+describe('ArticleSearchBar', () => {
+  it('renders the search input', () => {
+    render(<ArticleSearchBar value="" onChange={jest.fn()} />)
+    expect(
+      screen.getByPlaceholderText('Search articles (3+ characters required)...')
+    ).toBeInTheDocument()
+  })
+
+  it('calls onChange with the typed value', () => {
+    const onChange = jest.fn()
+    render(<ArticleSearchBar value="" onChange={onChange} />)
+    fireEvent.change(screen.getByPlaceholderText('Search articles (3+ characters required)...'), {
+      target: { value: 'hello' },
+    })
+    expect(onChange).toHaveBeenCalledWith('hello')
+  })
+
+  it('shows the clear button when value is non-empty', () => {
+    render(<ArticleSearchBar value="test" onChange={jest.fn()} />)
+    expect(screen.getByRole('button', { name: 'Clear search' })).toBeInTheDocument()
+  })
+
+  it('hides the clear button when value is empty', () => {
+    render(<ArticleSearchBar value="" onChange={jest.fn()} />)
+    expect(screen.queryByRole('button', { name: 'Clear search' })).not.toBeInTheDocument()
+  })
+
+  it('calls onChange with empty string when clear button is clicked', () => {
+    const onChange = jest.fn()
+    render(<ArticleSearchBar value="test" onChange={onChange} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Clear search' }))
+    expect(onChange).toHaveBeenCalledWith('')
+  })
+
+  it('disables the input when disabled prop is true', () => {
+    render(<ArticleSearchBar value="" onChange={jest.fn()} disabled />)
+    expect(
+      screen.getByPlaceholderText('Search articles (3+ characters required)...')
+    ).toBeDisabled()
+  })
+
+  const resultCountCases = [
+    {
+      resultCount: 0,
+      value: 'xyz',
+      expected: 'No articles found matching your search.',
+    },
+    {
+      resultCount: 1,
+      value: 'test',
+      expected: 'Found 1 article matching "test"',
+    },
+    {
+      resultCount: 4,
+      value: 'camp',
+      expected: 'Found 4 articles matching "camp"',
+    },
+  ]
+
+  resultCountCases.forEach(({ resultCount, value, expected }) => {
+    it(`shows "${expected}" for resultCount ${resultCount}`, () => {
+      render(<ArticleSearchBar value={value} onChange={jest.fn()} resultCount={resultCount} />)
+      expect(screen.getByText(expected)).toBeInTheDocument()
+    })
+  })
+
+  it('does not show result count line when value is empty', () => {
+    render(<ArticleSearchBar value="" onChange={jest.fn()} resultCount={5} />)
+    expect(screen.queryByText(/Found/)).not.toBeInTheDocument()
+    expect(screen.queryByText(/No articles/)).not.toBeInTheDocument()
+  })
+})

package/src/__tests__/ArticlesHero.test.tsx

@@ -0,0 +1,38 @@
+import React from 'react'
+import { ArticlesHero } from '../ArticlesHero'
+import { render, screen } from '@testing-library/react'
+
+jest.mock('next/link', () => ({
+  __esModule: true,
+  default: ({ href, children }: { href: string; children: React.ReactNode }) => (
+    <a href={href}>{children}</a>
+  ),
+}))
+
+describe('ArticlesHero', () => {
+  it('renders the page heading', () => {
+    render(<ArticlesHero />)
+    expect(screen.getByRole('heading', { name: 'Vox Populus Insights' })).toBeInTheDocument()
+  })
+
+  it('renders the tagline text', () => {
+    render(<ArticlesHero />)
+    expect(screen.getByText(/expert analysis, campaign strategies/i)).toBeInTheDocument()
+  })
+
+  it('renders a link to the latest articles anchor', () => {
+    render(<ArticlesHero />)
+    expect(screen.getByRole('link', { name: 'Browse Latest Articles' })).toHaveAttribute(
+      'href',
+      '#latest'
+    )
+  })
+
+  it('renders a link to the contact page', () => {
+    render(<ArticlesHero />)
+    expect(screen.getByRole('link', { name: 'Contact Our Team' })).toHaveAttribute(
+      'href',
+      '/contact'
+    )
+  })
+})

package/src/__tests__/ArticlesPage.test.tsx

@@ -0,0 +1,155 @@
+import React from 'react'
+import { ArticlesPage } from '../ArticlesPage'
+import type { ArticlesConfig } from '../articlesConfig'
+import { render, screen, waitFor } from '@testing-library/react'
+
+jest.mock('next/link', () => ({
+  __esModule: true,
+  default: ({ href, children }: { href: string; children: React.ReactNode }) => (
+    <a href={href}>{children}</a>
+  ),
+}))
+
+jest.mock('next/image', () => ({
+  __esModule: true,
+  default: (props: React.ComponentProps<'img'>) => {
+    const { alt = '', ...rest } = props
+    return <img alt={alt} {...rest} />
+  },
+}))
+
+const mockArticles = [
+  {
+    slug: 'article-1',
+    title: 'Featured Article',
+    excerpt: 'Featured excerpt',
+    date: '2025-01-02',
+    author: 'Author',
+    category: 'Campaigns',
+    categories: ['Campaigns'],
+    readTime: '3 min read',
+    featuredImage: '/articles/article-1/image.jpg',
+  },
+  {
+    slug: 'article-2',
+    title: 'Second Article',
+    excerpt: 'Second excerpt',
+    date: '2025-01-01',
+    author: 'Author',
+    category: 'Volunteers',
+    categories: ['Volunteers'],
+    readTime: '2 min read',
+    featuredImage: '/articles/article-2/image.jpg',
+  },
+]
+
+const baseConfig: ArticlesConfig = {
+  siteUrl: 'https://example.com',
+  siteName: 'Test Site',
+  pageSize: 6,
+}
+
+function mockFetchSuccess() {
+  ;(globalThis.fetch as jest.Mock).mockResolvedValue({
+    ok: true,
+    json: async () => ({ articles: mockArticles }),
+  })
+}
+
+describe('ArticlesPage', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    globalThis.fetch = jest.fn()
+  })
+
+  it('shows loading state in the latest section while hero renders immediately', () => {
+    ;(globalThis.fetch as jest.Mock).mockReturnValue(new Promise(() => {}))
+    render(<ArticlesPage config={{ ...baseConfig, layout: ['hero', 'latest'] }} />)
+    // Hero is static — visible before any fetch completes
+    expect(screen.getByText('Vox Populus Insights')).toBeInTheDocument()
+    // Latest section shows a spinner while articles load
+    expect(screen.getByText('Loading articles...')).toBeInTheDocument()
+  })
+
+  it('renders all default layout sections after load', async () => {
+    mockFetchSuccess()
+    render(<ArticlesPage config={baseConfig} />)
+
+    // Static sections render immediately — no need to wait
+    expect(screen.getByText('Vox Populus Insights')).toBeInTheDocument()
+
+    // Article sections appear after fetch resolves
+    await waitFor(() => expect(screen.getByText('FEATURED ARTICLE')).toBeInTheDocument())
+    expect(screen.getByText('Latest Articles')).toBeInTheDocument()
+  })
+
+  it('respects a custom layout order — omits sections not in the array', async () => {
+    mockFetchSuccess()
+    const config: ArticlesConfig = {
+      ...baseConfig,
+      layout: ['search', 'latest'],
+    }
+    render(<ArticlesPage config={config} />)
+
+    await waitFor(() => expect(screen.getByText('Latest Articles')).toBeInTheDocument())
+
+    // hero not in layout
+    expect(screen.queryByText('Vox Populus Insights')).not.toBeInTheDocument()
+    // newsletter not in layout
+    expect(screen.queryByTestId('newsletter')).not.toBeInTheDocument()
+    // search is in layout
+    expect(
+      screen.getByPlaceholderText('Search articles (3+ characters required)...')
+    ).toBeInTheDocument()
+  })
+
+  it('applies theme values as CSS custom properties', async () => {
+    mockFetchSuccess()
+    const config: ArticlesConfig = {
+      ...baseConfig,
+      layout: ['latest'],
+      theme: { headerColor: '#ff0000', linkColor: '#00ff00' },
+    }
+    const { container } = render(<ArticlesPage config={config} />)
+
+    await waitFor(() => expect(screen.getByText('Latest Articles')).toBeInTheDocument())
+
+    const wrapper = container.firstChild as HTMLElement
+    expect(wrapper.style.getPropertyValue('--articles-header-color')).toBe('#ff0000')
+    expect(wrapper.style.getPropertyValue('--articles-link-color')).toBe('#00ff00')
+  })
+
+  it('shows inline error in the latest section when fetch fails', async () => {
+    ;(globalThis.fetch as jest.Mock).mockResolvedValue({ ok: false })
+    render(<ArticlesPage config={{ ...baseConfig, layout: ['latest'] }} />)
+
+    await waitFor(() => expect(screen.getByText('Error Loading Articles')).toBeInTheDocument())
+    expect(screen.getByRole('button', { name: 'Try again' })).toBeInTheDocument()
+  })
+
+  it('uses pageSize from config', async () => {
+    const manyArticles = Array.from({ length: 10 }, (_, i) => ({
+      ...mockArticles[0],
+      slug: `article-${i + 1}`,
+      title: `Article ${i + 1}`,
+    }))
+    ;(globalThis.fetch as jest.Mock).mockResolvedValue({
+      ok: true,
+      json: async () => ({ articles: manyArticles }),
+    })
+
+    const config: ArticlesConfig = {
+      ...baseConfig,
+      pageSize: 3,
+      layout: ['latest'],
+    }
+    render(<ArticlesPage config={config} />)
+
+    // 'featured' is not in the layout so no slice — articles 1-3 visible
+    await waitFor(() => expect(screen.getByText('Article 1')).toBeInTheDocument())
+    expect(screen.getByText('Article 2')).toBeInTheDocument()
+    expect(screen.getByText('Article 3')).toBeInTheDocument()
+    expect(screen.queryByText('Article 4')).not.toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Load more articles' })).toBeInTheDocument()
+  })
+})

package/src/__tests__/CategoryArticlesPage.test.tsx

@@ -0,0 +1,156 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import type { Article } from '../articleTypes'
+import { CategoryArticlesPage } from '../CategoryArticlesPage'
+import type { ArticlesConfig } from '../articlesConfig'
+
+jest.mock('next/link', () => ({
+  __esModule: true,
+  default: ({
+    href,
+    children,
+    ...rest
+  }: {
+    href: string
+    children: React.ReactNode
+    [key: string]: unknown
+  }) => (
+    <a href={href} {...rest}>
+      {children}
+    </a>
+  ),
+}))
+
+jest.mock('next/image', () => ({
+  __esModule: true,
+  default: (props: React.ComponentProps<'img'>) => <img {...props} alt={props.alt ?? ''} />,
+}))
+
+jest.mock('../LatestArticles', () => ({
+  LatestArticles: ({ articles }: { articles: Article[] }) => (
+    <div data-testid="latest-articles">
+      {articles.map((a) => (
+        <div key={a.slug} data-testid="article-card">
+          {a.title}
+        </div>
+      ))}
+    </div>
+  ),
+}))
+
+jest.mock('../ArticleSchemas', () => ({
+  BreadcrumbSchema: () => null,
+}))
+
+const baseConfig: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Test Site' }
+
+const makeArticle = (overrides: Partial<Article> = {}): Article => ({
+  slug: 'test-article',
+  title: 'Test Article',
+  excerpt: 'An excerpt.',
+  author: 'Author',
+  category: 'Campaigns',
+  categories: ['Campaigns'],
+  readTime: '3 min read',
+  featuredImage: '/articles/test-article/hero.jpg',
+  tags: [],
+  ...overrides,
+})
+
+describe('CategoryArticlesPage', () => {
+  it('renders nothing when articles array is empty', () => {
+    const { container } = render(
+      <CategoryArticlesPage category="campaigns" articles={[]} config={baseConfig} />
+    )
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('renders the category name in the hero', () => {
+    render(
+      <CategoryArticlesPage
+        category="campaigns"
+        articles={[makeArticle({ category: 'Campaigns' })]}
+        config={baseConfig}
+      />
+    )
+    expect(screen.getByText('Campaigns')).toBeInTheDocument()
+  })
+
+  it('renders plural article count in the hero', () => {
+    render(
+      <CategoryArticlesPage
+        category="campaigns"
+        articles={[makeArticle({ slug: 'a1' }), makeArticle({ slug: 'a2' })]}
+        config={baseConfig}
+      />
+    )
+    expect(screen.getByText('2 articles')).toBeInTheDocument()
+  })
+
+  it("uses singular 'article' when count is 1", () => {
+    render(
+      <CategoryArticlesPage category="campaigns" articles={[makeArticle()]} config={baseConfig} />
+    )
+    expect(screen.getByText('1 article')).toBeInTheDocument()
+  })
+
+  it('renders an article card for each article via LatestArticles', () => {
+    render(
+      <CategoryArticlesPage
+        category="campaigns"
+        articles={[
+          makeArticle({ slug: 'a1', title: 'Article One' }),
+          makeArticle({ slug: 'a2', title: 'Article Two' }),
+          makeArticle({ slug: 'a3', title: 'Article Three' }),
+        ]}
+        config={baseConfig}
+      />
+    )
+    expect(screen.getAllByTestId('article-card')).toHaveLength(3)
+    expect(screen.getByText('Article One')).toBeInTheDocument()
+    expect(screen.getByText('Article Three')).toBeInTheDocument()
+  })
+
+  it('renders the back link to /articles', () => {
+    render(
+      <CategoryArticlesPage category="campaigns" articles={[makeArticle()]} config={baseConfig} />
+    )
+    expect(screen.getByRole('link', { name: /All Articles/i })).toHaveAttribute('href', '/articles')
+  })
+
+  it('renders the hero image from the first article', () => {
+    render(
+      <CategoryArticlesPage
+        category="campaigns"
+        articles={[makeArticle({ featuredImage: '/articles/hero.jpg', category: 'Campaigns' })]}
+        config={baseConfig}
+      />
+    )
+    expect(screen.getByAltText('Campaigns')).toHaveAttribute('src', '/articles/hero.jpg')
+  })
+
+  it('shows the long description from config when provided', () => {
+    const config: ArticlesConfig = {
+      ...baseConfig,
+      categoryDescriptions: {
+        campaigns: { short: 'Short desc', long: 'A longer category description' },
+      },
+    }
+    render(<CategoryArticlesPage category="campaigns" articles={[makeArticle()]} config={config} />)
+    expect(screen.getByText('A longer category description')).toBeInTheDocument()
+  })
+
+  it('falls back to a generated short description when no config description is provided', () => {
+    render(
+      <CategoryArticlesPage
+        category="campaigns"
+        articles={[makeArticle({ category: 'Campaigns' })]}
+        config={baseConfig}
+      />
+    )
+    expect(screen.getByText('Browse all articles in Campaigns.')).toBeInTheDocument()
+  })
+})