@fullstackdatasolutions/articles 0.11.0 → 1.0.0

package/src/events.ts

@@ -0,0 +1,105 @@
+// Vendor-neutral article event contract (Phase 27F). The package emits
+// these typed events at the right places in existing components/hooks and
+// hands them to `config.onEvent` - it never talks to PostHog/Plunk/any
+// analytics or email vendor directly (see package.json dependencies, which
+// stay clean of them). No PII in any payload: only slugs/IDs/enums, never
+// emails, names-as-identifiers, or free text.
+
+export type ArticleEventName =
+  | 'article_viewed'
+  | 'meaningful_read'
+  | 'author_clicked'
+  | 'cta_viewed'
+  | 'cta_clicked'
+  | 'shared'
+  | 'related_article_clicked'
+  | 'path_step_advanced'
+
+interface ArticleEventBase<Name extends ArticleEventName> {
+  name: Name
+  /** `Date.now()` at emit time. */
+  timestamp: number
+}
+
+export interface ArticleViewedEvent extends ArticleEventBase<'article_viewed'> {
+  articleSlug: string
+  category?: string
+  seriesSlug?: string
+}
+
+/** Fired once per view after the reader has spent roughly half the article's estimated read time on the page (see `ArticleViewTracker`). */
+export interface MeaningfulReadEvent extends ArticleEventBase<'meaningful_read'> {
+  articleSlug: string
+}
+
+export interface AuthorClickedEvent extends ArticleEventBase<'author_clicked'> {
+  articleSlug: string
+  authorSlug: string
+}
+
+/** `ctaId` is `primaryAction.actionId`, an `AuthorProfile.primaryCta` slug, or a `PathDefinition` key - always an app-chosen ID, never label text. */
+export interface CtaViewedEvent extends ArticleEventBase<'cta_viewed'> {
+  ctaId: string
+  articleSlug?: string
+}
+
+export interface CtaClickedEvent extends ArticleEventBase<'cta_clicked'> {
+  ctaId: string
+  articleSlug?: string
+}
+
+export interface SharedEvent extends ArticleEventBase<'shared'> {
+  articleSlug: string
+  /** Share channel key, e.g. `'linkedin'`, `'copy-link'` - never the shared URL/message text. */
+  channel: string
+}
+
+export interface RelatedArticleClickedEvent extends ArticleEventBase<'related_article_clicked'> {
+  fromSlug: string
+  toSlug: string
+  source: 'path' | 'series' | 'category'
+}
+
+export interface PathStepAdvancedEvent extends ArticleEventBase<'path_step_advanced'> {
+  pathKey: string
+  fromSlug: string
+  toSlug: string
+  direction: 'previous' | 'next'
+}
+
+export type ArticleEvent =
+  | ArticleViewedEvent
+  | MeaningfulReadEvent
+  | AuthorClickedEvent
+  | CtaViewedEvent
+  | CtaClickedEvent
+  | SharedEvent
+  | RelatedArticleClickedEvent
+  | PathStepAdvancedEvent
+
+/** Register this on `ArticlesConfig.onEvent` to receive every emitted event and translate it to your own analytics stack. */
+export type ArticleEventHandler = (event: ArticleEvent) => void
+
+// `Omit<ArticleEvent, 'timestamp'>` alone would collapse the discriminated
+// union to its common keys (TypeScript computes `keyof` on a union as the
+// intersection of each member's keys), losing every event-specific field.
+// A distributive conditional type over the naked `T` preserves each
+// member's own shape instead.
+type DistributiveOmitTimestamp<T> = T extends ArticleEvent ? Omit<T, 'timestamp'> : never
+
+/**
+ * Safely invokes `handler` with `event`, stamping `timestamp`. Swallows any
+ * error thrown by the consuming app's handler - a broken analytics
+ * integration must never break article rendering.
+ */
+export function emitArticleEvent(
+  handler: ArticleEventHandler | undefined,
+  event: DistributiveOmitTimestamp<ArticleEvent>
+): void {
+  if (!handler) return
+  try {
+    handler({ ...event, timestamp: Date.now() } as ArticleEvent)
+  } catch {
+    // consuming app's handler errors must never break rendering
+  }
+}

