@fullstackdatasolutions/articles 0.1.0

package/src/__tests__/LatestArticlesSection.test.tsx

@@ -0,0 +1,105 @@
+import React from 'react'
+import { LatestArticlesSection } from '../LatestArticlesSection'
+import type { Article } from '../articleTypes'
+import { render, screen, fireEvent } 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} />
+  },
+}))
+
+function makeArticle(n: number): Article {
+  return {
+    slug: `article-${n}`,
+    title: `Article ${n}`,
+    excerpt: `Excerpt ${n}`,
+    date: '2025-01-01',
+    author: 'Author',
+    category: 'Test',
+    categories: ['Test'],
+    readTime: '3 min read',
+    featuredImage: `/articles/article-${n}/image.jpg`,
+  }
+}
+
+const noOp = jest.fn()
+
+describe('LatestArticlesSection', () => {
+  beforeEach(() => jest.clearAllMocks())
+
+  it('shows "Latest Articles" heading when there is no search query', () => {
+    render(
+      <LatestArticlesSection articles={[makeArticle(1)]} searchQuery="" onClearSearch={noOp} />
+    )
+    expect(screen.getByRole('heading', { name: 'Latest Articles' })).toBeInTheDocument()
+  })
+
+  it('shows "Search Results" heading when a search query is active', () => {
+    render(
+      <LatestArticlesSection articles={[makeArticle(1)]} searchQuery="voter" onClearSearch={noOp} />
+    )
+    expect(screen.getByRole('heading', { name: 'Search Results' })).toBeInTheDocument()
+  })
+
+  it('shows the general description text when not searching', () => {
+    render(
+      <LatestArticlesSection articles={[makeArticle(1)]} searchQuery="" onClearSearch={noOp} />
+    )
+    expect(screen.getByText(/stay informed/i)).toBeInTheDocument()
+  })
+
+  it('shows the article count in the description when searching', () => {
+    const articles = [makeArticle(1), makeArticle(2)]
+    render(<LatestArticlesSection articles={articles} searchQuery="voter" onClearSearch={noOp} />)
+    expect(screen.getByText('Found 2 articles matching your search.')).toBeInTheDocument()
+  })
+
+  it('uses singular "article" when count is 1', () => {
+    render(
+      <LatestArticlesSection articles={[makeArticle(1)]} searchQuery="voter" onClearSearch={noOp} />
+    )
+    expect(screen.getByText('Found 1 article matching your search.')).toBeInTheDocument()
+  })
+
+  it('renders article cards when articles are present', () => {
+    render(
+      <LatestArticlesSection
+        articles={[makeArticle(1), makeArticle(2)]}
+        searchQuery=""
+        onClearSearch={noOp}
+      />
+    )
+    expect(screen.getByText('Article 1')).toBeInTheDocument()
+    expect(screen.getByText('Article 2')).toBeInTheDocument()
+  })
+
+  it('shows the empty state when searching returns no results', () => {
+    render(<LatestArticlesSection articles={[]} searchQuery="xyzzy" onClearSearch={noOp} />)
+    expect(screen.getByText('No articles found')).toBeInTheDocument()
+    expect(screen.getByText(/xyzzy/)).toBeInTheDocument()
+  })
+
+  it('does not show the empty state when not searching and articles is empty', () => {
+    render(<LatestArticlesSection articles={[]} searchQuery="" onClearSearch={noOp} />)
+    expect(screen.queryByText('No articles found')).not.toBeInTheDocument()
+  })
+
+  it('calls onClearSearch when the Clear search button is clicked', () => {
+    const onClearSearch = jest.fn()
+    render(
+      <LatestArticlesSection articles={[]} searchQuery="xyzzy" onClearSearch={onClearSearch} />
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Clear search' }))
+    expect(onClearSearch).toHaveBeenCalledTimes(1)
+  })
+})

package/src/__tests__/jest-dom.d.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom'

package/src/__tests__/seoUtils.test.ts

@@ -0,0 +1,217 @@
+import { ArticlesConfig } from '../articlesConfig'
+import {
+  generateArticleStaticParams,
+  generateCategoryStaticParams,
+  generateArticleMetadata,
+  generateCategoryMetadata,
+  getArticleSitemapEntries,
+} from '../seoUtils'
+
+jest.mock('../server-articles', () => ({
+  getAvailableArticleSlugs: jest.fn(() => ['article-one', 'article-two']),
+  getAllCategories: jest.fn(async () => [
+    { name: 'Campaigns', slug: 'campaigns', count: 2, featuredImage: '/campaigns.jpg' },
+    { name: 'Volunteers', slug: 'volunteers', count: 1, featuredImage: '/volunteers.jpg' },
+  ]),
+  getArticleMetadata: jest.fn(async (slug: string) => {
+    if (slug === 'article-one') {
+      return {
+        slug: 'article-one',
+        title: 'Article One',
+        excerpt: 'Excerpt for article one.',
+        date: '2025-01-15',
+        author: 'Jane Doe',
+        category: 'Campaigns',
+        categories: ['Campaigns'],
+        readTime: '3 min read',
+        featuredImage: '/articles/article-one/image.jpg',
+        tags: ['campaigns', 'strategy'],
+        htmlContent: '<p>content</p>',
+      }
+    }
+    return null
+  }),
+  getArticlesByCategory: jest.fn(async (slug: string) => {
+    if (slug === 'campaigns') {
+      return [
+        {
+          slug: 'article-one',
+          title: 'Article One',
+          excerpt: 'Excerpt.',
+          date: '2025-01-15',
+          author: 'Jane Doe',
+          category: 'Campaigns',
+          categories: ['Campaigns'],
+          readTime: '3 min read',
+          featuredImage: '/articles/article-one/image.jpg',
+        },
+        {
+          slug: 'article-two',
+          title: 'Article Two',
+          excerpt: 'Excerpt two.',
+          date: '2025-01-16',
+          author: 'John Smith',
+          category: 'Campaigns',
+          categories: ['Campaigns'],
+          readTime: '4 min read',
+          featuredImage: '/articles/article-two/image.jpg',
+        },
+      ]
+    }
+    return []
+  }),
+  getAllArticles: jest.fn(async () => [
+    {
+      slug: 'article-one',
+      date: '2025-01-15',
+      title: 'Article One',
+      excerpt: '',
+      author: '',
+      category: '',
+      categories: [],
+      readTime: '',
+      featuredImage: '',
+    },
+    {
+      slug: 'article-two',
+      date: '2025-01-16',
+      title: 'Article Two',
+      excerpt: '',
+      author: '',
+      category: '',
+      categories: [],
+      readTime: '',
+      featuredImage: '',
+    },
+  ]),
+}))
+
+const config: ArticlesConfig = {
+  siteUrl: 'https://example.com',
+  siteName: 'Example Site',
+}
+
+describe('generateArticleStaticParams', () => {
+  it('returns slug params from available articles', () => {
+    const result = generateArticleStaticParams()
+    expect(result).toEqual([{ slug: 'article-one' }, { slug: 'article-two' }])
+  })
+})
+
+describe('generateCategoryStaticParams', () => {
+  it('returns category slug params', async () => {
+    const result = await generateCategoryStaticParams()
+    expect(result).toEqual([{ category: 'campaigns' }, { category: 'volunteers' }])
+  })
+})
+
+describe('generateArticleMetadata', () => {
+  it('returns correct title and description using config values', async () => {
+    const meta = await generateArticleMetadata('article-one', config)
+    expect(meta.title).toBe('Article One | Example Site')
+    expect(meta.description).toBe('Excerpt for article one.')
+  })
+
+  it('includes correct canonical URL', async () => {
+    const meta = await generateArticleMetadata('article-one', config)
+    expect(meta.alternates?.canonical).toBe('https://example.com/articles/article-one')
+  })
+
+  it('builds OpenGraph with siteName from config', async () => {
+    const meta = await generateArticleMetadata('article-one', config)
+    expect((meta.openGraph as { siteName?: string })?.siteName).toBe('Example Site')
+    expect((meta.openGraph as { url?: string })?.url).toBe(
+      'https://example.com/articles/article-one'
+    )
+  })
+
+  it('resolves relative image paths using siteUrl', async () => {
+    const meta = await generateArticleMetadata('article-one', config)
+    const images = (meta.openGraph as { images?: { url: string }[] })?.images
+    expect(images?.[0].url).toBe('https://example.com/articles/article-one/image.jpg')
+  })
+
+  it('returns not-found metadata for unknown slug', async () => {
+    const meta = await generateArticleMetadata('nonexistent', config)
+    expect(meta.title).toBe('Article Not Found')
+  })
+
+  it('strips trailing slash from siteUrl before building URLs', async () => {
+    const meta = await generateArticleMetadata('article-one', {
+      ...config,
+      siteUrl: 'https://example.com/',
+    })
+    expect(meta.alternates?.canonical).toBe('https://example.com/articles/article-one')
+  })
+})
+
+describe('generateCategoryMetadata', () => {
+  it('returns correct title using category name and siteName', async () => {
+    const meta = await generateCategoryMetadata('campaigns', config)
+    expect(meta.title).toBe('Campaigns Articles | Example Site')
+  })
+
+  it('generates fallback description when no categoryDescriptions set', async () => {
+    const meta = await generateCategoryMetadata('campaigns', config)
+    expect(meta.description).toContain('2 articles')
+    expect(meta.description).toContain('Campaigns')
+  })
+
+  it('uses short description from categoryDescriptions when provided', async () => {
+    const cfg: ArticlesConfig = {
+      ...config,
+      categoryDescriptions: {
+        campaigns: { short: 'Campaign strategy articles.', long: 'A longer description.' },
+      },
+    }
+    const meta = await generateCategoryMetadata('campaigns', cfg)
+    expect(meta.description).toBe('Campaign strategy articles.')
+  })
+
+  it('includes canonical URL', async () => {
+    const meta = await generateCategoryMetadata('campaigns', config)
+    expect(meta.alternates?.canonical).toBe('https://example.com/articles/category/campaigns')
+  })
+
+  it('returns Category Not Found for empty category', async () => {
+    const meta = await generateCategoryMetadata('nonexistent', config)
+    expect(meta.title).toBe('Category Not Found')
+  })
+})
+
+describe('getArticleSitemapEntries', () => {
+  it('returns article and category entries prefixed with baseUrl', async () => {
+    const entries = await getArticleSitemapEntries('https://example.com')
+    // 2 articles + 2 categories
+    expect(entries).toHaveLength(4)
+
+    const articleUrls = entries.filter((e) => !e.url.includes('/category/')).map((e) => e.url)
+    expect(articleUrls).toEqual([
+      'https://example.com/articles/article-one',
+      'https://example.com/articles/article-two',
+    ])
+
+    const categoryUrls = entries.filter((e) => e.url.includes('/category/')).map((e) => e.url)
+    expect(categoryUrls).toEqual([
+      'https://example.com/articles/category/campaigns',
+      'https://example.com/articles/category/volunteers',
+    ])
+  })
+
+  it('sets priority 0.8 for articles and 0.7 for categories', async () => {
+    const entries = await getArticleSitemapEntries('https://example.com')
+    const articleEntry = entries.find((e) => !e.url.includes('/category/'))!
+    const categoryEntry = entries.find((e) => e.url.includes('/category/'))!
+    expect(articleEntry.priority).toBe(0.8)
+    expect(articleEntry.changeFrequency).toBe('weekly')
+    expect(categoryEntry.priority).toBe(0.7)
+    expect(categoryEntry.changeFrequency).toBe('weekly')
+  })
+
+  it('returns empty array when fetching throws', async () => {
+    const { getAllArticles } = jest.requireMock('../server-articles')
+    getAllArticles.mockRejectedValueOnce(new Error('filesystem error'))
+    const entries = await getArticleSitemapEntries('https://example.com')
+    expect(entries).toEqual([])
+  })
+})

package/src/__tests__/useArticles.test.ts

@@ -0,0 +1,207 @@
+import { useArticles } from '../useArticles'
+import { renderHook, act, waitFor } from '@testing-library/react'
+
+const mockArticles = [
+  {
+    slug: 'article-1',
+    title: 'Article 1',
+    excerpt: 'Excerpt 1',
+    date: '2025-01-01',
+    author: 'Author',
+    category: 'Campaigns',
+    categories: ['Campaigns'],
+    readTime: '3 min read',
+    featuredImage: '/articles/article-1/image.jpg',
+  },
+  {
+    slug: 'article-2',
+    title: 'Article 2',
+    excerpt: 'Excerpt 2',
+    date: '2025-01-02',
+    author: 'Author',
+    category: 'Campaigns',
+    categories: ['Campaigns'],
+    readTime: '4 min read',
+    featuredImage: '/articles/article-2/image.jpg',
+  },
+  {
+    slug: 'article-3',
+    title: 'Article 3',
+    excerpt: 'Excerpt 3',
+    date: '2025-01-03',
+    author: 'Author',
+    category: 'Volunteers',
+    categories: ['Volunteers'],
+    readTime: '2 min read',
+    featuredImage: '/articles/article-3/image.jpg',
+  },
+]
+
+describe('useArticles', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    globalThis.fetch = jest.fn()
+  })
+
+  it('starts in loading state with empty articles', () => {
+    ;(globalThis.fetch as jest.Mock).mockReturnValue(new Promise(() => {}))
+    const { result } = renderHook(() => useArticles())
+    expect(result.current.loading).toBe(true)
+    expect(result.current.articles).toEqual([])
+    expect(result.current.error).toBeNull()
+  })
+
+  it('fetches articles on mount and populates state', async () => {
+    ;(globalThis.fetch as jest.Mock).mockResolvedValue({
+      ok: true,
+      json: async () => ({ articles: mockArticles }),
+    })
+
+    const { result } = renderHook(() => useArticles())
+
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    expect(result.current.articles).toHaveLength(3)
+    expect(globalThis.fetch).toHaveBeenCalledWith('/api/articles')
+  })
+
+  it('derives categories from the fetched article list', async () => {
+    ;(globalThis.fetch as jest.Mock).mockResolvedValue({
+      ok: true,
+      json: async () => ({ articles: mockArticles }),
+    })
+
+    const { result } = renderHook(() => useArticles())
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    expect(result.current.categories).toHaveLength(2)
+    // Campaigns has 2 articles so it sorts first
+    expect(result.current.categories[0].name).toBe('Campaigns')
+    expect(result.current.categories[0].count).toBe(2)
+    expect(result.current.categories[1].name).toBe('Volunteers')
+    expect(result.current.categories[1].count).toBe(1)
+  })
+
+  it('sets error state when fetch fails', async () => {
+    ;(globalThis.fetch as jest.Mock).mockResolvedValue({ ok: false })
+
+    const { result } = renderHook(() => useArticles())
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    expect(result.current.error).toBe('Failed to fetch articles')
+    expect(result.current.articles).toEqual([])
+  })
+
+  describe('debounced search', () => {
+    beforeEach(() => jest.useFakeTimers())
+    afterEach(() => jest.useRealTimers())
+
+    it('does not fetch immediately when 3+ characters are typed', async () => {
+      ;(globalThis.fetch as jest.Mock).mockResolvedValue({
+        ok: true,
+        json: async () => ({ articles: mockArticles }),
+      })
+      const { result } = renderHook(() => useArticles())
+      // Drain the initial mount fetch with real async resolution
+      await act(async () => {
+        await Promise.resolve()
+      })
+
+      act(() => result.current.handleSearch('cam'))
+
+      // Still only the initial fetch — debounce hasn't fired yet
+      expect(globalThis.fetch).toHaveBeenCalledTimes(1)
+      expect(result.current.searchQuery).toBe('cam')
+    })
+
+    it('fetches after 1 second of inactivity', async () => {
+      ;(globalThis.fetch as jest.Mock)
+        .mockResolvedValueOnce({ ok: true, json: async () => ({ articles: mockArticles }) })
+        .mockResolvedValueOnce({ ok: true, json: async () => ({ articles: [mockArticles[0]] }) })
+      const { result } = renderHook(() => useArticles())
+      await act(async () => {
+        await Promise.resolve()
+      })
+
+      act(() => result.current.handleSearch('cam'))
+      act(() => jest.advanceTimersByTime(1000))
+
+      await waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(2))
+      expect(globalThis.fetch).toHaveBeenLastCalledWith('/api/articles?q=cam')
+    })
+
+    it('resets the timer when the user keeps typing — only one fetch fires', async () => {
+      ;(globalThis.fetch as jest.Mock).mockResolvedValue({
+        ok: true,
+        json: async () => ({ articles: mockArticles }),
+      })
+      const { result } = renderHook(() => useArticles())
+      await act(async () => {
+        await Promise.resolve()
+      })
+
+      act(() => {
+        result.current.handleSearch('cam')
+        jest.advanceTimersByTime(500)
+        result.current.handleSearch('camp')
+        jest.advanceTimersByTime(500)
+        result.current.handleSearch('campa')
+        jest.advanceTimersByTime(1000) // only this final 1s fires a fetch
+      })
+
+      await waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(2))
+      expect(globalThis.fetch).toHaveBeenLastCalledWith('/api/articles?q=campa')
+    })
+
+    it('does not fetch for 1-2 character queries even after 1 second', async () => {
+      ;(globalThis.fetch as jest.Mock).mockResolvedValue({
+        ok: true,
+        json: async () => ({ articles: mockArticles }),
+      })
+      const { result } = renderHook(() => useArticles())
+      await act(async () => {
+        await Promise.resolve()
+      })
+
+      act(() => {
+        result.current.handleSearch('ca')
+        jest.advanceTimersByTime(1000)
+      })
+
+      expect(globalThis.fetch).toHaveBeenCalledTimes(1) // only the initial mount fetch
+      expect(result.current.searchQuery).toBe('ca')
+    })
+
+    it('fetches immediately (no debounce) when query is cleared', async () => {
+      ;(globalThis.fetch as jest.Mock).mockResolvedValue({
+        ok: true,
+        json: async () => ({ articles: mockArticles }),
+      })
+      const { result } = renderHook(() => useArticles())
+      await act(async () => {
+        await Promise.resolve()
+      })
+
+      act(() => result.current.handleSearch(''))
+
+      // Second fetch fires without advancing timers
+      await waitFor(() => expect(globalThis.fetch).toHaveBeenCalledTimes(2))
+      expect(globalThis.fetch).toHaveBeenLastCalledWith('/api/articles')
+    })
+  })
+
+  it('refetches all articles when handleSearch is called with empty string', async () => {
+    ;(globalThis.fetch as jest.Mock).mockResolvedValue({
+      ok: true,
+      json: async () => ({ articles: mockArticles }),
+    })
+
+    const { result } = renderHook(() => useArticles())
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    act(() => result.current.handleSearch(''))
+    await waitFor(() => expect(result.current.loading).toBe(false))
+
+    expect(globalThis.fetch).toHaveBeenLastCalledWith('/api/articles')
+  })
+})

