@fullstackdatasolutions/articles 0.12.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackdatasolutions/articles",
-  "version": "0.12.0",
+  "version": "1.1.0",
   "private": false,
   "license": "MIT",
   "funding": {

package/src/ArticleCard.tsx

@@ -3,13 +3,18 @@
 import Image from 'next/image'
 import Link from 'next/link'
 import { ArrowRight, Calendar, Clock } from 'lucide-react'
+import { getInitials } from './AuthorCard'
+import { emitArticleEvent } from './events'
 import type { Article } from './articleTypes'
+import type { ArticlesConfig } from './articlesConfig'
 
 type ArticleCardProps = Readonly<{
   article: Article
+  /** Optional (Phase 27F) - when passed with `config.onEvent`, clicking the author link fires an `author_clicked` event. Omitting it changes nothing. */
+  config?: ArticlesConfig
 }>
 
-export function ArticleCard({ article }: ArticleCardProps) {
+export function ArticleCard({ article, config }: ArticleCardProps) {
   return (
     <div className="rounded-lg border border-border bg-card text-card-foreground shadow-sm hover:shadow-lg transition-shadow duration-300">
       <div className="p-0">
@@ -27,15 +32,46 @@ export function ArticleCard({ article }: ArticleCardProps) {
             {article.category}
           </span>
         </div>
-        <h3 className="text-lg font-semibold leading-none tracking-tight mb-2">
-          <Link
-            href={`/articles/${article.slug}`}
-            className="hover:text-indigo-600 transition-colors"
-          >
+        <h3
+          className="text-lg font-semibold leading-none tracking-tight mb-2"
+          style={{ fontFamily: config?.theme?.headerFontFamily }}
+        >
+          <Link href={`/articles/${article.slug}`} className="hover:text-primary transition-colors">
             {article.title}
           </Link>
         </h3>
         <p className="text-muted-foreground mb-4 line-clamp-3">{article.excerpt}</p>
+        {article.authorSlug && (
+          <Link
+            href={`/articles/authors/${article.authorSlug}`}
+            className="mb-4 flex items-center gap-2 text-sm text-muted-foreground hover:text-primary transition-colors"
+            onClick={() =>
+              emitArticleEvent(config?.onEvent, {
+                name: 'author_clicked',
+                articleSlug: article.slug,
+                authorSlug: article.authorSlug as string,
+              })
+            }
+          >
+            {article.authorAvatar ? (
+              <Image
+                src={article.authorAvatar}
+                alt=""
+                width={24}
+                height={24}
+                className="h-6 w-6 rounded-full object-cover"
+              />
+            ) : (
+              <span
+                aria-hidden="true"
+                className="flex h-6 w-6 shrink-0 items-center justify-center rounded-full bg-muted text-[10px] font-semibold text-muted-foreground"
+              >
+                {getInitials(article.author)}
+              </span>
+            )}
+            <span>{article.author}</span>
+          </Link>
+        )}
         <div className="flex items-center justify-between text-sm text-muted-foreground border-t pt-4">
           <div className="flex items-center gap-3">
             {article.date && (

package/src/ArticleContent.tsx

@@ -1,19 +1,158 @@
+import type { ReactNode } from 'react'
 import { renderMdxSource } from './renderMdx'
+import { markdownToHtml, getContentSlotBoundaries } from './markdown'
 import type { Article } from './articleTypes'
 import type { ArticlesConfig } from './articlesConfig'
 
+/**
+ * Sanitized, non-PII context passed into `ArticleContent`'s slot render
+ * props - deliberately a narrow subset of `Article`, not the whole object
+ * (no raw `content`/`mdxSource`, no author email or anything author-PII).
+ */
+export interface ArticleSlotContext {
+  slug: string
+  title: string
+  category: string
+  tags: string[]
+  readTime: string
+  wordCount?: number
+  authorSlug?: string
+  seriesSlug?: string
+  primaryActionId?: string
+}
+
+export type ArticleSlotContent = ReactNode | ((context: ArticleSlotContext) => ReactNode)
+
+function buildSlotContext(article: Article): ArticleSlotContext {
+  return {
+    slug: article.slug,
+    title: article.title,
+    category: article.category,
+    tags: article.tags ?? [],
+    readTime: article.readTime,
+    wordCount: article.wordCount,
+    authorSlug: article.authorSlug,
+    seriesSlug: article.seriesSlug,
+    primaryActionId: article.primaryAction?.actionId,
+  }
+}
+
+function resolveSlot(slot: ArticleSlotContent | undefined, context: ArticleSlotContext): ReactNode {
+  if (slot === undefined) return null
+  return typeof slot === 'function' ? slot(context) : slot
+}
+
 type ArticleContentProps = Readonly<{
   article: Article
   className?: string
   config?: ArticlesConfig
+  /** Rendered immediately before the article body - the "around the body, not inside it" counterpart to `config.mdxComponents` (which places content *inside* MDX bodies). */
+  afterHero?: ArticleSlotContent
+  /** Rendered right after the first paragraph, resolved deterministically from the parsed AST (see `getContentSlotBoundaries`). Falls back to not rendering (never a brittle string split) when the source has no detectable paragraphs, e.g. MDX using JSX-heavy syntax remark-parse can't read as plain markdown. */
+  afterIntro?: ArticleSlotContent
+  /** Rendered after roughly the middle paragraph. Same fallback behavior as `afterIntro`. */
+  midContent?: ArticleSlotContent
+  /** Rendered immediately after the article body. */
+  afterContent?: ArticleSlotContent
 }>
 
-export async function ArticleContent({ article, className, config }: ArticleContentProps) {
-  if (article.contentType === 'mdx' && article.mdxSource) {
-    const content = await renderMdxSource(article.mdxSource, `/articles/${article.slug}`, config)
-    return <div className={className}>{content}</div>
+async function renderSegment(
+  markdown: string,
+  contentType: Article['contentType'],
+  slug: string,
+  config?: ArticlesConfig
+): Promise<ReactNode> {
+  if (!markdown.trim()) return null
+  if (contentType === 'mdx') {
+    return renderMdxSource(markdown, `/articles/${slug}`, config)
+  }
+  const html = await markdownToHtml(markdown, slug, config)
+  return <div dangerouslySetInnerHTML={{ __html: html }} />
+}
+
+export async function ArticleContent({
+  article,
+  className,
+  config,
+  afterHero,
+  afterIntro,
+  midContent,
+  afterContent,
+}: ArticleContentProps) {
+  // Legacy path (Phase 27F: zero slot props passed) reproduces the exact
+  // pre-27F markup - a single outer div, `dangerouslySetInnerHTML` set
+  // directly on it for the HTML path - rather than the slot-aware wrapper
+  // below, so existing consumers/tests see byte-for-byte identical output.
+  const hasAnySlot =
+    afterHero !== undefined ||
+    afterIntro !== undefined ||
+    midContent !== undefined ||
+    afterContent !== undefined
+  if (!hasAnySlot) {
+    if (article.contentType === 'mdx' && article.mdxSource) {
+      const content = await renderMdxSource(article.mdxSource, `/articles/${article.slug}`, config)
+      return <div className={className}>{content}</div>
+    }
+    return (
+      <div className={className} dangerouslySetInnerHTML={{ __html: article.htmlContent || '' }} />
+    )
   }
+
+  const slotContext = buildSlotContext(article)
+  const heroNode = resolveSlot(afterHero, slotContext)
+  const introNode = resolveSlot(afterIntro, slotContext)
+  const midNode = resolveSlot(midContent, slotContext)
+  const contentNode = resolveSlot(afterContent, slotContext)
+
+  const needsSplit = Boolean(introNode || midNode)
+  const rawSource =
+    article.contentType === 'mdx' ? article.mdxSource : (article.content ?? undefined)
+
+  if (needsSplit && rawSource) {
+    const boundaries = getContentSlotBoundaries(rawSource)
+    if (boundaries) {
+      try {
+        const introSegment = rawSource.slice(0, boundaries.introEnd)
+        const midSegment = rawSource.slice(boundaries.introEnd, boundaries.mid)
+        const restSegment = rawSource.slice(boundaries.mid)
+        const [introHtml, midHtml, restHtml] = await Promise.all([
+          renderSegment(introSegment, article.contentType, article.slug, config),
+          renderSegment(midSegment, article.contentType, article.slug, config),
+          renderSegment(restSegment, article.contentType, article.slug, config),
+        ])
+        return (
+          <div className={className}>
+            {heroNode}
+            {introHtml}
+            {introNode}
+            {midHtml}
+            {midNode}
+            {restHtml}
+            {contentNode}
+          </div>
+        )
+      } catch {
+        // Splitting the MDX source failed to evaluate (e.g. a JSX block
+        // straddled a paragraph boundary) - fall through to the
+        // whole-document render below rather than throwing. `afterIntro`/
+        // `midContent` are silently omitted for this article; `afterHero`/
+        // `afterContent` still render.
+      }
+    }
+  }
+
+  const wholeBody =
+    article.contentType === 'mdx' && article.mdxSource ? (
+      await renderMdxSource(article.mdxSource, `/articles/${article.slug}`, config)
+    ) : (
+      <div dangerouslySetInnerHTML={{ __html: article.htmlContent || '' }} />
+    )
+
   return (
-    <div className={className} dangerouslySetInnerHTML={{ __html: article.htmlContent || '' }} />
+    <div className={className}>
+      {heroNode}
+      {wholeBody}
+      {contentNode}
+    </div>
   )
 }

package/src/ArticleDetailHero.tsx

@@ -3,6 +3,7 @@ import Image from 'next/image'
 import Link from 'next/link'
 import { Calendar, Clock, User } from 'lucide-react'
 import type { Article, AuthorProfile } from './articleTypes'
+import type { ArticlesConfig } from './articlesConfig'
 
 type ArticleDetailHeroProps = Readonly<{
   article: Article
@@ -10,6 +11,8 @@ type ArticleDetailHeroProps = Readonly<{
   showDate?: boolean
   showAuthor?: boolean
   authors?: AuthorProfile[]
+  /** Optional - when `config.theme.headerFontFamily` is set, applies it to the title. */
+  config?: ArticlesConfig
 }>
 
 function toSlug(cat: string): string {
@@ -25,6 +28,7 @@ export function ArticleDetailHero({
   showDate = false,
   showAuthor = true,
   authors = [],
+  config,
 }: ArticleDetailHeroProps) {
   const showConfiguredAuthors = showAuthor && authors.length > 0
   const showLegacyAuthor = showAuthor && authors.length === 0 && article.author.trim().length > 0
@@ -98,7 +102,12 @@ export function ArticleDetailHero({
             )}
           </div>
         )}
-        <h1 className="text-4xl md:text-5xl font-bold mb-4">{article.title}</h1>
+        <h1
+          className="text-4xl md:text-5xl font-bold mb-4"
+          style={{ fontFamily: config?.theme?.headerFontFamily }}
+        >
+          {article.title}
+        </h1>
         <div
           style={{
             display: 'flex',
@@ -145,6 +154,29 @@ export function ArticleDetailHero({
             </div>
           )}
         </div>
+        {/*
+          Phase 27E: one-sentence author authority statement, sourced from
+          the configured author's `promise`. Scoped here (the article detail
+          byline) rather than `ArticleCard` - a listing grid repeats the same
+          author across many cards, so a second line of text per card adds
+          clutter without adding trust; the detail page byline is the one
+          high-intent placement where establishing authority right as a
+          reader commits to the article actually helps. Only renders for a
+          single configured author (ambiguous which author's promise "wins"
+          with more than one) and only when `promise` is set - omitted
+          entirely otherwise, so this never changes existing output.
+        */}
+        {showConfiguredAuthors && authors.length === 1 && authors[0].promise && (
+          <p
+            style={{
+              marginTop: '0.75rem',
+              fontSize: '0.9375rem',
+              color: 'rgba(255,255,255,0.85)',
+            }}
+          >
+            {authors[0].promise}
+          </p>
+        )}
       </div>
     </section>
   )

package/src/ArticleNavigation.tsx

@@ -1,19 +1,48 @@
 import Link from 'next/link'
 import { ChevronLeft, ChevronRight } from 'lucide-react'
+import { emitArticleEvent } from './events'
+import type { ArticlesConfig } from './articlesConfig'
 
 interface ArticleNavigationProps {
   readonly previous: { slug: string; title: string } | null
   readonly next: { slug: string; title: string } | null
   readonly basePath: string
+  /** The article slug this navigation is shown on. Combined with `pathKey`, enables `path_step_advanced` events. */
+  readonly fromSlug?: string
+  /**
+   * Set when this navigation walks a configured `Path` (as opposed to plain
+   * chronological/series adjacency) - fires `path_step_advanced` on click.
+   * Omit for ordinary previous/next navigation; no event fires without it.
+   */
+  readonly pathKey?: string
+  readonly config?: ArticlesConfig
 }
 
 function truncateTitle(title: string, maxLength = 60): string {
   return title.length > maxLength ? `${title.substring(0, maxLength)}...` : title
 }
 
-export function ArticleNavigation({ previous, next, basePath }: ArticleNavigationProps) {
+export function ArticleNavigation({
+  previous,
+  next,
+  basePath,
+  fromSlug,
+  pathKey,
+  config,
+}: ArticleNavigationProps) {
   if (!previous && !next) return null
 
+  function emitStep(toSlug: string, direction: 'previous' | 'next') {
+    if (!pathKey || !fromSlug) return
+    emitArticleEvent(config?.onEvent, {
+      name: 'path_step_advanced',
+      pathKey,
+      fromSlug,
+      toSlug,
+      direction,
+    })
+  }
+
   return (
     <nav className="mt-12 pt-8 border-t border-border" aria-label="Article navigation">
       <div className="flex justify-between gap-4">
@@ -21,6 +50,7 @@ export function ArticleNavigation({ previous, next, basePath }: ArticleNavigatio
           {previous && (
             <Link
               href={`${basePath}/${previous.slug}`}
+              onClick={() => emitStep(previous.slug, 'previous')}
               className="group flex items-center gap-3 p-4 rounded-lg border border-border hover:border-primary/20 hover:bg-muted/50 transition-colors"
             >
               <ChevronLeft className="h-5 w-5 text-muted-foreground group-hover:text-primary shrink-0" />
@@ -38,6 +68,7 @@ export function ArticleNavigation({ previous, next, basePath }: ArticleNavigatio
           {next && (
             <Link
               href={`${basePath}/${next.slug}`}
+              onClick={() => emitStep(next.slug, 'next')}
               className="group flex items-center justify-end gap-3 p-4 rounded-lg border border-border hover:border-primary/20 hover:bg-muted/50 transition-colors"
             >
               <div className="min-w-0 flex-1 text-right">

package/src/ArticleSchemas.tsx

@@ -1,59 +1,35 @@
+import type { ArticlesConfig } from './articlesConfig'
 import type { Article, AuthorProfile, FaqItem, HowToStep } from './articleTypes'
-import { getAuthorSameAs } from './authorUtils'
+import { getAuthorAvatar, getAuthorSameAs } from './authorUtils'
 
 export { BreadcrumbSchema } from './Breadcrumb'
 
-type ArticleSchemaProps = Readonly<{
-  article: Article
-  articleUrl: string
-  siteName: string
-  showAuthor?: boolean
-  authors?: AuthorProfile[]
-}>
-
-function getPersonSchemas(article: Article, authors?: readonly AuthorProfile[]) {
+function getPersonSchemas(
+  article: Article,
+  authors?: readonly AuthorProfile[],
+  config?: ArticlesConfig
+) {
   let resolvedAuthors: AuthorProfile[] = []
   if (authors?.length) {
     resolvedAuthors = [...authors]
   } else if (article.author) {
     resolvedAuthors = [{ name: article.author, slug: '', bio: '' }]
   }
+  // Phase 27E audit: same decision as AuthorArticlesPage's getPersonSchema -
+  // the new AuthorProfile fields (promise/servesWho/principles/credentials/
+  // proof) are marketing copy, audience segments, or unverifiable claims, not
+  // schema.org-appropriate facts, so none of them are added here. `url`/
+  // `image`/`sameAs` stay sourced exactly as before (author.url, resolved
+  // avatar, approved social links only).
   return resolvedAuthors.map((author) => ({
     '@type': 'Person',
     name: author.name,
     ...(author.url && { url: author.url }),
+    ...(getAuthorAvatar(author, config) && { image: getAuthorAvatar(author, config) }),
     ...(getAuthorSameAs(author).length > 0 && { sameAs: getAuthorSameAs(author) }),
   }))
 }
 
-export function ArticleSchema({
-  article,
-  articleUrl,
-  siteName,
-  showAuthor = true,
-  authors,
-}: ArticleSchemaProps) {
-  const personSchemas = getPersonSchemas(article, authors)
-  const schema = {
-    '@context': 'https://schema.org',
-    '@type': 'Article',
-    headline: article.title,
-    description: article.excerpt,
-    image: article.featuredImage,
-    ...(article.date && { datePublished: new Date(article.date).toISOString() }),
-    ...(showAuthor && personSchemas.length > 0 && { author: personSchemas }),
-    publisher: { '@type': 'Organization', name: siteName },
-    mainEntityOfPage: { '@type': 'WebPage', '@id': articleUrl },
-  }
-
-  return (
-    <script
-      type="application/ld+json"
-      dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
-    />
-  )
-}
-
 type ArticleSEOProps = Readonly<{
   article: Article
   articleUrl: string
@@ -61,6 +37,7 @@ type ArticleSEOProps = Readonly<{
   siteLogo?: string
   showAuthor?: boolean
   authors?: AuthorProfile[]
+  config?: ArticlesConfig
 }>
 
 export function ArticleSEO({
@@ -70,10 +47,11 @@ export function ArticleSEO({
   siteLogo,
   showAuthor = true,
   authors,
+  config,
 }: ArticleSEOProps) {
   const publishedAt = article.date ? new Date(article.date).toISOString() : undefined
   const modifiedAt = article.lastmod ? new Date(article.lastmod).toISOString() : publishedAt
-  const personSchemas = getPersonSchemas(article, authors)
+  const personSchemas = getPersonSchemas(article, authors, config)
 
   const structuredData = {
     '@context': 'https://schema.org',
@@ -92,6 +70,9 @@ export function ArticleSEO({
       ...(siteLogo && { logo: { '@type': 'ImageObject', url: siteLogo } }),
     },
     description: article.excerpt,
+    articleSection: article.category,
+    ...(article.tags && article.tags.length > 0 && { keywords: article.tags.join(', ') }),
+    ...(article.wordCount !== undefined && { wordCount: article.wordCount }),
     ...(article.series && { isPartOf: { '@type': 'Blog', name: article.series } }),
   }
 
@@ -160,11 +141,21 @@ export function FAQPageSchema({ items }: FAQPageSchemaProps) {
   )
 }
 
+export type CollectionPageItem = Readonly<{
+  position: number
+  url: string
+  name: string
+}>
+
 type CollectionPageSchemaProps = Readonly<{
   title: string
   description: string
   url: string
   articleCount: number
+  // The articles actually linked in the page's initial HTML (e.g. the first
+  // pageSize before "Load more"/pagination), not necessarily every article
+  // in the underlying collection - matches what a crawler can see.
+  items?: CollectionPageItem[]
 }>
 
 export function CollectionPageSchema({
@@ -172,6 +163,7 @@ export function CollectionPageSchema({
   description,
   url,
   articleCount,
+  items,
 }: CollectionPageSchemaProps) {
   const schema = {
     '@context': 'https://schema.org',
@@ -180,6 +172,18 @@ export function CollectionPageSchema({
     description,
     url,
     numberOfItems: articleCount,
+    ...(items &&
+      items.length > 0 && {
+        mainEntity: {
+          '@type': 'ItemList',
+          itemListElement: items.map((item) => ({
+            '@type': 'ListItem',
+            position: item.position,
+            url: item.url,
+            name: item.name,
+          })),
+        },
+      }),
   }
 
   return (

package/src/ArticleSocialShare.tsx

@@ -2,17 +2,35 @@
 
 import { useState } from 'react'
 import { Share2, Copy, Check, Mail, MessageCircle, Users, FileText } from 'lucide-react'
+import { emitArticleEvent } from './events'
+import type { ArticlesConfig } from './articlesConfig'
 
 interface ArticleSocialShareProps {
   readonly title: string
   readonly url: string
   readonly excerpt?: string
   readonly shareMessage?: string
+  /** Optional (Phase 27F). Enables `shared` events - requires `articleSlug` too. */
+  readonly config?: ArticlesConfig
+  /** The article slug being shared. Required to emit `shared`. */
+  readonly articleSlug?: string
 }
 
-export function ArticleSocialShare({ title, url, excerpt, shareMessage }: ArticleSocialShareProps) {
+export function ArticleSocialShare({
+  title,
+  url,
+  excerpt,
+  shareMessage,
+  config,
+  articleSlug,
+}: ArticleSocialShareProps) {
   const [copied, setCopied] = useState(false)
 
+  function trackShare(channel: string) {
+    if (!articleSlug) return
+    emitArticleEvent(config?.onEvent, { name: 'shared', articleSlug, channel })
+  }
+
   const encodedTitle = encodeURIComponent(title)
   const encodedUrl = encodeURIComponent(url)
   const encodedExcerpt = encodeURIComponent(excerpt || '')
@@ -31,13 +49,15 @@ export function ArticleSocialShare({ title, url, excerpt, shareMessage }: Articl
     try {
       await navigator.clipboard.writeText(url)
       setCopied(true)
+      trackShare('copy-link')
       setTimeout(() => setCopied(false), 2000)
     } catch {
       // clipboard unavailable
     }
   }
 
-  const openShareWindow = (shareUrl: string) => {
+  const openShareWindow = (shareUrl: string, channel: string) => {
+    trackShare(channel)
     globalThis.open(shareUrl, '_blank', 'width=600,height=400,scrollbars=yes,resizable=yes')
   }
 
@@ -52,34 +72,58 @@ export function ArticleSocialShare({ title, url, excerpt, shareMessage }: Articl
       </div>
 
       <div className="flex flex-wrap gap-2">
-        <button className={btnClass} onClick={() => openShareWindow(shareLinks.linkedin)}>
+        <button
+          type="button"
+          className={btnClass}
+          onClick={() => openShareWindow(shareLinks.linkedin, 'linkedin')}
+        >
           <Users className="h-4 w-4" />
           LinkedIn
         </button>
-        <button className={btnClass} onClick={() => openShareWindow(shareLinks.facebook)}>
+        <button
+          type="button"
+          className={btnClass}
+          onClick={() => openShareWindow(shareLinks.facebook, 'facebook')}
+        >
           <span className="text-xs font-bold">f</span> Facebook
         </button>
-        <button className={btnClass} onClick={() => openShareWindow(shareLinks.twitter)}>
+        <button
+          type="button"
+          className={btnClass}
+          onClick={() => openShareWindow(shareLinks.twitter, 'twitter')}
+        >
           <MessageCircle className="h-4 w-4" />
           Twitter
         </button>
-        <button className={btnClass} onClick={() => openShareWindow(shareLinks.reddit)}>
+        <button
+          type="button"
+          className={btnClass}
+          onClick={() => openShareWindow(shareLinks.reddit, 'reddit')}
+        >
           <FileText className="h-4 w-4" />
           Reddit
         </button>
-        <button className={btnClass} onClick={() => openShareWindow(shareLinks.whatsapp)}>
+        <button
+          type="button"
+          className={btnClass}
+          onClick={() => openShareWindow(shareLinks.whatsapp, 'whatsapp')}
+        >
           <MessageCircle className="h-4 w-4" />
           WhatsApp
         </button>
-        <button className={btnClass} onClick={() => openShareWindow(shareLinks.telegram)}>
+        <button
+          type="button"
+          className={btnClass}
+          onClick={() => openShareWindow(shareLinks.telegram, 'telegram')}
+        >
           <MessageCircle className="h-4 w-4" />
           Telegram
         </button>
-        <a className={btnClass} href={shareLinks.email}>
+        <a className={btnClass} href={shareLinks.email} onClick={() => trackShare('email')}>
           <Mail className="h-4 w-4" />
           Email
         </a>
-        <button className={btnClass} onClick={copyToClipboard}>
+        <button type="button" className={btnClass} onClick={copyToClipboard}>
           {copied ? <Check className="h-4 w-4" /> : <Copy className="h-4 w-4" />}
           {copied ? 'Copied!' : 'Copy Link'}
         </button>