@fullstackdatasolutions/articles 0.11.0 → 1.0.0

package/src/__tests__/RelatedArticlesSection.test.tsx

@@ -0,0 +1,132 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from 'react'
+import { render, screen, fireEvent } from '@testing-library/react'
+import type { Article } from '../articleTypes'
+import { RelatedArticlesSection } from '../RelatedArticlesSection'
+import type { ArticlesConfig } from '../articlesConfig'
+
+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 articles: Article[] = [
+  {
+    slug: 'one',
+    title: 'Article One',
+    excerpt: 'Excerpt one.',
+    author: 'Jane Doe',
+    category: 'Civic Tech',
+    categories: ['Civic Tech'],
+    readTime: '3 min read',
+    featuredImage: '/one.jpg',
+  },
+  {
+    slug: 'two',
+    title: 'Article Two',
+    excerpt: 'Excerpt two.',
+    author: 'Jane Doe',
+    category: 'Civic Tech',
+    categories: ['Civic Tech'],
+    readTime: '4 min read',
+    featuredImage: '/two.jpg',
+  },
+]
+
+describe('RelatedArticlesSection', () => {
+  it('renders nothing when there are no related articles', () => {
+    const { container } = render(<RelatedArticlesSection articles={[]} category="Civic Tech" />)
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('renders a heading naming the category', () => {
+    render(<RelatedArticlesSection articles={articles} category="Civic Tech" />)
+    expect(screen.getByRole('heading', { name: 'More in Civic Tech' })).toBeInTheDocument()
+  })
+
+  it('renders a real link for every related article', () => {
+    render(<RelatedArticlesSection articles={articles} category="Civic Tech" />)
+    expect(screen.getByRole('link', { name: 'Article One' })).toHaveAttribute(
+      'href',
+      '/articles/one'
+    )
+    expect(screen.getByRole('link', { name: 'Article Two' })).toHaveAttribute(
+      'href',
+      '/articles/two'
+    )
+  })
+
+  describe('heading override (Phase 27F)', () => {
+    it('uses a custom heading when provided, instead of "More in {category}"', () => {
+      render(
+        <RelatedArticlesSection articles={articles} category="Civic Tech" heading="New GM Path" />
+      )
+      expect(screen.getByRole('heading', { name: 'New GM Path' })).toBeInTheDocument()
+      expect(screen.queryByText('More in Civic Tech')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('related_article_clicked event (Phase 27F)', () => {
+    it('fires related_article_clicked with fromSlug/toSlug/source on card click', () => {
+      const onEvent = jest.fn()
+      const config: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Test', onEvent }
+      render(
+        <RelatedArticlesSection
+          articles={articles}
+          category="Civic Tech"
+          config={config}
+          fromSlug="current-article"
+          source="series"
+        />
+      )
+      fireEvent.click(screen.getByRole('link', { name: 'Article One' }))
+      expect(onEvent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'related_article_clicked',
+          fromSlug: 'current-article',
+          toSlug: 'one',
+          source: 'series',
+        })
+      )
+    })
+
+    it('defaults source to "category" when omitted', () => {
+      const onEvent = jest.fn()
+      const config: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Test', onEvent }
+      render(
+        <RelatedArticlesSection
+          articles={articles}
+          category="Civic Tech"
+          config={config}
+          fromSlug="current-article"
+        />
+      )
+      fireEvent.click(screen.getByRole('link', { name: 'Article Two' }))
+      expect(onEvent).toHaveBeenCalledWith(expect.objectContaining({ source: 'category' }))
+    })
+
+    it('does not fire an event when fromSlug is omitted', () => {
+      const onEvent = jest.fn()
+      const config: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Test', onEvent }
+      render(<RelatedArticlesSection articles={articles} category="Civic Tech" config={config} />)
+      fireEvent.click(screen.getByRole('link', { name: 'Article One' }))
+      expect(onEvent).not.toHaveBeenCalled()
+    })
+
+    it('does not throw when config is omitted', () => {
+      render(
+        <RelatedArticlesSection articles={articles} category="Civic Tech" fromSlug="current" />
+      )
+      expect(() => fireEvent.click(screen.getByRole('link', { name: 'Article One' }))).not.toThrow()
+    })
+  })
+})

package/src/__tests__/SeriesArticlesPage.test.tsx

@@ -0,0 +1,121 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import type { Article } from '../articleTypes'
+import { SeriesArticlesPage } from '../SeriesArticlesPage'
+import type { ArticlesConfig } from '../articlesConfig'
+
+jest.mock('next/link', () => ({
+  __esModule: true,
+  default: ({ href, children }: { href: string; children: React.ReactNode }) => (
+    <a href={href}>{children}</a>
+  ),
+}))
+
+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', () => ({
+  CollectionPageSchema: ({ title }: { title: string }) => (
+    <script data-testid="collection-schema" data-title={title} />
+  ),
+}))
+
+const baseConfig: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Test Site' }
+
+const makeArticle = (overrides: Partial<Article> = {}): Article => ({
+  slug: 'step-1',
+  title: 'Step One',
+  excerpt: 'An excerpt.',
+  author: 'Jane Doe',
+  category: 'Campaigns',
+  categories: ['Campaigns'],
+  readTime: '3 min read',
+  featuredImage: '/img.jpg',
+  series: 'New GM Path',
+  seriesSlug: 'new-gm',
+  seriesOrder: 1,
+  ...overrides,
+})
+
+describe('SeriesArticlesPage', () => {
+  it('renders nothing when articles is empty', () => {
+    const { container } = render(
+      <SeriesArticlesPage seriesSlug="new-gm" articles={[]} config={baseConfig} />
+    )
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('renders the series name from the first article label', () => {
+    render(
+      <SeriesArticlesPage seriesSlug="new-gm" articles={[makeArticle()]} config={baseConfig} />
+    )
+    expect(screen.getByRole('heading', { name: 'New GM Path' })).toBeInTheDocument()
+  })
+
+  it('falls back to the seriesSlug when no article has a series label', () => {
+    render(
+      <SeriesArticlesPage
+        seriesSlug="new-gm"
+        articles={[makeArticle({ series: undefined })]}
+        config={baseConfig}
+      />
+    )
+    expect(screen.getByRole('heading', { name: 'new-gm' })).toBeInTheDocument()
+  })
+
+  it('renders every article via LatestArticles', () => {
+    render(
+      <SeriesArticlesPage
+        seriesSlug="new-gm"
+        articles={[
+          makeArticle(),
+          makeArticle({ slug: 'step-2', title: 'Step Two', seriesOrder: 2 }),
+        ]}
+        config={baseConfig}
+      />
+    )
+    expect(screen.getAllByTestId('article-card')).toHaveLength(2)
+    expect(screen.getByText('Step One')).toBeInTheDocument()
+    expect(screen.getByText('Step Two')).toBeInTheDocument()
+  })
+
+  it('renders a CollectionPageSchema', () => {
+    render(
+      <SeriesArticlesPage seriesSlug="new-gm" articles={[makeArticle()]} config={baseConfig} />
+    )
+    expect(screen.getByTestId('collection-schema')).toHaveAttribute(
+      'data-title',
+      'New GM Path | Test Site'
+    )
+  })
+
+  it('shows the article count', () => {
+    render(
+      <SeriesArticlesPage
+        seriesSlug="new-gm"
+        articles={[makeArticle(), makeArticle({ slug: 'step-2' })]}
+        config={baseConfig}
+      />
+    )
+    expect(screen.getByText('2 articles in this series')).toBeInTheDocument()
+  })
+
+  it('uses singular "article" for a single-article series', () => {
+    render(
+      <SeriesArticlesPage seriesSlug="new-gm" articles={[makeArticle()]} config={baseConfig} />
+    )
+    expect(screen.getByText('1 article in this series')).toBeInTheDocument()
+  })
+})

package/src/__tests__/eventTracking.test.tsx

@@ -0,0 +1,145 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ArticleViewTracker, CtaViewTracker } from '../eventTracking'
+import type { ArticlesConfig } from '../articlesConfig'
+
+describe('ArticleViewTracker', () => {
+  beforeEach(() => {
+    jest.useFakeTimers()
+  })
+
+  afterEach(() => {
+    jest.useRealTimers()
+  })
+
+  it('renders nothing', () => {
+    const { container } = render(
+      <ArticleViewTracker article={{ slug: 'a' }} config={{ siteUrl: 'x', siteName: 'y' }} />
+    )
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('fires article_viewed on mount with category/seriesSlug', () => {
+    const onEvent = jest.fn()
+    const config: ArticlesConfig = { siteUrl: 'x', siteName: 'y', onEvent }
+    render(
+      <ArticleViewTracker
+        article={{ slug: 'a', category: 'Campaigns', seriesSlug: 'new-gm' }}
+        config={config}
+      />
+    )
+    expect(onEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: 'article_viewed',
+        articleSlug: 'a',
+        category: 'Campaigns',
+        seriesSlug: 'new-gm',
+      })
+    )
+  })
+
+  it('does not throw when config/onEvent is omitted', () => {
+    expect(() => render(<ArticleViewTracker article={{ slug: 'a' }} />)).not.toThrow()
+  })
+
+  it('fires meaningful_read once after the estimated read-time timer elapses', () => {
+    const onEvent = jest.fn()
+    const config: ArticlesConfig = { siteUrl: 'x', siteName: 'y', onEvent }
+    render(<ArticleViewTracker article={{ slug: 'a', wordCount: 400 }} config={config} />)
+
+    onEvent.mockClear()
+    // 400 words / 200wpm * 60000ms * 0.5 = 60000ms
+    jest.advanceTimersByTime(60_000)
+    expect(onEvent).toHaveBeenCalledWith(
+      expect.objectContaining({ name: 'meaningful_read', articleSlug: 'a' })
+    )
+    expect(onEvent).toHaveBeenCalledTimes(1)
+  })
+
+  it('uses a default timer when wordCount is unset', () => {
+    const onEvent = jest.fn()
+    const config: ArticlesConfig = { siteUrl: 'x', siteName: 'y', onEvent }
+    render(<ArticleViewTracker article={{ slug: 'a' }} config={config} />)
+    onEvent.mockClear()
+    jest.advanceTimersByTime(15_000)
+    expect(onEvent).toHaveBeenCalledWith(
+      expect.objectContaining({ name: 'meaningful_read', articleSlug: 'a' })
+    )
+  })
+})
+
+describe('CtaViewTracker', () => {
+  const originalIO = globalThis.IntersectionObserver
+
+  afterEach(() => {
+    globalThis.IntersectionObserver = originalIO
+  })
+
+  it('renders children', () => {
+    render(
+      <CtaViewTracker ctaId="cta-1">
+        <button type="button">Click me</button>
+      </CtaViewTracker>
+    )
+    expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument()
+  })
+
+  it('fires cta_viewed immediately when IntersectionObserver is unavailable', () => {
+    // @ts-expect-error - simulate an environment without IntersectionObserver
+    delete globalThis.IntersectionObserver
+    const onEvent = jest.fn()
+    render(
+      <CtaViewTracker
+        ctaId="cta-1"
+        articleSlug="a"
+        config={{ siteUrl: 'x', siteName: 'y', onEvent }}
+      >
+        <div>CTA</div>
+      </CtaViewTracker>
+    )
+    expect(onEvent).toHaveBeenCalledWith(
+      expect.objectContaining({ name: 'cta_viewed', ctaId: 'cta-1', articleSlug: 'a' })
+    )
+  })
+
+  it('fires cta_viewed once intersection is observed', () => {
+    let observedCallback: IntersectionObserverCallback | undefined
+    class FakeIntersectionObserver {
+      constructor(cb: IntersectionObserverCallback) {
+        observedCallback = cb
+      }
+      observe() {}
+      disconnect() {}
+    }
+    // @ts-expect-error - test double
+    globalThis.IntersectionObserver = FakeIntersectionObserver
+
+    const onEvent = jest.fn()
+    render(
+      <CtaViewTracker ctaId="cta-1" config={{ siteUrl: 'x', siteName: 'y', onEvent }}>
+        <div>CTA</div>
+      </CtaViewTracker>
+    )
+    expect(onEvent).not.toHaveBeenCalled()
+    observedCallback?.(
+      [{ isIntersecting: true } as IntersectionObserverEntry],
+      {} as IntersectionObserver
+    )
+    expect(onEvent).toHaveBeenCalledWith(expect.objectContaining({ name: 'cta_viewed' }))
+  })
+
+  it('does not throw when config is omitted', () => {
+    // @ts-expect-error - simulate an environment without IntersectionObserver
+    delete globalThis.IntersectionObserver
+    expect(() =>
+      render(
+        <CtaViewTracker ctaId="cta-1">
+          <div>CTA</div>
+        </CtaViewTracker>
+      )
+    ).not.toThrow()
+  })
+})

package/src/__tests__/events.test.ts

@@ -0,0 +1,82 @@
+import { emitArticleEvent } from '../events'
+import type { ArticleEvent } from '../events'
+
+describe('emitArticleEvent', () => {
+  it('does nothing when handler is undefined', () => {
+    expect(() =>
+      emitArticleEvent(undefined, { name: 'article_viewed', articleSlug: 'test' })
+    ).not.toThrow()
+  })
+
+  it('calls the handler with a stamped timestamp', () => {
+    const handler = jest.fn()
+    const before = Date.now()
+    emitArticleEvent(handler, { name: 'article_viewed', articleSlug: 'test' })
+    const after = Date.now()
+
+    expect(handler).toHaveBeenCalledTimes(1)
+    const event = handler.mock.calls[0][0] as ArticleEvent
+    expect(event.name).toBe('article_viewed')
+    expect(event.timestamp).toBeGreaterThanOrEqual(before)
+    expect(event.timestamp).toBeLessThanOrEqual(after)
+  })
+
+  it('preserves event-specific fields for each event shape', () => {
+    const handler = jest.fn()
+    emitArticleEvent(handler, {
+      name: 'author_clicked',
+      articleSlug: 'test',
+      authorSlug: 'jane-doe',
+    })
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: 'author_clicked',
+        articleSlug: 'test',
+        authorSlug: 'jane-doe',
+      })
+    )
+  })
+
+  it('swallows errors thrown by the consuming app handler', () => {
+    const handler = jest.fn(() => {
+      throw new Error('broken analytics integration')
+    })
+    expect(() =>
+      emitArticleEvent(handler, { name: 'shared', articleSlug: 'test', channel: 'linkedin' })
+    ).not.toThrow()
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  it('never includes PII-shaped fields (only slugs/ids/enums) in any event payload', () => {
+    const handler = jest.fn()
+    emitArticleEvent(handler, { name: 'article_viewed', articleSlug: 'a' })
+    emitArticleEvent(handler, { name: 'meaningful_read', articleSlug: 'a' })
+    emitArticleEvent(handler, { name: 'author_clicked', articleSlug: 'a', authorSlug: 'jane-doe' })
+    emitArticleEvent(handler, { name: 'cta_viewed', ctaId: 'kit' })
+    emitArticleEvent(handler, { name: 'cta_clicked', ctaId: 'kit' })
+    emitArticleEvent(handler, { name: 'shared', articleSlug: 'a', channel: 'copy-link' })
+    emitArticleEvent(handler, {
+      name: 'related_article_clicked',
+      fromSlug: 'a',
+      toSlug: 'b',
+      source: 'category',
+    })
+    emitArticleEvent(handler, {
+      name: 'path_step_advanced',
+      pathKey: 'p',
+      fromSlug: 'a',
+      toSlug: 'b',
+      direction: 'next',
+    })
+    const disallowedKeyFragments = ['email', 'name', 'phone', 'address']
+    for (const call of handler.mock.calls) {
+      const payload = call[0] as Record<string, unknown>
+      for (const key of Object.keys(payload)) {
+        if (key === 'name') continue // the event-type discriminant, e.g. 'shared' - not PII
+        for (const fragment of disallowedKeyFragments) {
+          expect(key.toLowerCase()).not.toContain(fragment)
+        }
+      }
+    }
+  })
+})

package/src/__tests__/markdown.test.ts

@@ -10,6 +10,11 @@ jest.mock('remark-parse', () => () => () => {})
 jest.mock('remark-rehype', () => () => () => {})
 
 const mockRemarkUseCalls: unknown[][] = []
+// Settable by individual `getContentSlotBoundaries` tests to control what
+// `.parse()` returns (real remark parsing isn't reachable under this
+// ESM-mocked setup - see the file-top comment) - `undefined` makes `.parse`
+// throw, exercising the "malformed source" fallback path.
+let mockParseResult: unknown
 
 // Mock remark() to return a chainable processor whose .process() resolves to ''
 jest.mock('remark', () => {
@@ -20,6 +25,10 @@ jest.mock('remark', () => {
         return chain
       },
       process: async () => ({ toString: () => '' }),
+      parse: () => {
+        if (mockParseResult === undefined) throw new Error('parse failed')
+        return mockParseResult
+      },
     }
     return chain
   }
@@ -55,7 +64,7 @@ jest.mock('unist-util-visit', () => ({
   },
 }))
 
-import { customRenderer, markdownToHtml, extractToc } from '../markdown'
+import { customRenderer, markdownToHtml, extractToc, getContentSlotBoundaries } from '../markdown'
 
 // ---------------------------------------------------------------------------
 // customRenderer
@@ -352,3 +361,71 @@ describe('extractToc', () => {
     await expect(extractToc('')).resolves.toBeDefined()
   })
 })
