@fullstackdatasolutions/articles 0.12.0 → 1.1.0

package/src/__tests__/validateArticles.test.ts

@@ -0,0 +1,312 @@
+// `../server-articles` transitively imports `../markdown`, which pulls in
+// ESM-only unified/rehype packages ts-jest's CJS transform can't load (see
+// markdown.test.ts) - mock it with faithful reimplementations of just the
+// three pure helpers `validateArticles`/`validateAllArticles` actually use.
+jest.mock('../server-articles', () => ({
+  getAllArticles: jest.fn(async () => []),
+  categoryToSlug: (category: string) =>
+    category
+      .toLowerCase()
+      .replaceAll(/\s+/g, '-')
+      .replaceAll(/[^a-z0-9-]/g, ''),
+  getAuthorBySlug: (slug: string, config: { authors?: Record<string, unknown> }) =>
+    config.authors?.[slug] ?? null,
+  getArticleAuthors: (article: { author?: string; authors?: string[] }) => {
+    const values = article.authors ?? (article.author ? [article.author] : [])
+    return values.map((name) => ({ name, slug: name, bio: '' }))
+  },
+}))
+
+import { validateArticles } from '../validateArticles'
+import type { Article } from '../articleTypes'
+import type { ArticlesConfig } from '../articlesConfig'
+
+function makeArticle(overrides: Partial<Article> = {}): Article {
+  return {
+    slug: 'test-article',
+    title: 'Test Article',
+    excerpt: 'An excerpt.',
+    date: '2025-01-01',
+    author: 'Jane Doe',
+    category: 'Campaigns',
+    categories: ['Campaigns'],
+    readTime: '3 min read',
+    featuredImage: '/img.jpg',
+    ...overrides,
+  }
+}
+
+const baseConfig: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Example' }
+
+describe('validateArticles', () => {
+  it('returns ok:true with no errors/warnings for a clean, fully-populated article set', () => {
+    const result = validateArticles([makeArticle()], baseConfig)
+    expect(result.ok).toBe(true)
+    expect(result.errors).toEqual([])
+  })
+
+  describe('duplicate canonical URLs', () => {
+    it('flags two articles sharing a canonicalUrl as an error', () => {
+      const result = validateArticles(
+        [
+          makeArticle({ slug: 'one', canonicalUrl: 'https://example.com/x' }),
+          makeArticle({ slug: 'two', canonicalUrl: 'https://example.com/x' }),
+        ],
+        baseConfig
+      )
+      expect(result.ok).toBe(false)
+      expect(result.errors).toEqual(
+        expect.arrayContaining([expect.objectContaining({ code: 'duplicate-canonical-url' })])
+      )
+    })
+
+    it('does not flag distinct canonicalUrls', () => {
+      const result = validateArticles(
+        [
+          makeArticle({ slug: 'one', canonicalUrl: 'https://example.com/x' }),
+          makeArticle({ slug: 'two', canonicalUrl: 'https://example.com/y' }),
+        ],
+        baseConfig
+      )
+      expect(result.errors).toEqual([])
+    })
+  })
+
+  describe('author references', () => {
+    const configWithAuthors: ArticlesConfig = {
+      ...baseConfig,
+      authors: {
+        'jane-doe': { name: 'Jane Doe', slug: 'jane-doe', bio: '' },
+      },
+    }
+
+    it('does not flag an article whose author matches config.authors', () => {
+      const result = validateArticles([makeArticle({ author: 'jane-doe' })], configWithAuthors)
+      expect(result.errors).toEqual([])
+    })
+
+    it('flags an author that does not match any config.authors entry', () => {
+      const result = validateArticles(
+        [makeArticle({ author: 'unknown-author' })],
+        configWithAuthors
+      )
+      expect(result.errors).toEqual(
+        expect.arrayContaining([expect.objectContaining({ code: 'unknown-author-reference' })])
+      )
+    })
+
+    it('skips the check entirely when config.authors is not configured', () => {
+      const result = validateArticles([makeArticle({ author: 'anyone' })], baseConfig)
+      expect(result.errors).toEqual([])
+    })
+  })
+
+  describe('series collisions', () => {
+    it('flags two articles in the same series with the same seriesOrder', () => {
+      const result = validateArticles(
+        [
+          makeArticle({ slug: 'one', seriesSlug: 'new-gm', seriesOrder: 1 }),
+          makeArticle({ slug: 'two', seriesSlug: 'new-gm', seriesOrder: 1 }),
+        ],
+        baseConfig
+      )
+      expect(result.errors).toEqual(
+        expect.arrayContaining([expect.objectContaining({ code: 'duplicate-series-order' })])
+      )
+    })
+
+    it('does not flag distinct seriesOrder values', () => {
+      const result = validateArticles(
+        [
+          makeArticle({ slug: 'one', seriesSlug: 'new-gm', seriesOrder: 1 }),
+          makeArticle({ slug: 'two', seriesSlug: 'new-gm', seriesOrder: 2 }),
+        ],
+        baseConfig
+      )
+      expect(result.errors).toEqual([])
+    })
+
+    it('does not flag articles missing seriesOrder', () => {
+      const result = validateArticles(
+        [
+          makeArticle({ slug: 'one', seriesSlug: 'new-gm' }),
+          makeArticle({ slug: 'two', seriesSlug: 'new-gm' }),
+        ],
+        baseConfig
+      )
+      expect(result.errors).toEqual([])
+    })
+  })
+
+  describe('path reference integrity', () => {
+    const pathConfig: ArticlesConfig = {
+      ...baseConfig,
+      paths: {
+        'new-gm': {
+          name: 'New GM Path',
+          promise: 'Confidence on session one.',
+          articles: ['one', 'missing-slug'],
+          nextAction: { label: 'Get the kit', href: '/kit' },
+        },
+      },
+    }
+
+    it('flags a path referencing a missing article', () => {
+      const result = validateArticles([makeArticle({ slug: 'one' })], pathConfig)
+      expect(result.errors).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ code: 'path-missing-article', articleSlug: 'missing-slug' }),
+        ])
+      )
+    })
+
+    it('flags a path referencing a draft article', () => {
+      const config: ArticlesConfig = {
+        ...baseConfig,
+        paths: {
+          'new-gm': {
+            name: 'New GM Path',
+            promise: 'Confidence on session one.',
+            articles: ['one', 'two'],
+            nextAction: { label: 'Get the kit', href: '/kit' },
+          },
+        },
+      }
+      const result = validateArticles(
+        [makeArticle({ slug: 'one' }), makeArticle({ slug: 'two', draft: true })],
+        config
+      )
+      expect(result.errors).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ code: 'path-references-draft', articleSlug: 'two' }),
+        ])
+      )
+    })
+
+    it('flags an empty path', () => {
+      const config: ArticlesConfig = {
+        ...baseConfig,
+        paths: {
+          empty: {
+            name: 'Empty Path',
+            promise: 'Nothing here.',
+            articles: [],
+            nextAction: { label: 'Go', href: '/go' },
+          },
+        },
+      }
+      const result = validateArticles([makeArticle()], config)
+      expect(result.errors).toEqual(
+        expect.arrayContaining([expect.objectContaining({ code: 'empty-path', pathKey: 'empty' })])
+      )
+    })
+
+    it('does not flag a fully valid path', () => {
+      const result = validateArticles(
+        [makeArticle({ slug: 'one' }), makeArticle({ slug: 'missing-slug' })],
+        pathConfig
+      )
+      expect(result.errors).toEqual([])
+    })
+  })
+
+  describe('unsafe URLs', () => {
+    it('flags a javascript: URL in a Path nextAction.href', () => {
+      const config: ArticlesConfig = {
+        ...baseConfig,
+        paths: {
+          bad: {
+            name: 'Bad Path',
+            promise: 'x',
+            articles: ['one'],
+            nextAction: { label: 'Go', href: 'javascript:alert(1)' },
+          },
+        },
+      }
+      const result = validateArticles([makeArticle({ slug: 'one' })], config)
+      expect(result.errors).toEqual(
+        expect.arrayContaining([expect.objectContaining({ code: 'unsafe-url', pathKey: 'bad' })])
+      )
+    })
+
+    it('flags a javascript: URL in an author primaryCta.href', () => {
+      const config: ArticlesConfig = {
+        ...baseConfig,
+        authors: {
+          jane: {
+            name: 'Jane',
+            slug: 'jane',
+            bio: '',
+            primaryCta: { label: 'Go', href: 'javascript:alert(1)' },
+          },
+        },
+      }
+      const result = validateArticles([makeArticle()], config)
+      expect(result.errors).toEqual(
+        expect.arrayContaining([expect.objectContaining({ code: 'unsafe-url' })])
+      )
+    })
+
+    it('does not flag ordinary https:// URLs', () => {
+      const config: ArticlesConfig = {
+        ...baseConfig,
+        paths: {
+          ok: {
+            name: 'OK Path',
+            promise: 'x',
+            articles: ['one'],
+            nextAction: { label: 'Go', href: 'https://example.com/kit' },
+          },
+        },
+      }
+      const result = validateArticles([makeArticle({ slug: 'one' })], config)
+      expect(result.errors).toEqual([])
+    })
+  })
+
+  describe('warnings', () => {
+    it('warns on a missing excerpt', () => {
+      const result = validateArticles([makeArticle({ excerpt: '' })], baseConfig)
+      expect(result.warnings).toEqual(
+        expect.arrayContaining([expect.objectContaining({ code: 'missing-excerpt' })])
+      )
+    })
+
+    it('warns on a missing date', () => {
+      const result = validateArticles([makeArticle({ date: undefined })], baseConfig)
+      expect(result.warnings).toEqual(
+        expect.arrayContaining([expect.objectContaining({ code: 'missing-date' })])
+      )
+    })
+
+    it('warns when searchTitle exceeds the recommended length', () => {
+      const result = validateArticles([makeArticle({ searchTitle: 'x'.repeat(61) })], baseConfig)
+      expect(result.warnings).toEqual(
+        expect.arrayContaining([expect.objectContaining({ code: 'search-title-too-long' })])
+      )
+    })
+
+    it('does not warn when searchTitle is within the recommended length', () => {
+      const result = validateArticles([makeArticle({ searchTitle: 'Short title' })], baseConfig)
+      expect(result.warnings).toEqual([])
+    })
+
+    it('warns on category slug collisions', () => {
+      const result = validateArticles(
+        [
+          makeArticle({ slug: 'one', categories: ['Game Masters'] }),
+          makeArticle({ slug: 'two', categories: ['game-masters'] }),
+        ],
+        baseConfig
+      )
+      expect(result.warnings).toEqual(
+        expect.arrayContaining([expect.objectContaining({ code: 'category-slug-collision' })])
+      )
+    })
+
+    it('warnings never affect ok', () => {
+      const result = validateArticles([makeArticle({ excerpt: '' })], baseConfig)
+      expect(result.ok).toBe(true)
+    })
+  })
+})

