@fullstackdatasolutions/articles 1.2.3 → 1.3.1

package/package.json

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

package/src/ArticleAnswer.tsx

@@ -0,0 +1,35 @@
+import type { Article } from './articleTypes'
+
+type ArticleAnswerProps = Readonly<{
+  article: Pick<Article, 'answer'>
+  /** Heading shown above the answer. Default: `'The short answer'`. */
+  label?: string
+  className?: string
+}>
+
+/**
+ * Renders `article.answer` as a callout above the article body.
+ *
+ * The same text is emitted as the Article schema's `abstract` and placed at
+ * the top of the article's markdown twin, so the passage an answer engine is
+ * most likely to lift is also the one a reader sees first. Returns `null`
+ * when the article has no `answer`, so it is safe to render unconditionally.
+ */
+export function ArticleAnswer({
+  article,
+  label = 'The short answer',
+  className,
+}: ArticleAnswerProps) {
+  if (!article.answer?.trim()) return null
+  return (
+    <aside
+      className={`mb-8 rounded-lg border-l-4 border-primary bg-muted/40 px-6 py-4 ${className ?? ''}`}
+      style={{ borderLeftWidth: '4px' }}
+    >
+      <p className="mb-2 text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+        {label}
+      </p>
+      <p className="text-base leading-relaxed">{article.answer}</p>
+    </aside>
+  )
+}

package/src/ArticleSchemas.tsx

@@ -1,6 +1,13 @@
-import type { ArticlesConfig } from './articlesConfig'
+import {
+  getOrganizationId,
+  getPersonId,
+  getWebSiteId,
+  resolveEntityUrl,
+  type ArticlesConfig,
+} from './articlesConfig'
 import type { Article, AuthorProfile, FaqItem, HowToStep } from './articleTypes'
-import { getAuthorAvatar, getAuthorSameAs } from './authorUtils'
+import type { ArticleComment } from './commentTypes'
+import { getAuthorAvatar, getAuthorIdentityUrl, getAuthorSameAs } from './authorUtils'
 
 export { BreadcrumbSchema } from './Breadcrumb'
 
