npm - @fullstackdatasolutions/articles - Versions diffs - 0.12.0 → 1.1.0 - Mend

@fullstackdatasolutions/articles 0.12.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (69) hide show

package/CHANGELOG.md +34 -0
package/README.md +559 -11
package/dist/index.cjs +984 -388
package/dist/index.cjs.map +1 -1
package/dist/index.d.cts +383 -21
package/dist/index.d.ts +383 -21
package/dist/index.js +968 -376
package/dist/index.js.map +1 -1
package/dist/nextjs.cjs +74 -6
package/dist/nextjs.cjs.map +1 -1
package/dist/nextjs.d.cts +149 -0
package/dist/nextjs.d.ts +149 -0
package/dist/nextjs.js +74 -6
package/dist/nextjs.js.map +1 -1
package/dist/server.cjs +665 -27
package/dist/server.cjs.map +1 -1
package/dist/server.d.cts +357 -3
package/dist/server.d.ts +357 -3
package/dist/server.js +643 -29
package/dist/server.js.map +1 -1
package/package.json +1 -1
package/src/ArticleCard.tsx +42 -6
package/src/ArticleContent.tsx +144 -5
package/src/ArticleDetailHero.tsx +33 -1
package/src/ArticleNavigation.tsx +32 -1
package/src/ArticleSchemas.tsx +43 -39
package/src/ArticleSocialShare.tsx +54 -10
package/src/ArticlesPage.tsx +56 -5
package/src/AuthorArticlesPage.tsx +308 -14
package/src/AuthorCard.tsx +1 -1
package/src/CategoryArticlesPage.tsx +34 -2
package/src/LatestArticles.tsx +28 -1
package/src/LatestArticlesSection.tsx +15 -1
package/src/PaginationNav.tsx +78 -0
package/src/RelatedArticlesSection.tsx +58 -0
package/src/SeriesArticlesPage.tsx +66 -0
package/src/__tests__/ArticleCard.test.tsx +63 -3
package/src/__tests__/ArticleContent.test.tsx +143 -0
package/src/__tests__/ArticleDetailHero.test.tsx +30 -0
package/src/__tests__/ArticleNavigation.test.tsx +81 -3
package/src/__tests__/ArticleSchemas.test.tsx +155 -81
package/src/__tests__/ArticleSocialShare.test.tsx +54 -0
package/src/__tests__/ArticlesPage.test.tsx +131 -0
package/src/__tests__/AuthorArticlesPage.test.tsx +304 -3
package/src/__tests__/CategoryArticlesPage.test.tsx +116 -1
package/src/__tests__/LatestArticles.test.tsx +52 -0
package/src/__tests__/LatestArticlesSection.test.tsx +28 -0
package/src/__tests__/PaginationNav.test.tsx +73 -0
package/src/__tests__/RelatedArticlesSection.test.tsx +132 -0
package/src/__tests__/SeriesArticlesPage.test.tsx +121 -0
package/src/__tests__/eventTracking.test.tsx +145 -0
package/src/__tests__/events.test.ts +82 -0
package/src/__tests__/markdown.test.ts +78 -1
package/src/__tests__/pagination.test.ts +178 -0
package/src/__tests__/seoUtils-authors.test.ts +37 -0
package/src/__tests__/seoUtils.test.ts +246 -0
package/src/__tests__/server-articles.test.ts +356 -1
package/src/__tests__/validateArticles.test.ts +312 -0
package/src/articleTypes.ts +109 -0
package/src/articlesConfig.ts +45 -1
package/src/eventTracking.tsx +97 -0
package/src/events.ts +105 -0
package/src/index.ts +26 -1
package/src/markdown.ts +41 -0
package/src/pagination.ts +93 -0
package/src/seoUtils.ts +198 -11
package/src/server-articles.ts +199 -6
package/src/server.ts +46 -2
package/src/validateArticles.ts +260 -0

package/src/PaginationNav.tsx ADDED Viewed

