@fullstackdatasolutions/articles 0.11.0 → 1.0.0

package/src/__tests__/AuthorArticlesPage.test.tsx

@@ -1,11 +1,17 @@
-import { render, screen } from '@testing-library/react'
+import { render, screen, fireEvent } from '@testing-library/react'
 import type React from 'react'
 import { AuthorArticlesPage } from '../AuthorArticlesPage'
 
 jest.mock('next/link', () => ({
   __esModule: true,
-  default: ({ href, children }: { href: string; children: React.ReactNode }) => (
-    <a href={href}>{children}</a>
+  default: ({
+    href,
+    children,
+    ...rest
+  }: { href: string; children: React.ReactNode } & Record<string, unknown>) => (
+    <a href={href} {...rest}>
+      {children}
+    </a>
   ),
 }))
 
@@ -70,5 +76,300 @@ describe('AuthorArticlesPage', () => {
         sameAs: ['https://fullstackdatasolutions.com'],
       })
     )
+
+    const collectionPage = schemas.find((schema) => schema['@type'] === 'CollectionPage')
+    expect(collectionPage).toEqual(
+      expect.objectContaining({
+        name: 'Andrew Blase | Example',
+        url: 'https://example.com/articles/authors/andrew-blase',
+        numberOfItems: 1,
+        mainEntity: {
+          '@type': 'ItemList',
+          itemListElement: [
+            {
+              '@type': 'ListItem',
+              position: 1,
+              url: 'https://example.com/articles/test-article',
+              name: 'Test Article',
+            },
+          ],
+        },
+      })
+    )
+  })
+
+  describe('listingPagination: "pages" mode', () => {
+    const pagesConfig = { ...config, listingPagination: 'pages' as const }
+
+    it('does not render PaginationNav when config.listingPagination is unset, even with page/totalPages', () => {
+      render(
+        <AuthorArticlesPage
+          author={author}
+          articles={articles}
+          config={config}
+          page={2}
+          totalPages={4}
+        />
+      )
+      expect(screen.queryByText(/Page \d+ of \d+/)).not.toBeInTheDocument()
+    })
+
+    it('renders PaginationNav built from the author slug when config.listingPagination is "pages"', () => {
+      render(
+        <AuthorArticlesPage
+          author={author}
+          articles={articles}
+          config={pagesConfig}
+          page={2}
+          totalPages={4}
+        />
+      )
+      expect(screen.getByText('Page 2 of 4')).toBeInTheDocument()
+      expect(screen.getByRole('link', { name: /next/i })).toHaveAttribute(
+        'href',
+        '/articles/authors/andrew-blase/page/3'
+      )
+    })
+
+    it('uses totalCount for the Person interactionStatistic and CollectionPage articleCount', () => {
+      const { container } = render(
+        <AuthorArticlesPage
+          author={author}
+          articles={articles}
+          config={pagesConfig}
+          page={1}
+          totalPages={5}
+          totalCount={9}
+        />
+      )
+      const schemas = parseSchemaScript(container)
+      const person = schemas.find((schema) => schema['@type'] === 'Person')
+      const collectionPage = schemas.find((schema) => schema['@type'] === 'CollectionPage')
+      expect(person?.interactionStatistic).toEqual(
+        expect.objectContaining({ userInteractionCount: 9 })
+      )
+      expect(collectionPage?.numberOfItems).toBe(9)
+    })
+
+    it('falls back to articles.length when totalCount is omitted', () => {
+      const { container } = render(
+        <AuthorArticlesPage
+          author={author}
+          articles={articles}
+          config={pagesConfig}
+          page={1}
+          totalPages={5}
+        />
+      )
+      const schemas = parseSchemaScript(container)
+      const collectionPage = schemas.find((schema) => schema['@type'] === 'CollectionPage')
+      expect(collectionPage?.numberOfItems).toBe(1)
+    })
+  })
+
+  describe('rich AuthorProfile fields (Phase 27E)', () => {
+    const richAuthor = {
+      ...author,
+      promise: 'Helping new GMs run confident first sessions.',
+      servesWho: ['New game masters', 'Streaming DMs'],
+      originStory: [
+        { heading: 'How it started', paragraphs: ['Ran my first session in 2010.'] },
+        { paragraphs: ['Never looked back.'] },
+      ],
+      principles: ['Fun first', 'Prep less, improvise more'],
+      credentials: ['10+ years running published campaigns'],
+      proof: [
+        { claim: '500+ sessions run', source: 'Personal log' },
+        { claim: 'Featured on a podcast', url: 'https://example.com/podcast' },
+      ],
+      primaryCta: { label: 'Book a session', href: '/book' },
+    }
+
+    it('does not render any new section when sections is omitted, even with a fully populated profile', () => {
+      const { container } = render(
+        <AuthorArticlesPage author={richAuthor} articles={articles} config={config} />
+      )
+      expect(screen.queryByText(richAuthor.promise)).not.toBeInTheDocument()
+      expect(screen.queryByText('Who I help')).not.toBeInTheDocument()
+      expect(screen.queryByText('My story')).not.toBeInTheDocument()
+      expect(screen.queryByText('What I believe')).not.toBeInTheDocument()
+      expect(screen.queryByText('Proof')).not.toBeInTheDocument()
+      expect(screen.queryByRole('link', { name: 'Book a session' })).not.toBeInTheDocument()
+      expect(container.querySelector('[aria-label="Author promise"]')).not.toBeInTheDocument()
+    })
+
+    it('legacy profile (no new fields) renders identically whether or not sections is passed with only "articles"', () => {
+      const legacy = render(
+        <AuthorArticlesPage author={author} articles={articles} config={config} />
+      )
+      expect(legacy.getByText('Articles by Andrew Blase')).toBeInTheDocument()
+      legacy.unmount()
+
+      const withSections = render(
+        <AuthorArticlesPage
+          author={author}
+          articles={articles}
+          config={config}
+          sections={['articles']}
+        />
+      )
+      expect(withSections.getByText('Articles by Andrew Blase')).toBeInTheDocument()
+      expect(withSections.getByRole('link', { name: 'Test Article' })).toHaveAttribute(
+        'href',
+        '/articles/test-article'
+      )
+    })
+
+    it('renders only the requested sections, in the requested order', () => {
+      render(
+        <AuthorArticlesPage
+          author={richAuthor}
+          articles={articles}
+          config={config}
+          sections={['promise', 'hero']}
+        />
+      )
+      expect(screen.getByText(richAuthor.promise)).toBeInTheDocument()
+      expect(screen.getByRole('heading', { name: 'Andrew Blase' })).toBeInTheDocument()
+      expect(screen.queryByText('Who I help')).not.toBeInTheDocument()
+      expect(screen.queryByRole('link', { name: 'Test Article' })).not.toBeInTheDocument()
+    })
+
+    it('omits a listed section with no backing data', () => {
+      render(
+        <AuthorArticlesPage
+          author={author}
+          articles={articles}
+          config={config}
+          sections={['promise', 'servesWho', 'originStory', 'principles', 'proof', 'cta']}
+        />
+      )
+      expect(screen.queryByText('Who I help')).not.toBeInTheDocument()
+      expect(screen.queryByText('My story')).not.toBeInTheDocument()
+      expect(screen.queryByText('What I believe')).not.toBeInTheDocument()
+      expect(screen.queryByText('Proof')).not.toBeInTheDocument()
+    })
+
+    it('renders servesWho, originStory, principles, and proof with accessible landmarks', () => {
+      const { container } = render(
+        <AuthorArticlesPage
+          author={richAuthor}
+          articles={articles}
+          config={config}
+          sections={['servesWho', 'originStory', 'principles', 'proof']}
+        />
+      )
+      expect(screen.getByRole('heading', { name: 'Who I help' })).toBeInTheDocument()
+      expect(screen.getByText('New game masters')).toBeInTheDocument()
+      expect(screen.getByText('Streaming DMs')).toBeInTheDocument()
+
+      expect(screen.getByRole('heading', { name: 'My story' })).toBeInTheDocument()
+      expect(screen.getByRole('heading', { name: 'How it started' })).toBeInTheDocument()
+      expect(screen.getByText('Ran my first session in 2010.')).toBeInTheDocument()
+      expect(screen.getByText('Never looked back.')).toBeInTheDocument()
+
+      expect(screen.getByRole('heading', { name: 'What I believe' })).toBeInTheDocument()
+      expect(screen.getByText('Fun first')).toBeInTheDocument()
+
+      expect(screen.getByRole('heading', { name: 'Proof' })).toBeInTheDocument()
+      expect(screen.getByText('500+ sessions run')).toBeInTheDocument()
+      expect(screen.getByText('Personal log')).toBeInTheDocument()
+      expect(screen.getByRole('link', { name: 'https://example.com/podcast' })).toHaveAttribute(
+        'href',
+        'https://example.com/podcast'
+      )
+
+      expect(container.querySelector('[aria-label="Who this author serves"]')).toBeInTheDocument()
+      expect(container.querySelector('[aria-label="Author origin story"]')).toBeInTheDocument()
+      expect(container.querySelector('[aria-label="Author principles"]')).toBeInTheDocument()
+      expect(container.querySelector('[aria-label="Author proof"]')).toBeInTheDocument()
+    })
+
+    it('renders primaryCta as a link with the configured label and href', () => {
+      render(
+        <AuthorArticlesPage
+          author={richAuthor}
+          articles={articles}
+          config={config}
+          sections={['cta']}
+        />
+      )
+      expect(screen.getByRole('link', { name: 'Book a session' })).toHaveAttribute('href', '/book')
+    })
+
+    it('fires cta_clicked with a ctaId when the primaryCta link is clicked (Phase 27F)', () => {
+      const onEvent = jest.fn()
+      render(
+        <AuthorArticlesPage
+          author={richAuthor}
+          articles={articles}
+          config={{ ...config, onEvent }}
+          sections={['cta']}
+        />
+      )
+      fireEvent.click(screen.getByRole('link', { name: 'Book a session' }))
+      expect(onEvent).toHaveBeenCalledWith(
+        expect.objectContaining({ name: 'cta_clicked', ctaId: 'author-cta:andrew-blase' })
+      )
+    })
+
+    it('fires cta_viewed for the primaryCta section (Phase 27F, no IntersectionObserver in jsdom falls back to immediate)', () => {
+      const onEvent = jest.fn()
+      render(
+        <AuthorArticlesPage
+          author={richAuthor}
+          articles={articles}
+          config={{ ...config, onEvent }}
+          sections={['cta']}
+        />
+      )
+      expect(onEvent).toHaveBeenCalledWith(
+        expect.objectContaining({ name: 'cta_viewed', ctaId: 'author-cta:andrew-blase' })
+      )
+    })
+
+    it('renders the custom section slot only when "custom" is listed, using customSection', () => {
+      const { rerender } = render(
+        <AuthorArticlesPage
+          author={author}
+          articles={articles}
+          config={config}
+          sections={['articles']}
+          customSection={<div>Custom block</div>}
+        />
+      )
+      expect(screen.queryByText('Custom block')).not.toBeInTheDocument()
+
+      rerender(
+        <AuthorArticlesPage
+          author={author}
+          articles={articles}
+          config={config}
+          sections={['custom']}
+          customSection={<div>Custom block</div>}
+        />
+      )
+      expect(screen.getByText('Custom block')).toBeInTheDocument()
+    })
+
+    it('excludes credentials, servesWho, principles, proof, and promise from the Person JSON-LD', () => {
+      const { container } = render(
+        <AuthorArticlesPage author={richAuthor} articles={articles} config={config} />
+      )
+      const schemas = parseSchemaScript(container)
+      const person = schemas.find((schema) => schema['@type'] === 'Person')
+      expect(person).toBeDefined()
+      const serialized = JSON.stringify(person)
+      expect(serialized).not.toContain('Helping new GMs')
+      expect(serialized).not.toContain('10+ years running')
+      expect(serialized).not.toContain('New game masters')
+      expect(serialized).not.toContain('Fun first')
+      expect(serialized).not.toContain('500+ sessions run')
+      expect(person).toEqual(
+        expect.objectContaining({
+          description: 'Writer focused on civic technology.',
+        })
+      )
+    })
   })
 })