package/src/articleTypes.ts

@@ -22,9 +22,18 @@ export interface Article {
   lastmod?: string
   author: string
   authors?: string[]
+  // Resolved from `author`/`authors` against `config.authors` at fetch time
+  // (see `getArticleSummary`) so cards can link/avatar without re-resolving
+  // client-side. Unset when no configured author profile matches.
+  authorSlug?: string
+  authorAvatar?: string
   category: string
   categories: string[]
   readTime: string
+  // Word count of the raw markdown body, computed alongside readTime from
+  // the same reading-time pass (no extra parsing cost). Used for the
+  // Article schema's wordCount field.
+  wordCount?: number
   featuredImage: string
   tags?: string[]
   content?: string
@@ -38,7 +47,66 @@ export interface Article {
   canonicalUrl?: string
   articleType?: string
   series?: string
+  /**
+   * Machine-safe series identifier (Phase 27F) - separate from the
+   * label-only `series` string, which stays supported unchanged for
+   * consumers who only set it. `seriesSlug`/`seriesOrder` turn `series` into
+   * a navigable reader journey via `getArticlesBySeries`/
+   * `getAdjacentArticlesInSeries`. Both optional; omitted on every article
+   * reproduces pre-27F behavior exactly.
+   */
+  seriesSlug?: string
+  /** Position within `seriesSlug`, ascending. Ties/omissions fall back to date order (see `getArticlesBySeries`). */
+  seriesOrder?: number
   aiCrawl?: boolean
+  /**
+   * Discovery metadata overrides (Phase 27F), all optional and additive.
+   * `searchTitle`/`searchDescription` feed `generateArticleMetadata`'s
+   * `<title>`/meta description ONLY - canonical URLs, JSON-LD, RSS, and
+   * `ArticleCard` keep reading `title`/`excerpt` unchanged. `socialTitle`/
+   * `socialDescription`/`socialImage` feed Open Graph/Twitter Card output
+   * ONLY, falling back to `title`/`excerpt`/`featuredImage`. See
+   * `resolveSearchMetadata`/`resolveSocialMetadata` in `seoUtils.ts` for the
+   * exact fallback/sanitization rules.
+   */
+  searchTitle?: string
+  searchDescription?: string
+  socialTitle?: string
+  socialDescription?: string
+  socialImage?: string
+  /**
+   * References an app-owned CTA/offer by opaque ID (Phase 27F). The package
+   * never interprets `actionId` - it doesn't know about forms, email
+   * providers, or analytics vendors. The consuming app looks `actionId` up
+   * in its own registry when rendering a detail-page slot (see
+   * `ArticleContent`'s `afterHero`/`afterIntro`/`midContent`/`afterContent`
+   * props); an unmatched ID must render nothing, never throw.
+   */
+  primaryAction?: {
+    actionId: string
+  }
+}
+
+/**
+ * A "start here" curated reader journey that can cross series/categories -
+ * a distinct primitive from the label-only `series` field/`seriesSlug`
+ * pair (Phase 27F). Configured via `ArticlesConfig.paths`, keyed by an
+ * app-chosen path key. `articles` is an ordered list of slugs; every
+ * referenced slug must exist and not be `draft: true` - enforced by
+ * `validateArticles`, not silently at render time.
+ */
+export interface PathDefinition {
+  /** Display name, e.g. "New GM Starter Path". */
+  name: string
+  /** One-sentence value proposition shown on the path's landing/step UI. */
+  promise: string
+  /** Ordered article slugs making up the journey. */
+  articles: string[]
+  /** The one next action offered once a reader completes the path. */
+  nextAction: {
+    label: string
+    href: string
+  }
 }
 
 export interface CategoryInfo {
@@ -66,6 +134,26 @@ export interface AuthorSocial {
   other?: Record<string, string>
 }
 
+/**
+ * One headed block of structured long-form content (used by
+ * `AuthorProfile.originStory`). An array of these, not a single HTML blob,
+ * so consuming apps can render/style each block themselves rather than
+ * `dangerouslySetInnerHTML`-ing raw markup.
+ */
+export interface RichTextSection {
+  heading?: string
+  paragraphs: string[]
+}
+
+export type RichText = RichTextSection[]
+
+/** A single sourceable claim used by `AuthorProfile.proof`. */
+export interface ProofItem {
+  claim: string
+  source?: string
+  url?: string
+}
+
 export interface AuthorProfile {
   name: string
   slug: string
@@ -73,6 +161,27 @@ export interface AuthorProfile {
   avatar?: string
   url?: string
   social?: AuthorSocial
+  /** Short one-line audience promise, e.g. "Helping new GMs run confident first sessions." Optional, additive - omitted fields never change existing rendering. */
+  promise?: string
+  /** Structured long-form origin story - see `RichText`/`RichTextSection`. */
+  originStory?: RichText
+  /** Who this author's content/work is for, e.g. "New game masters", "Streaming DMs". */
+  servesWho?: string[]
+  /** Core beliefs/approach statements. */
+  principles?: string[]
+  /**
+   * Experience/credential claims (e.g. "10+ years running published campaigns").
+   * Intentionally never included in Person JSON-LD - unverifiable claims don't
+   * belong in structured data (see `getPersonSchema`/`getPersonSchemas`).
+   */
+  credentials?: string[]
+  /** Concrete, sourceable proof points. */
+  proof?: ProofItem[]
+  /** Primary call-to-action rendered on the author's page. */
+  primaryCta?: {
+    label: string
+    href: string
+  }
 }
 
 export interface BreadcrumbItem {

package/src/articlesConfig.ts

@@ -1,5 +1,6 @@
 import type { ComponentType } from 'react'
-import type { AuthorProfile } from './articleTypes'
+import type { AuthorProfile, PathDefinition } from './articleTypes'
+import type { ArticleEventHandler } from './events'
 
 /** Keys for each renderable section of the articles listing page. */
 export type ArticlesSection =
@@ -17,6 +18,14 @@ export type ArticlesSection =
 export interface ArticlesTheme {
   /** Font family for the articles section. Example: `"'Inter', sans-serif"` */
   fontFamily?: string
+  /**
+   * Font family for headings only (article title, card titles, section
+   * headings) - falls back to `fontFamily` when omitted. Lets a site use a
+   * distinct display face for headings (e.g. a serif) while keeping a
+   * separate body font, without hardcoding either into the package.
+   * Example: `"'Cinzel', serif"`
+   */
+  headerFontFamily?: string
   /** Color for article card titles and section headings. Example: `'#111827'` */
   headerColor?: string
   /** Color for body and excerpt text. Example: `'#6b7280'` */
@@ -73,6 +82,19 @@ export interface HeroConfig {
 /** Controls how article body links set target/rel attributes. */
 export type LinkTargetStrategy = 'external-new-tab' | 'all-new-tab' | 'same-tab'
 
+/**
+ * Controls how listing pages (the articles index, category pages, author
+ * pages) surface articles beyond the first `pageSize`.
+ * - `'load-more'` (default): client-only "Load more" button, no URL change.
+ *   Byte-for-byte identical to pre-27D behavior.
+ * - `'pages'`: real, directly-navigable paginated routes (`/articles/page/2`,
+ *   `/articles/category/[category]/page/2`, `/articles/authors/[author]/page/2`)
+ *   with SSR content, prev/next links, and per-page canonical metadata. The
+ *   route *files* live in the consuming app - see the pagination primitives
+ *   exported from `./server` and the `PaginationNav` component.
+ */
+export type ListingPagination = 'load-more' | 'pages'
+
 /** React components that article MDX bodies can reference by JSX tag name. */
 export type MdxComponents = Record<string, ComponentType<never>>
 
@@ -166,6 +188,28 @@ export interface ArticlesConfig {
   linkTargetStrategy?: LinkTargetStrategy
   /** Extra components exposed to article MDX bodies by JSX tag name. */
   mdxComponents?: MdxComponents
+  /**
+   * Chooses how listing pages surface articles beyond the first `pageSize`.
+   * Default: `'load-more'` (unchanged pre-27D behavior). Set to `'pages'` to
+   * opt into real, crawlable paginated routes instead.
+   */
+  listingPagination?: ListingPagination
+  /**
+   * "Start here" curated reader journeys, keyed by an app-chosen path key.
+   * Distinct from the label-only `series` field/`seriesSlug` pair - a path
+   * can cross series and categories. Every `PathDefinition.articles` slug
+   * must exist and not be `draft: true`; validate with `validateArticles`
+   * before publishing, since a broken reference produces a dead journey
+   * step rather than a build-time failure otherwise.
+   */
+  paths?: Record<string, PathDefinition>
+  /**
+   * Vendor-neutral event callback (Phase 27F). Fired by components/hooks at
+   * meaningful reader-journey moments (see `ArticleEvent` in `events.ts`).
+   * No PII in any payload. The package never talks to an analytics/email
+   * vendor directly - translate events to PostHog/etc. in this callback.
+   */
+  onEvent?: ArticleEventHandler
 }
 
 export const DEFAULT_PAGE_SIZE = 6

package/src/eventTracking.tsx

@@ -0,0 +1,97 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+import type { ReactNode } from 'react'
+import { emitArticleEvent } from './events'
+import type { ArticlesConfig } from './articlesConfig'
+import type { Article } from './articleTypes'
+
+type ArticleViewTrackerProps = Readonly<{
+  article: Pick<Article, 'slug'> & Partial<Pick<Article, 'category' | 'seriesSlug' | 'wordCount'>>
+  config?: ArticlesConfig
+}>
+
+const AVERAGE_WORDS_PER_MINUTE = 200
+const DEFAULT_MEANINGFUL_READ_MS = 15_000
+
+/**
+ * Renders nothing - fires `article_viewed` on mount and `meaningful_read`
+ * once, after roughly half the article's estimated read time has elapsed
+ * (a deterministic, testable timing approximation rather than scroll-depth
+ * tracking, which this package has no reliable cross-app way to measure
+ * since it doesn't own the article body's scroll container). Place once on
+ * the article detail page alongside `ArticleContent`.
+ */
+export function ArticleViewTracker({ article, config }: ArticleViewTrackerProps) {
+  const firedMeaningfulRead = useRef(false)
+
+  useEffect(() => {
+    emitArticleEvent(config?.onEvent, {
+      name: 'article_viewed',
+      articleSlug: article.slug,
+      category: article.category,
+      seriesSlug: article.seriesSlug,
+    })
+
+    const estimatedMs = article.wordCount
+      ? (article.wordCount / AVERAGE_WORDS_PER_MINUTE) * 60_000 * 0.5
+      : DEFAULT_MEANINGFUL_READ_MS
+    const timer = setTimeout(() => {
+      if (firedMeaningfulRead.current) return
+      firedMeaningfulRead.current = true
+      emitArticleEvent(config?.onEvent, { name: 'meaningful_read', articleSlug: article.slug })
+    }, estimatedMs)
+
+    return () => clearTimeout(timer)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [article.slug])
+
+  return null
+}
+
+type CtaViewTrackerProps = Readonly<{
+  /** Opaque CTA/offer ID - never label text (no PII/marketing copy in event payloads). */
+  ctaId: string
+  articleSlug?: string
+  config?: ArticlesConfig
+  children: ReactNode
+}>
+
+/**
+ * Wraps any CTA block and fires `cta_viewed` once, the first time at least
+ * half of it scrolls into the viewport (`IntersectionObserver`). Falls back
+ * to firing immediately when `IntersectionObserver` isn't available (older
+ * browsers, non-DOM test environments) rather than never firing.
+ */
+export function CtaViewTracker({ ctaId, articleSlug, config, children }: CtaViewTrackerProps) {
+  const ref = useRef<HTMLDivElement | null>(null)
+  const fired = useRef(false)
+
+  useEffect(() => {
+    const node = ref.current
+    if (!node) return
+
+    function fire() {
+      if (fired.current) return
+      fired.current = true
+      emitArticleEvent(config?.onEvent, { name: 'cta_viewed', ctaId, articleSlug })
+    }
+
+    if (typeof IntersectionObserver === 'undefined') {
+      fire()
+      return
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) fire()
+      },
+      { threshold: 0.5 }
+    )
+    observer.observe(node)
+    return () => observer.disconnect()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ctaId, articleSlug])
+
+  return <div ref={ref}>{children}</div>
+}