@@ -0,0 +1,78 @@
+import Link from 'next/link'
+import { ChevronLeft, ChevronRight } from 'lucide-react'
+import { buildPaginationLinks } from './pagination'
+interface PaginationNavProps {
+  readonly basePath: string
+  readonly page: number
+  readonly totalPages: number
+}
+/**
+ * Renders real `<a href>` prev/next links between listing pages (used only
+ * in `listingPagination: 'pages'` mode), plus `<link rel="prev"/"next">`
+ * tags for crawlers/tools that still read them.
+ *
+ * Google stopped using rel=next/prev as an indexing signal in 2019 (Google
+ * Search Central's pagination guidance now recommends a unique
+ * self-referencing canonical per page - see `generateArticlesIndexPageMetadata`
+ * et al in seoUtils.ts - plus real crawlable links between pages, which is
+ * what this component's visible Previous/Next links provide). rel=next/prev
+ * remains valid HTML and is still read by Bing and some third-party tools,
+ * so it's emitted here for free: React 19 hoists `<link>`/`<meta>` elements
+ * rendered anywhere in a Server Component tree into `<head>` automatically
+ * (not just from layout.js/page.js directly), so no separate Head API call
+ * is needed.
+ */
+export function PaginationNav({ basePath, page, totalPages }: PaginationNavProps) {
+  if (totalPages <= 1) return null
+  const { prevUrl, nextUrl } = buildPaginationLinks(basePath, page, totalPages)
+  return (
+    <nav
+      className="mt-10 flex items-center justify-center gap-4"
+      aria-label="Article listing pagination"
+    >
+      {prevUrl && <link rel="prev" href={prevUrl} />}
+      {nextUrl && <link rel="next" href={nextUrl} />}
+      {prevUrl ? (
+        <Link
+          href={prevUrl}
+          className="inline-flex items-center gap-1 px-4 py-2 border border-input bg-background hover:bg-accent rounded-md font-medium text-sm transition-colors"
+        >
+          <ChevronLeft className="h-4 w-4" aria-hidden="true" />
+          Previous
+        </Link>
+      ) : (
+        <span
+          aria-hidden="true"
+          className="inline-flex items-center gap-1 px-4 py-2 rounded-md font-medium text-sm text-muted-foreground opacity-50"
+        >
+          <ChevronLeft className="h-4 w-4" />
+          Previous
+        </span>
+      )}
+      <span className="text-sm text-muted-foreground">
+        Page {page} of {totalPages}
+      </span>
+      {nextUrl ? (
+        <Link
+          href={nextUrl}
+          className="inline-flex items-center gap-1 px-4 py-2 border border-input bg-background hover:bg-accent rounded-md font-medium text-sm transition-colors"
+        >
+          Next
+          <ChevronRight className="h-4 w-4" aria-hidden="true" />
+        </Link>
+      ) : (
+        <span
+          aria-hidden="true"
+          className="inline-flex items-center gap-1 px-4 py-2 rounded-md font-medium text-sm text-muted-foreground opacity-50"
+        >
+          Next
+          <ChevronRight className="h-4 w-4" />
+        </span>
+      )}
+    </nav>
+  )
+}

package/src/RelatedArticlesSection.tsx ADDED Viewed

@@ -0,0 +1,58 @@
+import type { Article } from './articleTypes'
+import type { ArticlesConfig } from './articlesConfig'
+import { ArticleCard } from './ArticleCard'
+import { emitArticleEvent } from './events'
+import type { RelatedContentSource } from './server-articles'
+type RelatedArticlesSectionProps = Readonly<{
+  articles: Article[]
+  category: string
+  /** Overrides the default "More in {category}" heading - used by `getRelatedContent` callers when `source` is `'path'`/`'series'`. Omit to keep the default category-based heading. */
+  heading?: string
+  /** Optional (Phase 27F). Enables `related_article_clicked` events - requires `fromSlug` too. */
+  config?: ArticlesConfig
+  /** The article slug this related section is shown on. Required to emit `related_article_clicked`. */
+  fromSlug?: string
+  /** Selection source that produced `articles`, from `getRelatedContent`. Defaults to `'category'`. */
+  source?: RelatedContentSource
+}>
+export function RelatedArticlesSection({
+  articles,
+  category,
+  heading,
+  config,
+  fromSlug,
+  source = 'category',
+}: RelatedArticlesSectionProps) {
+  if (articles.length === 0) return null
+  return (
+    <section className="mt-12 pt-8 border-t border-border" aria-label="Related articles">
+      <h2
+        className="text-xl font-semibold text-foreground mb-6"
+        style={{ fontFamily: config?.theme?.headerFontFamily }}
+      >
+        {heading ?? `More in ${category}`}
+      </h2>
+      <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+        {articles.map((article) => (
+          <div
+            key={article.slug}
+            onClickCapture={() => {
+              if (!fromSlug) return
+              emitArticleEvent(config?.onEvent, {
+                name: 'related_article_clicked',
+                fromSlug,
+                toSlug: article.slug,
+                source,
+              })
+            }}
+          >
+            <ArticleCard article={article} config={config} />
+          </div>
+        ))}
+      </div>
+    </section>
+  )
+}