package/src/__tests__/CategoryArticlesPage.test.tsx

@@ -30,8 +30,19 @@ jest.mock('next/image', () => ({
 }))
 
 jest.mock('../LatestArticles', () => ({
-  LatestArticles: ({ articles }: { articles: Article[] }) => (
+  LatestArticles: ({
+    articles,
+    pagination,
+  }: {
+    articles: Article[]
+    pagination?: { page: number; totalPages: number; basePath: string }
+  }) => (
     <div data-testid="latest-articles">
+      {pagination && (
+        <div data-testid="pagination-context">
+          {`page=${pagination.page} totalPages=${pagination.totalPages} basePath=${pagination.basePath}`}
+        </div>
+      )}
       {articles.map((a) => (
         <div key={a.slug} data-testid="article-card">
           {a.title}
@@ -179,4 +190,108 @@ describe('CategoryArticlesPage', () => {
     )
     expect(screen.getByText('Browse all articles in Campaigns.')).toBeInTheDocument()
   })
+
+  it('renders a CollectionPage schema with an ItemList of the articles', () => {
+    const { container } = render(
+      <CategoryArticlesPage
+        category="campaigns"
+        articles={[
+          makeArticle({ slug: 'a1', title: 'Article One', category: 'Campaigns' }),
+          makeArticle({ slug: 'a2', title: 'Article Two', category: 'Campaigns' }),
+        ]}
+        config={baseConfig}
+      />
+    )
+    const script = container.querySelector('script[type="application/ld+json"]')
+    expect(script).not.toBeNull()
+    const schema = JSON.parse(script!.innerHTML)
+    expect(schema).toEqual(
+      expect.objectContaining({
+        '@type': 'CollectionPage',
+        name: 'Campaigns | Test Site',
+        url: 'https://example.com/articles/category/campaigns',
+        numberOfItems: 2,
+        mainEntity: {
+          '@type': 'ItemList',
+          itemListElement: [
+            {
+              '@type': 'ListItem',
+              position: 1,
+              url: 'https://example.com/articles/a1',
+              name: 'Article One',
+            },
+            {
+              '@type': 'ListItem',
+              position: 2,
+              url: 'https://example.com/articles/a2',
+              name: 'Article Two',
+            },
+          ],
+        },
+      })
+    )
+  })
+
+  describe('listingPagination: "pages" mode', () => {
+    const pagesConfig: ArticlesConfig = { ...baseConfig, listingPagination: 'pages' }
+
+    it('does not pass pagination through when config.listingPagination is unset, even with page/totalPages', () => {
+      render(
+        <CategoryArticlesPage
+          category="campaigns"
+          articles={[makeArticle()]}
+          config={baseConfig}
+          page={2}
+          totalPages={4}
+        />
+      )
+      expect(screen.queryByTestId('pagination-context')).not.toBeInTheDocument()
+    })
+
+    it('passes a pagination context built from category/page/totalPages down to LatestArticles', () => {
+      render(
+        <CategoryArticlesPage
+          category="campaigns"
+          articles={[makeArticle()]}
+          config={pagesConfig}
+          page={2}
+          totalPages={4}
+        />
+      )
+      expect(screen.getByTestId('pagination-context')).toHaveTextContent(
+        'page=2 totalPages=4 basePath=/articles/category/campaigns'
+      )
+    })
+
+    it('uses totalCount for the CollectionPage schema articleCount when provided', () => {
+      const { container } = render(
+        <CategoryArticlesPage
+          category="campaigns"
+          articles={[makeArticle({ category: 'Campaigns' })]}
+          config={pagesConfig}
+          page={1}
+          totalPages={5}
+          totalCount={17}
+        />
+      )
+      const script = container.querySelector('script[type="application/ld+json"]')
+      const schema = JSON.parse(script!.innerHTML)
+      expect(schema.numberOfItems).toBe(17)
+    })
+
+    it('falls back to articles.length for articleCount when totalCount is omitted', () => {
+      const { container } = render(
+        <CategoryArticlesPage
+          category="campaigns"
+          articles={[makeArticle({ category: 'Campaigns' })]}
+          config={pagesConfig}
+          page={1}
+          totalPages={5}
+        />
+      )
+      const script = container.querySelector('script[type="application/ld+json"]')
+      const schema = JSON.parse(script!.innerHTML)
+      expect(schema.numberOfItems).toBe(1)
+    })
+  })
 })

package/src/__tests__/LatestArticles.test.tsx

@@ -154,4 +154,56 @@ describe('LatestArticles', () => {
     }
     expect(screen.queryByRole('button', { name: 'Load more articles' })).not.toBeInTheDocument()
   })
+
+  describe('pagination prop (listingPagination: "pages" mode)', () => {
+    it('renders every given article without slicing to pageSize', () => {
+      render(
+        <LatestArticles
+          articles={makeArticles(3)}
+          pageSize={3}
+          pagination={{ page: 2, totalPages: 4, basePath: '/articles' }}
+        />
+      )
+      expect(screen.getByText('Article 1')).toBeInTheDocument()
+      expect(screen.getByText('Article 2')).toBeInTheDocument()
+      expect(screen.getByText('Article 3')).toBeInTheDocument()
+    })
+
+    it('does not render the "Load more" button', () => {
+      render(
+        <LatestArticles
+          articles={makeArticles(3)}
+          pageSize={3}
+          pagination={{ page: 1, totalPages: 3, basePath: '/articles' }}
+        />
+      )
+      expect(screen.queryByRole('button', { name: 'Load more articles' })).not.toBeInTheDocument()
+    })
+
+    it('renders PaginationNav with the given page/totalPages/basePath', () => {
+      render(
+        <LatestArticles
+          articles={makeArticles(3)}
+          pageSize={3}
+          pagination={{ page: 2, totalPages: 4, basePath: '/articles/category/campaigns' }}
+        />
+      )
+      expect(screen.getByText('Page 2 of 4')).toBeInTheDocument()
+      expect(screen.getByRole('link', { name: /next/i })).toHaveAttribute(
+        'href',
+        '/articles/category/campaigns/page/3'
+      )
+    })
+
+    it('does not render PaginationNav when totalPages is 1', () => {
+      render(
+        <LatestArticles
+          articles={makeArticles(3)}
+          pageSize={3}
+          pagination={{ page: 1, totalPages: 1, basePath: '/articles' }}
+        />
+      )
+      expect(screen.queryByText(/Page \d+ of \d+/)).not.toBeInTheDocument()
+    })
+  })
 })

package/src/__tests__/LatestArticlesSection.test.tsx

@@ -102,4 +102,32 @@ describe('LatestArticlesSection', () => {
     fireEvent.click(screen.getByRole('button', { name: 'Clear search' }))
     expect(onClearSearch).toHaveBeenCalledTimes(1)
   })
+
+  describe('pagination prop (listingPagination: "pages" mode)', () => {
+    const pagination = { page: 2, totalPages: 3, basePath: '/articles' }
+
+    it('passes pagination through to LatestArticles when not searching', () => {
+      render(
+        <LatestArticlesSection
+          articles={[makeArticle(1)]}
+          searchQuery=""
+          onClearSearch={noOp}
+          pagination={pagination}
+        />
+      )
+      expect(screen.getByText('Page 2 of 3')).toBeInTheDocument()
+    })
+
+    it('does not pass pagination through while a search query is active', () => {
+      render(
+        <LatestArticlesSection
+          articles={[makeArticle(1)]}
+          searchQuery="voter"
+          onClearSearch={noOp}
+          pagination={pagination}
+        />
+      )
+      expect(screen.queryByText(/Page \d+ of \d+/)).not.toBeInTheDocument()
+    })
+  })
 })