package/src/index.ts

@@ -11,17 +11,21 @@ export { FeaturedArticle } from './FeaturedArticle'
 export { LatestArticles } from './LatestArticles'
 export { LatestArticlesSection } from './LatestArticlesSection'
 export { CategoryArticlesPage } from './CategoryArticlesPage'
+export { SeriesArticlesPage } from './SeriesArticlesPage'
 export { AuthorArticlesPage } from './AuthorArticlesPage'
 export { AuthorCard, AuthorSocialLinks } from './AuthorCard'
 export { AuthorDetailHero } from './AuthorDetailHero'
 export { Breadcrumb, BreadcrumbSchema } from './Breadcrumb'
-export { ArticleSchema, ArticleSEO, CollectionPageSchema, FAQPageSchema } from './ArticleSchemas'
+export { ArticleSEO, CollectionPageSchema, FAQPageSchema } from './ArticleSchemas'
 
 export { ArticleSocialShare } from './ArticleSocialShare'
 export { ArticleNavigation } from './ArticleNavigation'
+export { RelatedArticlesSection } from './RelatedArticlesSection'
 export { ArticleBackLink } from './ArticleBackLink'
 export { ArticleTOC } from './ArticleTOC'
 export { ScrollToTop } from './ScrollToTop'
+export { PaginationNav } from './PaginationNav'
+export { ArticleViewTracker, CtaViewTracker } from './eventTracking'
 
 // Comments
 export { CommentsSection } from './CommentsSection'