package/src/SeriesArticlesPage.tsx ADDED Viewed

@@ -0,0 +1,66 @@
+'use client'
+import Link from 'next/link'
+import { CollectionPageSchema } from './ArticleSchemas'
+import { LatestArticles } from './LatestArticles'
+import { DEFAULT_PAGE_SIZE, type ArticlesConfig } from './articlesConfig'
+import type { Article } from './articleTypes'
+type SeriesArticlesPageProps = Readonly<{
+  /** Machine-safe series identifier - matches `Article.seriesSlug`. */
+  seriesSlug: string
+  /** Already resolved via `getArticlesBySeries` (seriesOrder-sorted). */
+  articles: Article[]
+  config: ArticlesConfig
+}>
+/**
+ * Lightweight series landing page (Phase 27F) - a thinner sibling of
+ * `CategoryArticlesPage` for a `seriesSlug`'s ordered reader journey rather
+ * than a category's chronological listing. Displays series position badges
+ * (1-indexed, following `getArticlesBySeries`' order) so a reader can see
+ * where in the journey each article sits; doesn't attempt real ('pages'
+ * mode) pagination - series are expected to be short, curated lists rather
+ * than open-ended listings, so `LatestArticles` is used purely for its
+ * card grid, sized to show every article without a "Load more" step.
+ */
+export function SeriesArticlesPage({ seriesSlug, articles, config }: SeriesArticlesPageProps) {
+  if (articles.length === 0) return null
+  const seriesName = articles[0].series ?? seriesSlug
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const seriesUrl = `${siteUrl}/articles/series/${seriesSlug}`
+  return (
+    <div>
+      <CollectionPageSchema
+        title={`${seriesName} | ${config.siteName}`}
+        description={`Follow the ${seriesName} series on ${config.siteName}.`}
+        url={seriesUrl}
+        articleCount={articles.length}
+        items={articles.map((article, index) => ({
+          position: index + 1,
+          url: `${siteUrl}/articles/${article.slug}`,
+          name: article.title,
+        }))}
+      />
+      <section className="py-16 bg-muted/50 flex-1">
+        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <div className="mb-8 flex items-center justify-between">
+            <Link href="/articles" className="text-sm text-primary hover:underline">
+              ← All Articles
+            </Link>
+            <p className="text-sm text-muted-foreground">
+              {articles.length} article{articles.length === 1 ? '' : 's'} in this series
+            </p>
+          </div>
+          <h1 className="text-3xl font-bold text-foreground mb-8">{seriesName}</h1>
+          <LatestArticles
+            articles={articles}
+            pageSize={Math.max(articles.length, DEFAULT_PAGE_SIZE)}
+          />
+        </div>
+      </section>
+    </div>
+  )
+}

package/src/__tests__/ArticleCard.test.tsx CHANGED Viewed

@@ -2,14 +2,21 @@
  * @jest-environment jsdom
  */
 import React from 'react'
-import { render, screen } from '@testing-library/react'
+import { render, screen, fireEvent } from '@testing-library/react'
 import type { Article } from '../articleTypes'
 import { ArticleCard } from '../ArticleCard'
+import type { ArticlesConfig } from '../articlesConfig'
 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>
   ),
 }))
@@ -75,4 +82,57 @@ describe('ArticleCard', () => {
       .filter((l) => l.getAttribute('href') === '/articles/test-article')
     expect(links.length).toBeGreaterThanOrEqual(2)
   })