package/src/__tests__/PaginationNav.test.tsx

@@ -0,0 +1,73 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { PaginationNav } from '../PaginationNav'
+
+jest.mock('next/link', () => ({
+  __esModule: true,
+  default: ({ href, children }: { href: string; children: React.ReactNode }) => (
+    <a href={href}>{children}</a>
+  ),
+}))
+
+describe('PaginationNav', () => {
+  it('renders nothing when there is only one page', () => {
+    const { container } = render(<PaginationNav basePath="/articles" page={1} totalPages={1} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('shows the current page and total page count', () => {
+    render(<PaginationNav basePath="/articles" page={2} totalPages={4} />)
+    expect(screen.getByText('Page 2 of 4')).toBeInTheDocument()
+  })
+
+  it('renders a real Previous link with the correct href on a middle page', () => {
+    render(<PaginationNav basePath="/articles" page={2} totalPages={4} />)
+    expect(screen.getByRole('link', { name: /previous/i })).toHaveAttribute('href', '/articles')
+  })
+
+  it('renders a real Next link with the correct href on a middle page', () => {
+    render(<PaginationNav basePath="/articles" page={2} totalPages={4} />)
+    expect(screen.getByRole('link', { name: /next/i })).toHaveAttribute('href', '/articles/page/3')
+  })
+
+  it('has no Previous link on page 1', () => {
+    render(<PaginationNav basePath="/articles" page={1} totalPages={4} />)
+    expect(screen.queryByRole('link', { name: /previous/i })).not.toBeInTheDocument()
+    expect(screen.getByText('Previous')).toBeInTheDocument()
+  })
+
+  it('has no Next link on the last page', () => {
+    render(<PaginationNav basePath="/articles" page={4} totalPages={4} />)
+    expect(screen.queryByRole('link', { name: /next/i })).not.toBeInTheDocument()
+    expect(screen.getByText('Next')).toBeInTheDocument()
+  })
+
+  // React 19 hoists <link>/<meta> elements rendered anywhere in the tree into
+  // document.head (not left in place in the local subtree) - so these
+  // assertions check document.head rather than the render()'d container.
+  it('renders rel="prev" and rel="next" link tags for crawlers/tools that read them', () => {
+    render(<PaginationNav basePath="/articles" page={2} totalPages={4} />)
+    expect(document.head.querySelector('link[rel="prev"]')).toHaveAttribute('href', '/articles')
+    expect(document.head.querySelector('link[rel="next"]')).toHaveAttribute(
+      'href',
+      '/articles/page/3'
+    )
+  })
+
+  it('omits rel="prev" on page 1 and rel="next" on the last page', () => {
+    render(<PaginationNav basePath="/articles" page={1} totalPages={4} />)
+    expect(document.head.querySelector('link[rel="prev"]')).toBeNull()
+    expect(document.head.querySelector('link[rel="next"]')).not.toBeNull()
+  })
+
+  it('builds hrefs from a nested basePath (category/author routes)', () => {
+    render(<PaginationNav basePath="/articles/category/campaigns" page={1} totalPages={2} />)
+    expect(screen.getByRole('link', { name: /next/i })).toHaveAttribute(
+      'href',
+      '/articles/category/campaigns/page/2'
+    )
+  })
+})