@@ -21,13 +28,17 @@ function getPersonSchemas(
   // 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) }),
-  }))
+  return resolvedAuthors.map((author) => {
+    const identityUrl = getAuthorIdentityUrl(author, config)
+    return {
+      '@type': 'Person',
+      ...(identityUrl && { '@id': getPersonId(identityUrl) }),
+      name: author.name,
+      ...(author.url && { url: author.url }),
+      ...(getAuthorAvatar(author, config) && { image: getAuthorAvatar(author, config) }),
+      ...(getAuthorSameAs(author).length > 0 && { sameAs: getAuthorSameAs(author) }),
+    }
+  })
 }
 
 type ArticleSEOProps = Readonly<{
@@ -38,43 +49,183 @@ type ArticleSEOProps = Readonly<{
   showAuthor?: boolean
   authors?: AuthorProfile[]
   config?: ArticlesConfig
+  /**
+   * Top-level comments to emit as `commentCount`/`comment`. Real discussion
+   * is a quality signal that is otherwise invisible in structured data.
+   * Deleted comments are excluded, and only the author name, body, and
+   * timestamp are emitted - never the commenter's id.
+   */
+  comments?: readonly ArticleComment[]
 }>
 
-export function ArticleSEO({
+// `lastmodFallback: 'none'` opts out of reusing the publish date - an article
+// edited three times with no `lastmod` otherwise reports its original date as
+// `dateModified` forever.
+function resolveModifiedAt(
+  article: Article,
+  publishedAt: string | undefined,
+  config?: ArticlesConfig
+): string | undefined {
+  if (article.lastmod) return new Date(article.lastmod).toISOString()
+  return config?.lastmodFallback === 'none' ? undefined : publishedAt
+}
+
+/**
+ * Absolutizes an article image for structured data.
+ *
+ * `featuredImage` is stored site-relative (`/articles/<slug>/hero.jpg`), and
+ * Open Graph already absolutizes it via `resolveImageUrl` - JSON-LD did not,
+ * so every article was publishing a relative `ImageObject.url`, which
+ * consumers of structured data reject. Prefers `config.siteUrl`, falling back
+ * to the origin of `articleUrl` for callers that pass no config.
+ *
+ * No `width`/`height`: the package never measures the file, and asserting
+ * dimensions it has not read would be a guess in structured data.
+ */
+function resolveSchemaImageUrl(image: string, articleUrl: string, config?: ArticlesConfig): string {
+  if (/^https?:\/\//.test(image)) return image
+  if (config) return resolveEntityUrl(image, config)
+  try {
+    return `${new URL(articleUrl).origin}/${image.replace(/^\/+/, '')}`
+  } catch {
+    return image
+  }
+}
+
+function buildPublisher(siteName: string, siteLogo?: string, config?: ArticlesConfig) {
+  if (config?.organization) return { '@id': getOrganizationId(config) }
+  return {
+    '@type': 'Organization',
+    name: siteName,
+    ...(siteLogo && { logo: { '@type': 'ImageObject', url: siteLogo } }),
+  }
+}
+
+// `articleType: 'QAPage'` already retypes the Article node, and a QAPage's
+// required shape is a `mainEntity` Question - so the Q&A belongs on that node
+// rather than in a second script that would duplicate one page as two
+// competing entities.
+function buildQuestionEntity(article: Article, articleUrl: string, publishedAt?: string) {
+  if (article.articleType !== 'QAPage' || !article.answer) return undefined
+  return {
+    '@type': 'Question',
+    name: article.title,
+    text: article.excerpt || article.title,
+    ...(publishedAt && { dateCreated: publishedAt }),
+    answerCount: 1,
+    acceptedAnswer: { '@type': 'Answer', text: article.answer, url: articleUrl },
+  }
+}
+
+function buildCommentFields(comments?: readonly ArticleComment[]) {
+  const visible = comments?.filter((comment) => !comment.isDeleted && !comment.parentId) ?? []
+  if (visible.length === 0) return {}
+  return {
+    commentCount: visible.length,
+    comment: visible.map((comment) => ({
+      '@type': 'Comment',
+      text: comment.body,
+      dateCreated: comment.createdAt,
+      author: { '@type': 'Person', name: comment.authorName },
+    })),
+  }
+}
+
+function buildTopicFields(article: Article, config?: ArticlesConfig) {
+  const about = article.about?.map((entity) => ({
+    '@type': 'Thing',
+    name: entity.name,
+    ...(entity.sameAs && { sameAs: entity.sameAs }),
+  }))
+  const citation = article.citation?.map((source) => ({
+    '@type': 'CreativeWork',
+    name: source.name,
+    ...(source.url && { url: source.url }),
+  }))
+  const selectors = config?.speakableSelectors
+
+  return {
+    ...(about?.length && { about }),
+    ...(citation?.length && { citation }),
+    ...(selectors?.length && {
+      speakable: { '@type': 'SpeakableSpecification', cssSelector: selectors },
+    }),
+  }
+}
+
+function buildArticleSchema({
   article,
   articleUrl,
   siteName,
   siteLogo,
-  showAuthor = true,
-  authors,
+  showAuthor,
+  personSchemas,
   config,
-}: ArticleSEOProps) {
+  comments,
+}: Readonly<{
+  article: Article
+  articleUrl: string
+  siteName: string
+  siteLogo?: string
+  showAuthor: boolean
+  personSchemas: ReturnType<typeof getPersonSchemas>
+  config?: ArticlesConfig
+  comments?: readonly ArticleComment[]
+}>) {
   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, config)
+  const modifiedAt = resolveModifiedAt(article, publishedAt, config)
+  const mainEntity = buildQuestionEntity(article, articleUrl, publishedAt)
 
-  const structuredData = {
+  return {
     '@context': 'https://schema.org',
     '@type': article.articleType || 'Article',
     mainEntityOfPage: { '@type': 'WebPage', '@id': articleUrl },
     headline: article.title,
     image: article.featuredImage
-      ? { '@type': 'ImageObject', url: article.featuredImage }
+      ? {
+          '@type': 'ImageObject',
+          url: resolveSchemaImageUrl(article.featuredImage, articleUrl, config),
+        }
       : undefined,
     ...(publishedAt && { datePublished: publishedAt }),
     ...(modifiedAt && { dateModified: modifiedAt }),
     ...(showAuthor && personSchemas.length > 0 && { author: personSchemas }),
-    publisher: {
-      '@type': 'Organization',
-      name: siteName,
-      ...(siteLogo && { logo: { '@type': 'ImageObject', url: siteLogo } }),
-    },
+    publisher: buildPublisher(siteName, siteLogo, config),
     description: article.excerpt,
+    ...(article.answer && { abstract: article.answer }),
     articleSection: article.category,
-    ...(article.tags && article.tags.length > 0 && { keywords: article.tags.join(', ') }),
+    ...(article.tags?.length && { keywords: article.tags.join(', ') }),
     ...(article.wordCount !== undefined && { wordCount: article.wordCount }),
     ...(article.series && { isPartOf: { '@type': 'Blog', name: article.series } }),
+    inLanguage: config?.language ?? 'en',
+    isAccessibleForFree: config?.isAccessibleForFree !== false,
+    ...buildTopicFields(article, config),
+    ...buildCommentFields(comments),
+    ...(mainEntity && { mainEntity }),
   }
+}
+
+export function ArticleSEO({
+  article,
+  articleUrl,
+  siteName,
+  siteLogo,
+  showAuthor = true,
+  authors,
+  config,
+  comments,
+}: ArticleSEOProps) {
+  const personSchemas = getPersonSchemas(article, authors, config)
+  const structuredData = buildArticleSchema({
+    article,
+    articleUrl,
+    siteName,
+    siteLogo,
+    showAuthor,
+    personSchemas,
+    config,
+    comments,
+  })
 
   return (
     <>
@@ -193,3 +344,92 @@ export function CollectionPageSchema({
     />
   )
 }
+
+type OrganizationSchemaProps = Readonly<{ config: ArticlesConfig }>
+
+/**
+ * Site-level publisher entity, rendered once in the root layout.
+ *
+ * Articles reference this by `@id` rather than repeating an inline
+ * `Organization` stub, so every page on the site resolves to one entity - the
+ * thing that lets a search or answer engine attribute a whole corpus to a
+ * single publisher instead of treating each page as an orphan.
+ * Returns `null` when `config.organization` is unset.
+ */
+export function OrganizationSchema({ config }: OrganizationSchemaProps) {
+  const org = config.organization
+  if (!org) return null
+
+  const schema = {
+    '@context': 'https://schema.org',
+    '@type': org.type ?? 'Organization',
+    '@id': getOrganizationId(config),
+    name: org.name ?? config.siteName,
+    url: org.url ?? config.siteUrl.replace(/\/$/, ''),
+    ...(org.logo && {
+      logo: { '@type': 'ImageObject', url: resolveEntityUrl(org.logo, config) },
+    }),
+    ...((org.description ?? config.description) && {
+      description: org.description ?? config.description,
+    }),
+    ...(org.sameAs && org.sameAs.length > 0 && { sameAs: org.sameAs }),
+    ...(org.parentOrganization && {
+      parentOrganization: {
+        '@type': 'Organization',
+        name: org.parentOrganization.name,
+        url: org.parentOrganization.url,
+      },
+    }),
+  }
+
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
+    />
+  )
+}
+
+type WebSiteSchemaProps = Readonly<{ config: ArticlesConfig }>
+
+/**
+ * Site entity, rendered once in the root layout alongside `OrganizationSchema`.
+ * Emits a `SearchAction` only when `organization.searchUrlTemplate` is set -
+ * the library's own search is client-side with no crawlable results URL, so
+ * declaring one unconditionally would advertise an endpoint that does not exist.
+ * Returns `null` when `config.organization` is unset.
+ */
+export function WebSiteSchema({ config }: WebSiteSchemaProps) {
+  const org = config.organization
+  if (!org) return null
+
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const template = org.searchUrlTemplate
+
+  const schema = {
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    '@id': getWebSiteId(config),
+    name: config.siteName,
+    url: siteUrl,
+    publisher: { '@id': getOrganizationId(config) },
+    ...(config.description && { description: config.description }),
+    ...(template && {
+      potentialAction: {
+        '@type': 'SearchAction',
+        target: {
+          '@type': 'EntryPoint',
+          urlTemplate: resolveEntityUrl(template, config),
+        },
+        'query-input': 'required name=search_term_string',
+      },
+    }),
+  }
+
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
+    />
+  )
+}

package/src/AuthorArticlesPage.tsx

@@ -5,10 +5,10 @@ import Link from 'next/link'
 import { CollectionPageSchema } from './ArticleSchemas'
 import { AuthorDetailHero } from './AuthorDetailHero'
 import { LatestArticles } from './LatestArticles'
-import { getAuthorAvatar, getAuthorSameAs, getAuthorUrl } from './authorUtils'
+import { getAuthorAvatar, getAuthorIdentityUrl, getAuthorSameAs } from './authorUtils'
 import { emitArticleEvent } from './events'
 import { CtaViewTracker } from './eventTracking'
-import { DEFAULT_PAGE_SIZE } from './articlesConfig'
+import { DEFAULT_PAGE_SIZE, getOrganizationId, getPersonId } from './articlesConfig'
 import type { ArticlesConfig } from './articlesConfig'
 import type { ListingPaginationContext } from './pagination'
 import type { Article, AuthorProfile } from './articleTypes'
@@ -55,7 +55,24 @@ type AuthorArticlesPageProps = Readonly<{
   customSection?: ReactNode
 }>
 
-function getPersonSchema(author: AuthorProfile, config: ArticlesConfig, articleCount: number) {
+/**
+ * Topics the author demonstrably writes about, taken from the categories of
+ * their own published articles - `knowsAbout` takes subject matter, and
+ * before 1.3.0 this field was filled with `config.siteName`, which is a
+ * publisher name rather than a topic and told a consumer nothing.
+ * `AuthorProfile.knowsAbout`, when set, replaces the derived list.
+ */
+function getKnowsAbout(author: AuthorProfile, articles: readonly Article[]): string[] {
+  if (author.knowsAbout?.length) return [...author.knowsAbout]
+  return [...new Set(articles.flatMap((article) => article.categories ?? []))].filter(Boolean)
+}
+
+function getPersonSchema(
+  author: AuthorProfile,
+  config: ArticlesConfig,
+  articleCount: number,
+  knowsAbout: readonly string[]
+) {
   // Phase 27E audit: `promise`/`servesWho`/`principles`/`credentials`/`proof`
   // are intentionally NOT added here. `promise` and `principles` are
   // audience-facing marketing copy, not encyclopedic facts; `servesWho` is an
@@ -64,17 +81,28 @@ function getPersonSchema(author: AuthorProfile, config: ArticlesConfig, articleC
   // structured data, so `description`/`knowsAbout`/`sameAs`/`image` stay
   // sourced exactly as they were before this phase (bio, siteName, approved
   // social links, resolved avatar).
+  // Three distinct URLs, deliberately not collapsed into one:
+  // - `@id` is the cross-site identity (see `getAuthorIdentityUrl`); it must
+  //   match what every article's `author` reference emits, and be absolute so
+  //   it can resolve to the same node from any page.
+  // - `url` is the author's own canonical profile.
+  // - `mainEntityOfPage` is *this* page, always - it says where the entity is
+  //   described, so it can never point at another site.
+  const pageUrl = `${config.siteUrl.replace(/\/$/, '')}/articles/authors/${author.slug}`
+  const identityUrl = getAuthorIdentityUrl(author, config) ?? pageUrl
+  const authorUrl = author.url ?? pageUrl
   return {
     '@context': 'https://schema.org',
     '@type': 'Person',
+    '@id': getPersonId(identityUrl),
     name: author.name,
     description: author.bio,
-    url: author.url ?? getAuthorUrl(author),
+    url: authorUrl,
     ...(getAuthorAvatar(author, config) && { image: getAuthorAvatar(author, config) }),
     ...(getAuthorSameAs(author).length > 0 && { sameAs: getAuthorSameAs(author) }),
-    knowsAbout: config.siteName,
-    mainEntityOfPage:
-      author.url ?? `${config.siteUrl.replace(/\/$/, '')}/articles/authors/${author.slug}`,
+    ...(knowsAbout.length > 0 && { knowsAbout: [...knowsAbout] }),
+    ...(config.organization && { worksFor: { '@id': getOrganizationId(config) } }),
+    mainEntityOfPage: pageUrl,
     interactionStatistic: {
       '@type': 'InteractionCounter',
       interactionType: 'https://schema.org/WriteAction',
@@ -299,7 +327,9 @@ export function AuthorArticlesPage({
       <script
         type="application/ld+json"
         dangerouslySetInnerHTML={{
-          __html: JSON.stringify(getPersonSchema(author, config, articleCount)),
+          __html: JSON.stringify(
+            getPersonSchema(author, config, articleCount, getKnowsAbout(author, articles))
+          ),
         }}
       />
       <CollectionPageSchema

package/src/__tests__/ArticleAnswer.test.tsx

@@ -0,0 +1,25 @@
+import { render, screen } from '@testing-library/react'
+import { ArticleAnswer } from '../ArticleAnswer'
+
+describe('ArticleAnswer', () => {
+  it('renders the answer with a default label', () => {
+    render(<ArticleAnswer article={{ answer: 'Roll initiative, then act in order.' }} />)
+    expect(screen.getByText('The short answer')).toBeInTheDocument()
+    expect(screen.getByText('Roll initiative, then act in order.')).toBeInTheDocument()
+  })
+
+  it('accepts a custom label and className', () => {
+    const { container } = render(
+      <ArticleAnswer article={{ answer: 'Yes.' }} label="TL;DR" className="custom" />
+    )
+    expect(screen.getByText('TL;DR')).toBeInTheDocument()
+    expect(container.querySelector('aside')).toHaveClass('custom')
+  })
+
+  it('renders nothing when the answer is missing or blank', () => {
+    const { container: empty } = render(<ArticleAnswer article={{}} />)
+    expect(empty.firstChild).toBeNull()
+    const { container: blank } = render(<ArticleAnswer article={{ answer: '   ' }} />)
+    expect(blank.firstChild).toBeNull()
+  })
+})