+  it('does not render an author link when authorSlug is unset', () => {
+    render(<ArticleCard article={baseArticle} />)
+    expect(screen.queryByRole('link', { name: /Jane Doe/i })).not.toBeInTheDocument()
+  })
+  it('renders an author avatar image linked to the author page when authorAvatar is set', () => {
+    render(
+      <ArticleCard
+        article={{
+          ...baseArticle,
+          authorSlug: 'jane-doe',
+          authorAvatar: '/articles/authors/jane-doe/avatar.jpg',
+        }}
+      />
+    )
+    const link = screen.getByRole('link', { name: 'Jane Doe' })
+    expect(link).toHaveAttribute('href', '/articles/authors/jane-doe')
+    // Avatar image is decorative (alt="") since the adjacent name text
+    // already conveys it - query the DOM directly rather than by alt text.
+    expect(link.querySelector('img')).toHaveAttribute(
+      'src',
+      '/articles/authors/jane-doe/avatar.jpg'
+    )
+  })
+  it('falls back to initials when authorSlug is set but authorAvatar is not', () => {
+    render(<ArticleCard article={{ ...baseArticle, authorSlug: 'jane-doe' }} />)
+    const link = screen.getByRole('link', { name: 'Jane Doe' })
+    expect(link).toHaveAttribute('href', '/articles/authors/jane-doe')
+    expect(screen.getByText('JD')).toBeInTheDocument()
+  })
+  describe('author_clicked event (Phase 27F)', () => {
+    it('fires author_clicked when the author link is clicked and config.onEvent is set', () => {
+      const onEvent = jest.fn()
+      const config: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Test', onEvent }
+      render(<ArticleCard article={{ ...baseArticle, authorSlug: 'jane-doe' }} config={config} />)
+      fireEvent.click(screen.getByRole('link', { name: 'Jane Doe' }))
+      expect(onEvent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'author_clicked',
+          articleSlug: 'test-article',
+          authorSlug: 'jane-doe',
+        })
+      )
+    })
+    it('does not throw when config is omitted and the author link is clicked', () => {
+      render(<ArticleCard article={{ ...baseArticle, authorSlug: 'jane-doe' }} />)
+      expect(() => fireEvent.click(screen.getByRole('link', { name: 'Jane Doe' }))).not.toThrow()
+    })
+  })
 })

package/src/__tests__/ArticleContent.test.tsx CHANGED Viewed

@@ -14,6 +14,22 @@ jest.mock('../renderMdx', () => ({
   renderMdxSource: (...args: unknown[]) => mockRenderMdxSource(...args),
 }))