package/src/articleTypes.ts

@@ -0,0 +1,21 @@
+export interface Article {
+  slug: string
+  title: string
+  excerpt: string
+  date?: string
+  author: string
+  category: string
+  categories: string[]
+  readTime: string
+  featuredImage: string
+  tags?: string[]
+  content?: string
+  htmlContent?: string
+}
+
+export interface CategoryInfo {
+  name: string
+  slug: string
+  count: number
+  featuredImage: string
+}

package/src/articlesConfig.ts

@@ -0,0 +1,98 @@
+/** Keys for each renderable section of the articles listing page. */
+export type ArticlesSection =
+  | 'hero'
+  | 'search'
+  | 'featured'
+  | 'latest'
+  | 'categories'
+  | 'newsletter'
+
+/**
+ * CSS custom-property overrides applied to the library's wrapper div.
+ * All fields are optional; omitted fields fall back to the consuming app's Tailwind theme.
+ */
+export interface ArticlesTheme {
+  /** Font family for the articles section. Example: `"'Inter', sans-serif"` */
+  fontFamily?: string
+  /** Color for article card titles and section headings. Example: `'#111827'` */
+  headerColor?: string
+  /** Color for body and excerpt text. Example: `'#6b7280'` */
+  textColor?: string
+  /** Background color for sections and cards. Example: `'#ffffff'` */
+  backgroundColor?: string
+  /** Color for "Read More" links and inline links. Example: `'#4f46e5'` */
+  linkColor?: string
+  /** Hover color for links. Example: `'#4338ca'` */
+  linkHoverColor?: string
+  /** Text decoration for links. Values: `'underline'` | `'none'` */
+  linkTextDecoration?: string
+  /** Font weight for headings. Example: `700` */
+  headerFontWeight?: string | number
+  /** Font size for article card titles. Example: `'1.25rem'` */
+  headerFontSize?: string
+  /** Font size for body text. Example: `'1rem'` */
+  bodyFontSize?: string
+  /** Line height for body text. Example: `'1.75'` */
+  lineHeight?: string
+  /** Border radius for cards. Example: `'0.5rem'` */
+  borderRadius?: string
+}
+
+/** Per-category text used in meta descriptions and on the category hero page. */
+export interface CategoryDescription {
+  /** Short description — used in meta description and category grid card. */
+  short: string
+  /** Long description — rendered as a hero paragraph on the category page. */
+  long?: string
+}
+
+/** Controls the comments feature. Attach to `ArticlesConfig.comments`. */
+export interface CommentsConfig {
+  /** Set to `true` to enable comments globally across all articles. */
+  enabled: boolean
+  /** Maximum reply nesting depth. Default: `1` (replies to top-level only). */
+  maxDepth?: number
+  /**
+   * Per-article overrides keyed by slug.
+   * Example: `{ 'sensitive-article': false }` disables comments on that article only.
+   */
+  perArticleOverride?: Record<string, boolean>
+}
+
+/** Top-level configuration object. Pass one instance to every library component. */
+export interface ArticlesConfig {
+  /** Canonical base URL of the site, used in metadata and JSON-LD. Example: `'https://yoursite.com'` */
+  siteUrl: string
+  /** Site name shown in metadata titles and JSON-LD publisher fields. Example: `'Vox Populus'` */
+  siteName: string
+  /** Number of articles shown per page in the grid and loaded on each "Load more" click. Default: `6` */
+  pageSize?: number
+  /** Number of category cards shown before a "Load more categories" button appears. Default: `8` */
+  categoriesPageSize?: number
+  /**
+   * Ordered list of sections to render on the articles listing page.
+   * Omit a key to hide that section entirely. Default: `['hero','search','featured','latest','categories']`
+   */
+  layout?: ArticlesSection[]
+  /** CSS custom-property overrides for colors, fonts, and spacing. All fields optional. */
+  theme?: ArticlesTheme
+  /**
+   * Descriptive text for each category, keyed by category slug.
+   * A plain string is treated as the short description only.
+   * Example: `{ 'campaigns': { short: 'Campaign tips', long: 'Full paragraph...' } }`
+   */
+  categoryDescriptions?: Record<string, string | CategoryDescription>
+  /** Comments configuration. Omit or set `enabled: false` to hide comments entirely. */
+  comments?: CommentsConfig
+}
+
+export const DEFAULT_PAGE_SIZE = 6
+export const DEFAULT_CATEGORIES_PAGE_SIZE = 8
+
+export const DEFAULT_LAYOUT: ArticlesSection[] = [
+  'hero',
+  'search',
+  'featured',
+  'latest',
+  'categories',
+]

package/src/commentTypes.ts

@@ -0,0 +1,14 @@
+export interface ArticleComment {
+  id: string
+  articleSlug: string
+  body: string
+  isDeleted: boolean
+  createdAt: string
+  authorId: string
+  authorName: string
+  parentId: string | null
+}
+
+export interface ArticleCommentWithReplies extends ArticleComment {
+  replies: ArticleComment[]
+}