@@ -41,6 +45,7 @@ export type {
   CategoryDescription,
   CommentsConfig,
   LinkTargetStrategy,
+  ListingPagination,
   MdxComponents,
   BreadcrumbsConfig,
   BreadcrumbLabels,
@@ -67,6 +72,26 @@ export type {
   CategoryInfo,
   FaqItem,
   HowToStep,
+  PathDefinition,
+  ProofItem,
+  RichText,
+  RichTextSection,
   TocItem,
 } from './articleTypes'
 export type { ArticleComment, ArticleCommentWithReplies } from './commentTypes'
+export type { CollectionPageItem } from './ArticleSchemas'
+export type { ListingPaginationContext } from './pagination'
+export type { AuthorPageSection } from './AuthorArticlesPage'
+export type {
+  ArticleEvent,
+  ArticleEventHandler,
+  ArticleEventName,
+  ArticleViewedEvent,
+  MeaningfulReadEvent,
+  AuthorClickedEvent,
+  CtaViewedEvent,
+  CtaClickedEvent,
+  SharedEvent,
+  RelatedArticleClickedEvent,
+  PathStepAdvancedEvent,
+} from './events'

package/src/markdown.ts

@@ -390,6 +390,47 @@ function extractHeadingItem(node: Element): TocItem | null {
   return { id, depth: Number.parseInt(match[1], 10), text }
 }
 
+export interface ContentSlotBoundaries {
+  /** Character offset (into the raw markdown source) right after the first paragraph - the "intro" boundary. */
+  introEnd: number
+  /** Character offset right after the middle paragraph - the "mid content" boundary. */
+  mid: number
+  /** Total top-level paragraph count found. */
+  paragraphCount: number
+}
+
+/**
+ * Resolves deterministic `afterIntro`/`midContent` split points from the
+ * raw markdown/MDX source's parsed AST (mdast paragraph node offsets) -
+ * never from string-splitting rendered HTML, which is fragile by
+ * construction (see Phase 27F plan notes). Returns `null` when the source
+ * has no top-level paragraphs, or fails to parse (e.g. MDX with JSX syntax
+ * remark-parse doesn't understand) - callers should treat `null` as "only
+ * `afterHero`/`afterContent` are available for this article", not throw.
+ */
+interface MdastNode {
+  type: string
+  position?: { start: { offset?: number }; end: { offset?: number } }
+  children?: MdastNode[]
+}
+
+export function getContentSlotBoundaries(markdown: string): ContentSlotBoundaries | null {
+  try {
+    const tree = remark().use(remarkParse).use(remarkGfm).parse(markdown) as unknown as MdastNode
+    const paragraphs = (tree.children ?? []).filter(
+      (node): node is MdastNode & { position: NonNullable<MdastNode['position']> } =>
+        node.type === 'paragraph' && Boolean(node.position)
+    )
+    if (paragraphs.length === 0) return null
+    const introEnd = paragraphs[0].position.end.offset ?? 0
+    const midIndex = Math.floor(paragraphs.length / 2)
+    const mid = paragraphs[midIndex].position.end.offset ?? introEnd
+    return { introEnd, mid: Math.max(mid, introEnd), paragraphCount: paragraphs.length }
+  } catch {
+    return null
+  }
+}
+
 export async function extractToc(markdown: string): Promise<TocItem[]> {
   const headings: TocItem[] = []
   const collectHeadings: Plugin<[], Root> = () => (tree: Root) => {

package/src/pagination.ts

@@ -0,0 +1,93 @@
+// Pure pagination math shared by both the server data-prep side (route files
+// slicing articles per page, generateStaticParams) and the client-safe
+// PaginationNav component (building prev/next hrefs). No fs/next dependency
+// so it's safe to import from both `index.ts` and `server.ts` entry points.
+import type { Article } from './articleTypes'
+
+export interface PaginatedArticles {
+  /** Articles belonging to this page only (already sliced). */
+  articles: Article[]
+  /** Clamped to the range `[1, totalPages]`. */
+  page: number
+  totalPages: number
+  hasPrevious: boolean
+  hasNext: boolean
+}
+
+/** Context threaded from a listing page component down into `LatestArticles`/`PaginationNav` in `'pages'` mode. */
+export interface ListingPaginationContext {
+  page: number
+  totalPages: number
+  /** Un-paginated route path for this listing, e.g. `/articles` or `/articles/category/campaigns`. */
+  basePath: string
+}
+
+export interface PaginationLinks {
+  /** This page's own canonical URL - never points back to page 1 for page > 1. */
+  canonicalUrl: string
+  prevUrl: string | null
+  nextUrl: string | null
+}
+
+export function getTotalPages(totalCount: number, pageSize: number): number {
+  if (totalCount <= 0 || pageSize <= 0) return 1
+  return Math.max(1, Math.ceil(totalCount / pageSize))
+}
+
+/** Slices `articles` to the requested page, clamping out-of-range page numbers into `[1, totalPages]`. */
+export function paginateArticles(
+  articles: Article[],
+  page: number,
+  pageSize: number
+): PaginatedArticles {
+  const totalPages = getTotalPages(articles.length, pageSize)
+  const requestedPage = Math.trunc(page) || 1
+  const clampedPage = Math.min(Math.max(requestedPage, 1), totalPages)
+  const start = (clampedPage - 1) * pageSize
+  return {
+    articles: articles.slice(start, start + pageSize),
+    page: clampedPage,
+    totalPages,
+    hasPrevious: clampedPage > 1,
+    hasNext: clampedPage < totalPages,
+  }
+}
+
+/** Page 1 is the un-suffixed `basePath` itself; page N>1 is `${basePath}/page/${N}`. */
+export function buildPageUrl(basePath: string, page: number): string {
+  const base = basePath.replace(/\/$/, '')
+  return page > 1 ? `${base}/page/${page}` : base
+}
+
+export function buildPaginationLinks(
+  basePath: string,
+  page: number,
+  totalPages: number
+): PaginationLinks {
+  return {
+    canonicalUrl: buildPageUrl(basePath, page),
+    prevUrl: page > 1 ? buildPageUrl(basePath, page - 1) : null,
+    nextUrl: page < totalPages ? buildPageUrl(basePath, page + 1) : null,
+  }
+}
+
+/**
+ * Static params for pages 2..totalPages (page 1 has no `/page/1` route - it's
+ * served by the un-paginated base route). For nested dynamic segments (e.g.
+ * `/articles/category/[category]/page/[page]`), combine this per-category in
+ * the consuming app's `generateStaticParams` - see README.
+ */
+export function generateListingPageStaticParams(totalPages: number): { page: string }[] {
+  const params: { page: string }[] = []
+  for (let page = 2; page <= totalPages; page++) params.push({ page: String(page) })
+  return params
+}
+
+export function parsePageParam(raw: string | undefined | null): number {
+  const parsed = Number.parseInt(raw ?? '', 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 1
+}
+
+export function isPageOutOfRange(page: number, totalPages: number): boolean {
+  return page < 1 || page > totalPages
+}

package/src/seoUtils.ts

@@ -6,6 +6,7 @@ import {
   getAllCategories,
   getArticleAuthors,
   getArticlesByCategory,
+  getArticlesBySeries,
   getAuthorBySlug,
   getArticleMarkdownUrl,
   getAvailableArticleSlugs,
@@ -20,6 +21,7 @@ import {
   type CategoryBreadcrumbEntry,
   type CustomBreadcrumbItem,
 } from './articlesConfig'
+import { buildPaginationLinks } from './pagination'
 import type { Article, AuthorProfile, BreadcrumbItem } from './articleTypes'
 
 function escapeXml(str: string): string {
@@ -89,6 +91,17 @@ export function generateAuthorStaticParams(config: ArticlesConfig): { author: st
   return getAllAuthors(config).map((author) => ({ author: author.slug }))
 }
 
+/** Static params for `/articles/series/[series]` - one entry per distinct `seriesSlug` found across all articles. */
+export async function generateSeriesStaticParams(
+  config?: ArticlesConfig
+): Promise<{ series: string }[]> {
+  const articles = await getAllArticles(config)
+  const seriesSlugs = new Set(
+    articles.map((article) => article.seriesSlug).filter((slug): slug is string => Boolean(slug))
+  )
+  return [...seriesSlugs].map((series) => ({ series }))
+}
+
 function resolveImageUrl(featuredImage: string, siteUrl: string): string {
   const base = siteUrl.replace(/\/$/, '')
   if (featuredImage.startsWith('http://') || featuredImage.startsWith('https://')) {
@@ -97,6 +110,41 @@ function resolveImageUrl(featuredImage: string, siteUrl: string): string {
   return `${base}/${featuredImage.replace(/^\/+/, '')}`
 }
 
+// Discovery metadata channel separation (Phase 27F): `searchTitle`/
+// `searchDescription` feed the `<title>`/meta-description channel ONLY,
+// `socialTitle`/`socialDescription`/`socialImage` feed Open Graph/Twitter
+// Card ONLY. Canonical URLs, JSON-LD (`ArticleSEO`), `ArticleCard`, and RSS
+// all keep reading `title`/`excerpt`/`featuredImage` directly and are
+// untouched by either override - each surface pulls from exactly one
+// source, never "apply every override everywhere".
+export function resolveSearchMetadata(
+  article: Pick<Article, 'title' | 'excerpt' | 'searchTitle' | 'searchDescription'>,
+  config: Pick<ArticlesConfig, 'siteName'>
+): { title: string; description: string } {
+  return {
+    title: article.searchTitle ?? article.title,
+    description:
+      article.searchDescription ??
+      article.excerpt ??
+      `Read ${article.title} on ${config.siteName}.`,
+  }
+}
+
+export function resolveSocialMetadata(
+  article: Pick<
+    Article,
+    'title' | 'excerpt' | 'featuredImage' | 'socialTitle' | 'socialDescription' | 'socialImage'
+  >,
+  siteUrl: string
+): { title: string; description: string; imageUrl: string } {
+  const image = article.socialImage ?? article.featuredImage
+  return {
+    title: article.socialTitle ?? article.title,
+    description: article.socialDescription ?? article.excerpt ?? '',
+    imageUrl: image ? resolveImageUrl(image, siteUrl) : `${siteUrl}/placeholder-logo.png`,
+  }
+}
+
 export async function generateArticleMetadata(
   slug: string,
   config: ArticlesConfig
@@ -113,24 +161,23 @@ export async function generateArticleMetadata(
   const siteUrl = config.siteUrl.replace(/\/$/, '')
   const articleUrl = `${siteUrl}/articles/${slug}`
   const canonicalUrl = article.canonicalUrl ?? articleUrl
-  const imageUrl = article.featuredImage
-    ? resolveImageUrl(article.featuredImage, siteUrl)
-    : `${siteUrl}/placeholder-logo.png`
-  const description = article.excerpt ?? `Read ${article.title} on ${config.siteName}.`
+  const search = resolveSearchMetadata(article, config)
+  const social = resolveSocialMetadata(article, siteUrl)
+  const description = search.description
   const showAuthor = config.showAuthor !== false
   const markdownUrl = getArticleMarkdownUrl(article, config)
   const authorNames = getArticleAuthors(article, config).map((author) => author.name)
 
   return {
-    title: `${article.title} | ${config.siteName}`,
+    title: `${search.title} | ${config.siteName}`,
     description,
     keywords: [...(article.tags ?? []).map((tag) => tag.toLowerCase())].join(', '),
     openGraph: {
-      title: article.title,
-      description,
+      title: social.title,
+      description: social.description || description,
       url: articleUrl,
       siteName: config.siteName,
-      images: [{ url: imageUrl, width: 1200, height: 630, alt: article.title }],
+      images: [{ url: social.imageUrl, width: 1200, height: 630, alt: social.title }],
       locale: 'en_US',
       type: 'article',
       ...(article.date && { publishedTime: article.date }),
@@ -140,9 +187,9 @@ export async function generateArticleMetadata(
     },
     twitter: {
       card: 'summary_large_image',
-      title: article.title,
-      description,
-      images: [imageUrl],
+      title: social.title,
+      description: social.description || description,
+      images: [social.imageUrl],
     },
     alternates: {
       canonical: canonicalUrl,
@@ -270,6 +317,55 @@ export async function generateCategoryMetadata(
   }
 }
 
+/** Metadata for a series landing page, analogous to `generateCategoryMetadata`. Series display name comes from the first matching article's label-only `series` string, falling back to `seriesSlug` itself. */
+export async function generateSeriesMetadata(
+  seriesSlug: string,
+  config: ArticlesConfig
+): Promise<Metadata> {
+  const articles = await getArticlesBySeries(seriesSlug, config)
+
+  if (articles.length === 0) return { title: 'Series Not Found' }
+
+  const seriesName = articles[0].series ?? seriesSlug
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const seriesUrl = `${siteUrl}/articles/series/${seriesSlug}`
+  const description = `Follow the ${seriesName} series - ${articles.length} article${articles.length === 1 ? '' : 's'} on ${config.siteName}.`
+  const title = `${seriesName} Series | ${config.siteName}`
+
+  return {
+    title,
+    description,
+    openGraph: {
+      title: `${seriesName} Series`,
+      description,
+      url: seriesUrl,
+      siteName: config.siteName,
+      images: [{ url: articles[0].featuredImage }],
+      type: 'website',
+      locale: 'en_US',
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: `${seriesName} Series`,
+      description,
+    },
+    alternates: {
+      canonical: seriesUrl,
+    },
+    robots: {
+      index: true,
+      follow: true,
+      googleBot: {
+        index: true,
+        follow: true,
+        'max-video-preview': -1,
+        'max-image-preview': 'large',
+        'max-snippet': -1,
+      },
+    },
+  }
+}
+
 export async function generateAuthorMetadata(
   authorSlug: string,
   config: ArticlesConfig
@@ -310,6 +406,97 @@ export async function generateAuthorMetadata(
   }
 }
 
+// Google Search Central's pagination guidance no longer treats rel=next/prev
+// as an indexing or ranking signal (confirmed dropped in 2019) - the
+// documented current recommendation is a unique, self-referencing canonical
+// per paginated page (never pointing page 2+ back to page 1) plus real
+// crawlable <a href> links between pages (handled by `PaginationNav`), which
+// is what these functions and that component together provide. rel=next/prev
+// itself is still valid HTML and still read by Bing and some third-party
+// tools/crawlers, so `PaginationNav` still emits it - it's just not what
+// makes these pages indexable to Google. Paginated pages stay index/follow
+// (inherited from the wrapped `generate*Metadata` call below) - the point of
+// this feature is making page 2+ indexable, not excluding it.
+function withPaginationMeta(
+  base: Metadata,
+  basePath: string,
+  page: number,
+  totalPages: number
+): Metadata {
+  // Not-found responses from the wrapped generate*Metadata call (e.g.
+  // "Category Not Found") never set `alternates` - leave them untouched
+  // rather than decorating an error title/canonical with page info.
+  if (!base.alternates) return base
+
+  const { canonicalUrl } = buildPaginationLinks(basePath, page, totalPages)
+  const pageSuffix = page > 1 ? ` - Page ${page}` : ''
+  const title = typeof base.title === 'string' ? `${base.title}${pageSuffix}` : base.title
+  const openGraph = base.openGraph
+    ? {
+        ...base.openGraph,
+        title:
+          typeof base.openGraph.title === 'string'
+            ? `${base.openGraph.title}${pageSuffix}`
+            : base.openGraph.title,
+        url: canonicalUrl,
+      }
+    : base.openGraph
+  const twitter = base.twitter
+    ? {
+        ...base.twitter,
+        title:
+          typeof base.twitter.title === 'string'
+            ? `${base.twitter.title}${pageSuffix}`
+            : base.twitter.title,
+      }
+    : base.twitter
+
+  return {
+    ...base,
+    title,
+    openGraph,
+    twitter,
+    alternates: { ...base.alternates, canonical: canonicalUrl },
+  }
+}
+
+/** Per-page metadata for `/articles/page/[page]` in `listingPagination: 'pages'` mode. Page 1 is identical to `generateArticlesIndexMetadata`. */
+export function generateArticlesIndexPageMetadata(
+  page: number,
+  totalPages: number,
+  config: ArticlesConfig
+): Metadata {
+  const base = generateArticlesIndexMetadata(config)
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  return withPaginationMeta(base, `${siteUrl}/articles`, page, totalPages)
+}
+
+/** Per-page metadata for `/articles/category/[category]/page/[page]` in `listingPagination: 'pages'` mode. */
+export async function generateCategoryPageMetadata(
+  categorySlug: string,
+  page: number,
+  totalPages: number,
+  config: ArticlesConfig
+): Promise<Metadata> {
+  const base = await generateCategoryMetadata(categorySlug, config)
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  return withPaginationMeta(base, `${siteUrl}/articles/category/${categorySlug}`, page, totalPages)
+}
+
+/** Per-page metadata for `/articles/authors/[author]/page/[page]` in `listingPagination: 'pages'` mode. */
+export async function generateAuthorPageMetadata(
+  authorSlug: string,
+  page: number,
+  totalPages: number,
+  config: ArticlesConfig
+): Promise<Metadata> {
+  const base = await generateAuthorMetadata(authorSlug, config)
+  const author = getAuthorBySlug(authorSlug, config)
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const basePath = author?.url ?? `${siteUrl}/articles/authors/${authorSlug}`
+  return withPaginationMeta(base, basePath, page, totalPages)
+}
+
 function formatCategoryName(category: string): string {
   return category
     .split('-')