+// `../markdown` pulls in ESM-only unified/rehype packages ts-jest's CJS
+// transform can't load (see markdown.test.ts) - mocked wholesale here since
+// ArticleContent only needs markdownToHtml/getContentSlotBoundaries's
+// *contract*, not real markdown parsing, for these component-level tests.
+// Real paragraph-boundary parsing is unit-tested directly in
+// contentSlots.test.ts against a controlled fake AST.
+const mockMarkdownToHtml = jest.fn(async (markdown: string) => `<p>${markdown.trim()}</p>`)
+const mockGetContentSlotBoundaries = jest.fn()
+jest.mock('../markdown', () => ({
+  markdownToHtml: (...args: unknown[]) =>
+    (mockMarkdownToHtml as (...a: unknown[]) => Promise<string>)(...args),
+  getContentSlotBoundaries: (...args: unknown[]) =>
+    (mockGetContentSlotBoundaries as (...a: unknown[]) => unknown)(...args),
+}))
 const baseArticle: Article = {
   slug: 'test-slug',
   title: 'Test Title',
@@ -27,9 +43,14 @@ const baseArticle: Article = {
 describe('ArticleContent', () => {
   beforeEach(() => {
+    mockRenderMdxSource.mockClear()
     mockRenderMdxSource.mockResolvedValue(
       React.createElement('div', { 'data-testid': 'mdx-content' }, 'MDX rendered')
     )
+    mockMarkdownToHtml.mockClear()
+    mockMarkdownToHtml.mockImplementation(async (markdown: string) => `<p>${markdown.trim()}</p>`)
+    mockGetContentSlotBoundaries.mockReset()
+    mockGetContentSlotBoundaries.mockReturnValue(null)
   })
   describe('HTML path', () => {
@@ -148,4 +169,126 @@ describe('ArticleContent', () => {
       expect(mockRenderMdxSource).toHaveBeenCalledWith('# Hello MDX', '/articles/test-slug', config)
     })
   })
+  describe('Phase 27F slots', () => {
+    it('renders afterHero and afterContent around the body without needing paragraph boundaries', async () => {
+      const article: Article = { ...baseArticle, contentType: 'md', htmlContent: '<p>Body</p>' }
+      const el = await ArticleContent({
+        article,
+        afterHero: <div data-testid="after-hero">Hero slot</div>,
+        afterContent: <div data-testid="after-content">Content slot</div>,
+      })
+      render(el as React.ReactElement)
+      expect(screen.getByTestId('after-hero')).toBeInTheDocument()
+      expect(screen.getByTestId('after-content')).toBeInTheDocument()
+      expect(mockGetContentSlotBoundaries).not.toHaveBeenCalled()
+    })
+    it('resolves function slots with sanitized article context', async () => {
+      const article: Article = {
+        ...baseArticle,
+        contentType: 'md',
+        htmlContent: '<p>Body</p>',
+        authorSlug: 'jane-doe',
+        seriesSlug: 'new-gm',
+        primaryAction: { actionId: 'download-kit' },
+      }
+      let receivedContext: unknown
+      const el = await ArticleContent({
+        article,
+        afterHero: (ctx) => {
+          receivedContext = ctx
+          return <div data-testid="ctx">{ctx.slug}</div>
+        },
+      })
+      render(el as React.ReactElement)
+      expect(receivedContext).toEqual({
+        slug: 'test-slug',
+        title: 'Test Title',
+        category: 'test',
+        tags: [],
+        readTime: '3 min',
+        wordCount: undefined,
+        authorSlug: 'jane-doe',
+        seriesSlug: 'new-gm',
+        primaryActionId: 'download-kit',
+      })
+    })
+    it('splits at AST-derived paragraph boundaries when afterIntro/midContent are provided', async () => {
+      mockGetContentSlotBoundaries.mockReturnValue({ introEnd: 10, mid: 25, paragraphCount: 3 })
+      const article: Article = {
+        ...baseArticle,
+        contentType: 'md',
+        content: '0123456789 more content up to twenty-five then more.',
+        htmlContent: '<p>Whole body (unused when splitting)</p>',
+      }
+      const el = await ArticleContent({
+        article,
+        afterIntro: <div data-testid="after-intro">Intro slot</div>,
+        midContent: <div data-testid="mid-content">Mid slot</div>,
+      })
+      const { container } = render(el as React.ReactElement)
+      expect(mockGetContentSlotBoundaries).toHaveBeenCalledWith(article.content)
+      expect(mockMarkdownToHtml).toHaveBeenCalledTimes(3)
+      expect(screen.getByTestId('after-intro')).toBeInTheDocument()
+      expect(screen.getByTestId('mid-content')).toBeInTheDocument()
+      // afterIntro slot appears before midContent slot in document order
+      const introIndex = container.innerHTML.indexOf('after-intro')
+      const midIndex = container.innerHTML.indexOf('mid-content')
+      expect(introIndex).toBeGreaterThan(-1)
+      expect(midIndex).toBeGreaterThan(introIndex)
+    })
+    it('falls back to whole-body rendering (afterIntro/midContent omitted) when boundaries are null', async () => {
+      mockGetContentSlotBoundaries.mockReturnValue(null)
+      const article: Article = {
+        ...baseArticle,
+        contentType: 'md',
+        content: 'Some raw markdown with no detectable paragraphs.',
+        htmlContent: '<p>Whole body</p>',
+      }
+      const el = await ArticleContent({
+        article,
+        afterIntro: <div data-testid="after-intro">Intro slot</div>,
+        afterHero: <div data-testid="after-hero">Hero slot</div>,
+      })
+      const { container } = render(el as React.ReactElement)
+      expect(screen.getByTestId('after-hero')).toBeInTheDocument()
+      expect(screen.queryByTestId('after-intro')).not.toBeInTheDocument()
+      expect(container.innerHTML).toContain('Whole body')
+    })
+    it('falls back to whole-body rendering when the article has no raw content to split', async () => {
+      const article: Article = {
+        ...baseArticle,
+        contentType: 'md',
+        htmlContent: '<p>Whole body</p>',
+        // no `content` field set
+      }
+      const el = await ArticleContent({
+        article,
+        midContent: <div data-testid="mid-content">Mid slot</div>,
+      })
+      render(el as React.ReactElement)
+      expect(mockGetContentSlotBoundaries).not.toHaveBeenCalled()
+      expect(screen.queryByTestId('mid-content')).not.toBeInTheDocument()
+    })
+    it('supports slot splitting for MDX articles via renderMdxSource per segment', async () => {
+      mockGetContentSlotBoundaries.mockReturnValue({ introEnd: 5, mid: 12, paragraphCount: 2 })
+      const article: Article = {
+        ...baseArticle,
+        contentType: 'mdx',
+        mdxSource: 'Hello world, this is MDX content.',
+      }
+      const el = await ArticleContent({
+        article,
+        afterIntro: <div data-testid="after-intro">Intro slot</div>,
+      })
+      render(el as React.ReactElement)
+      expect(mockRenderMdxSource).toHaveBeenCalledTimes(3)
+      expect(screen.getByTestId('after-intro')).toBeInTheDocument()
+    })
+  })
 })

package/src/__tests__/ArticleDetailHero.test.tsx CHANGED Viewed

@@ -163,4 +163,34 @@ describe('ArticleDetailHero', () => {
       expect(screen.queryByText('By Jane Doe')).not.toBeInTheDocument()
     })
   })