+
+// ---------------------------------------------------------------------------
+// getContentSlotBoundaries - deterministic paragraph-offset selection logic,
+// tested against a controlled fake mdast tree (see `mockParseResult` above)
+// since real remark parsing isn't reachable under this ESM-mocked setup.
+// ---------------------------------------------------------------------------
+
+function paragraph(start: number, end: number) {
+  return { type: 'paragraph', position: { start: { offset: start }, end: { offset: end } } }
+}
+
+describe('getContentSlotBoundaries', () => {
+  afterEach(() => {
+    mockParseResult = undefined
+  })
+
+  it('returns null when the source has no top-level paragraphs', () => {
+    mockParseResult = { type: 'root', children: [{ type: 'heading' }] }
+    expect(getContentSlotBoundaries('# Just a heading')).toBeNull()
+  })
+
+  it('returns null when parsing throws', () => {
+    mockParseResult = undefined
+    expect(getContentSlotBoundaries('anything')).toBeNull()
+  })
+
+  it('resolves introEnd to the end of the first paragraph', () => {
+    mockParseResult = { type: 'root', children: [paragraph(0, 10), paragraph(11, 25)] }
+    const boundaries = getContentSlotBoundaries('irrelevant, fake tree used')
+    expect(boundaries?.introEnd).toBe(10)
+  })
+
+  it('resolves mid to the end of the middle paragraph for an odd count', () => {
+    mockParseResult = {
+      type: 'root',
+      children: [paragraph(0, 10), paragraph(11, 25), paragraph(26, 40)],
+    }
+    const boundaries = getContentSlotBoundaries('fake tree used')
+    expect(boundaries?.mid).toBe(25)
+    expect(boundaries?.paragraphCount).toBe(3)
+  })
+
+  it('resolves mid to the end of the second-half paragraph for an even count', () => {
+    mockParseResult = {
+      type: 'root',
+      children: [paragraph(0, 10), paragraph(11, 25), paragraph(26, 40), paragraph(41, 55)],
+    }
+    const boundaries = getContentSlotBoundaries('fake tree used')
+    expect(boundaries?.mid).toBe(40)
+  })
+
+  it('handles a single paragraph by pointing mid at introEnd', () => {
+    mockParseResult = { type: 'root', children: [paragraph(0, 12)] }
+    const boundaries = getContentSlotBoundaries('One paragraph.')
+    expect(boundaries?.introEnd).toBe(12)
+    expect(boundaries?.mid).toBe(12)
+    expect(boundaries?.paragraphCount).toBe(1)
+  })
+
+  it('ignores non-paragraph top-level nodes', () => {
+    mockParseResult = {
+      type: 'root',
+      children: [{ type: 'heading' }, paragraph(5, 15), { type: 'thematicBreak' }],
+    }
+    const boundaries = getContentSlotBoundaries('fake tree used')
+    expect(boundaries?.paragraphCount).toBe(1)
+  })
+})