+  describe('author authority statement (Phase 27E)', () => {
+    it('does not render a statement for a legacy configured author with no promise', () => {
+      render(<ArticleDetailHero article={baseArticle} authors={[configuredAuthor]} />)
+      expect(screen.queryByText(/Helping/)).not.toBeInTheDocument()
+    })
+    it('renders the single configured author promise as a one-sentence statement', () => {
+      const authorWithPromise: AuthorProfile = {
+        ...configuredAuthor,
+        promise: 'Helping new GMs run confident first sessions.',
+      }
+      render(<ArticleDetailHero article={baseArticle} authors={[authorWithPromise]} />)
+      expect(screen.getByText('Helping new GMs run confident first sessions.')).toBeInTheDocument()
+    })
+    it('does not render a statement when there are multiple configured authors, even with a promise', () => {
+      const authorWithPromise: AuthorProfile = {
+        ...configuredAuthor,
+        promise: 'Helping new GMs run confident first sessions.',
+      }
+      const secondAuthor: AuthorProfile = { name: 'Jamie Rivera', slug: 'jamie-rivera', bio: '' }
+      render(
+        <ArticleDetailHero article={baseArticle} authors={[authorWithPromise, secondAuthor]} />
+      )
+      expect(
+        screen.queryByText('Helping new GMs run confident first sessions.')
+      ).not.toBeInTheDocument()
+    })
+  })
 })

package/src/__tests__/ArticleNavigation.test.tsx CHANGED Viewed

@@ -2,13 +2,20 @@
  * @jest-environment jsdom
  */
 import React from 'react'
-import { render, screen } from '@testing-library/react'
+import { render, screen, fireEvent } from '@testing-library/react'
 import { ArticleNavigation } from '../ArticleNavigation'
+import type { ArticlesConfig } from '../articlesConfig'
 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>
   ),
 }))
@@ -124,4 +131,75 @@ describe('ArticleNavigation', () => {
       )
     })
   })
+  describe('path_step_advanced event (Phase 27F)', () => {
+    it('fires path_step_advanced on next-link click when pathKey/fromSlug/config are set', () => {
+      const onEvent = jest.fn()
+      const config: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Test', onEvent }
+      render(
+        <ArticleNavigation
+          previous={null}
+          next={nextArticle}
+          basePath={basePath}
+          pathKey="new-gm"
+          fromSlug="current-article"
+          config={config}
+        />
+      )
+      fireEvent.click(screen.getByRole('link', { name: /next article title/i }))
+      expect(onEvent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'path_step_advanced',
+          pathKey: 'new-gm',
+          fromSlug: 'current-article',
+          toSlug: 'next-article',
+          direction: 'next',
+        })
+      )
+    })
+    it('fires path_step_advanced on previous-link click with direction "previous"', () => {
+      const onEvent = jest.fn()
+      const config: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Test', onEvent }
+      render(
+        <ArticleNavigation
+          previous={prevArticle}
+          next={null}
+          basePath={basePath}
+          pathKey="new-gm"
+          fromSlug="current-article"
+          config={config}
+        />
+      )
+      fireEvent.click(screen.getByRole('link', { name: /previous article title/i }))
+      expect(onEvent).toHaveBeenCalledWith(
+        expect.objectContaining({ direction: 'previous', toSlug: 'previous-article' })
+      )
+    })
+    it('does not fire an event when pathKey is omitted (ordinary navigation)', () => {
+      const onEvent = jest.fn()
+      const config: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Test', onEvent }
+      render(
+        <ArticleNavigation previous={null} next={nextArticle} basePath={basePath} config={config} />
+      )
+      fireEvent.click(screen.getByRole('link', { name: /next article title/i }))
+      expect(onEvent).not.toHaveBeenCalled()
+    })
+    it('does not throw when config is omitted', () => {
+      render(
+        <ArticleNavigation
+          previous={null}
+          next={nextArticle}
+          basePath={basePath}
+          pathKey="new-gm"
+          fromSlug="current-article"
+        />
+      )
+      expect(() =>
+        fireEvent.click(screen.getByRole('link', { name: /next article title/i }))
+      ).not.toThrow()
+    })
+  })
 })