@fullstackdatasolutions/articles 0.12.0 → 1.0.0

package/src/ArticlesPage.tsx

@@ -16,6 +16,7 @@ import {
   DEFAULT_LAYOUT,
   DEFAULT_PAGE_SIZE,
 } from './articlesConfig'
+import type { ListingPaginationContext } from './pagination'
 import { useArticles } from './useArticles'
 
 interface SectionContext {
@@ -28,6 +29,7 @@ interface SectionContext {
   handleSearch: (query: string) => void
   pageSize: number
   categoriesPageSize: number
+  pagination?: ListingPaginationContext
 }
 
 function buildThemeVars(theme?: ArticlesTheme): React.CSSProperties {
@@ -63,6 +65,7 @@ function renderSection(
     handleSearch,
     pageSize,
     categoriesPageSize,
+    pagination,
   } = ctx
 
   switch (section) {
@@ -134,6 +137,7 @@ function renderSection(
           searchQuery={searchQuery}
           onClearSearch={() => handleSearch('')}
           pageSize={pageSize}
+          pagination={pagination}
         />
       )
 
@@ -156,10 +160,29 @@ export function ArticlesPage({
   config,
   initialArticles,
   initialCategories,
+  page,
+  totalPages,
+  totalCount,
 }: Readonly<{
   config: ArticlesConfig
   initialArticles?: Article[]
   initialCategories?: CategoryInfo[]
+  /**
+   * Current page number in `listingPagination: 'pages'` mode. Ignored
+   * (along with `totalPages`/`totalCount`) unless `config.listingPagination
+   * === 'pages'` - the default `'load-more'` behavior never reads these.
+   * `initialArticles` should already be this page's slice (see
+   * `paginateArticles` from `./server`).
+   */
+  page?: number
+  /** Total page count in `'pages'` mode, from `getTotalPages`. */
+  totalPages?: number
+  /**
+   * True total article count across every page (not just `initialArticles`'
+   * length) - used for `CollectionPageSchema.articleCount`. Defaults to
+   * `state.articles.length`, matching prior behavior when omitted.
+   */
+  totalCount?: number
 }>) {
   const state = useArticles(initialArticles, initialCategories)
   const layout = config.layout ?? DEFAULT_LAYOUT
@@ -167,21 +190,48 @@ export function ArticlesPage({
   const categoriesPageSize = config.categoriesPageSize ?? DEFAULT_CATEGORIES_PAGE_SIZE
   const themeVars = buildThemeVars(config.theme)
 
-  const hasFeatured = layout.includes('featured')
+  const isPagesMode =
+    config.listingPagination === 'pages' && page !== undefined && totalPages !== undefined
+  const currentPage = page ?? 1
+  // The pinned "featured" hero only makes sense on page 1 (it always pulls
+  // state.articles[0], which on page 2+ would just be that page's first
+  // article, not the site's actual latest) - drop it from the layout for
+  // page > 1 rather than rendering a misleading featured pick.
+  const effectiveLayout =
+    isPagesMode && currentPage > 1 ? layout.filter((section) => section !== 'featured') : layout
+
+  const hasFeatured = effectiveLayout.includes('featured')
   const articlesWithoutFeatured = hasFeatured ? state.articles.slice(1) : state.articles
   const displayedArticles = state.searchQuery ? state.articles : articlesWithoutFeatured
 
-  const ctx: SectionContext = { ...state, displayedArticles, pageSize, categoriesPageSize }
+  const pagination: ListingPaginationContext | undefined = isPagesMode
+    ? { page: currentPage, totalPages: totalPages as number, basePath: '/articles' }
+    : undefined
+
+  const ctx: SectionContext = {
+    ...state,
+    displayedArticles,
+    pageSize,
+    categoriesPageSize,
+    pagination,
+  }
+
+  const articleCount = totalCount ?? state.articles.length
 
   return (
     <div style={themeVars}>
-      {layout.map((section) => renderSection(section, ctx, config))}
+      {effectiveLayout.map((section) => renderSection(section, ctx, config))}
       {state.articles.length > 0 && (
         <CollectionPageSchema
           title={`Articles | ${config.siteName}`}
-          description={`Browse all ${state.articles.length} articles on ${config.siteName}.`}
+          description={`Browse all ${articleCount} articles on ${config.siteName}.`}
           url={`${config.siteUrl}/articles`}
-          articleCount={state.articles.length}
+          articleCount={articleCount}
+          items={displayedArticles.slice(0, pageSize).map((article, index) => ({
+            position: index + 1,
+            url: `${config.siteUrl}/articles/${article.slug}`,
+            name: article.title,
+          }))}
         />
       )}
     </div>

package/src/AuthorArticlesPage.tsx

@@ -1,19 +1,69 @@
 'use client'
 
+import type { ReactNode } from 'react'
 import Link from 'next/link'
+import { CollectionPageSchema } from './ArticleSchemas'
+import { AuthorDetailHero } from './AuthorDetailHero'
 import { LatestArticles } from './LatestArticles'
 import { getAuthorAvatar, getAuthorSameAs, getAuthorUrl } from './authorUtils'
+import { emitArticleEvent } from './events'
+import { CtaViewTracker } from './eventTracking'
 import { DEFAULT_PAGE_SIZE } from './articlesConfig'
 import type { ArticlesConfig } from './articlesConfig'
+import type { ListingPaginationContext } from './pagination'
 import type { Article, AuthorProfile } from './articleTypes'
 
+/**
+ * Ordered section keys for the composable author-page render API (Phase
+ * 27E). `'custom'` is the one consumer-supplied slot - pass its content via
+ * the `customSection` prop. Passing `sections` is fully opt-in: omitting it
+ * keeps `AuthorArticlesPage`'s original output (Person/CollectionPage JSON-LD
+ * + article list only, no hero) byte-for-byte unchanged.
+ */
+export type AuthorPageSection =
+  | 'hero'
+  | 'promise'
+  | 'servesWho'
+  | 'originStory'
+  | 'principles'
+  | 'proof'
+  | 'cta'
+  | 'articles'
+  | 'custom'
+
 type AuthorArticlesPageProps = Readonly<{
   author: AuthorProfile
   articles: Article[]
   config: ArticlesConfig
+  /** Current page number in `listingPagination: 'pages'` mode. Ignored (with `totalPages`/`totalCount`) unless `config.listingPagination === 'pages'`. `articles` should already be this page's slice. */
+  page?: number
+  /** Total page count in `'pages'` mode, from `getTotalPages`. */
+  totalPages?: number
+  /** True total article count across every page. Defaults to `articles.length` (also used as the `Person` schema's `interactionStatistic` count). */
+  totalCount?: number
+  /**
+   * Ordered list of sections to render (Phase 27E composable render API).
+   * When omitted, `AuthorArticlesPage` renders exactly as it did before this
+   * prop existed - the article list only, no hero and no rich-profile
+   * sections, even if `author` has the new optional fields populated.
+   * Include `'hero'` to render `AuthorDetailHero` here instead of composing
+   * it separately; each other section renders nothing when its backing
+   * field (`author.promise`, `author.servesWho`, etc.) is unset.
+   */
+  sections?: AuthorPageSection[]
+  /** Content for the one `'custom'` slot in `sections`. Ignored unless `sections` includes `'custom'`. */
+  customSection?: ReactNode
 }>
 
 function getPersonSchema(author: AuthorProfile, config: ArticlesConfig, articleCount: number) {
+  // 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
+  // audience segment, not a `knowsAbout` topic; `credentials`/`proof` are
+  // unverifiable/self-reported claims. None meet the bar for schema.org
+  // structured data, so `description`/`knowsAbout`/`sameAs`/`image` stay
+  // sourced exactly as they were before this phase (bio, siteName, approved
+  // social links, resolved avatar).
   return {
     '@context': 'https://schema.org',
     '@type': 'Person',
@@ -33,28 +83,272 @@ function getPersonSchema(author: AuthorProfile, config: ArticlesConfig, articleC
   }
 }
 
-export function AuthorArticlesPage({ author, articles, config }: AuthorArticlesPageProps) {
-  const pageSize = config.pageSize ?? DEFAULT_PAGE_SIZE
+type AuthorSectionContext = Readonly<{
+  author: AuthorProfile
+  articleCount: number
+  articles: Article[]
+  pageSize: number
+  pagination?: ListingPaginationContext
+  customSection?: ReactNode
+  config?: ArticlesConfig
+}>
+
+function renderHeroSection(author: AuthorProfile, articleCount: number): ReactNode {
+  return <AuthorDetailHero key="hero" author={author} articleCount={articleCount} />
+}
+
+function renderPromiseSection(author: AuthorProfile): ReactNode {
+  return author.promise ? (
+    <section key="promise" aria-label="Author promise" className="bg-background py-12">
+      <div className="mx-auto max-w-3xl px-4 text-center sm:px-6 lg:px-8">
+        <p className="text-xl font-medium text-foreground md:text-2xl">{author.promise}</p>
+      </div>
+    </section>
+  ) : null
+}
+
+function renderServesWhoSection(author: AuthorProfile): ReactNode {
+  return author.servesWho && author.servesWho.length > 0 ? (
+    <section key="servesWho" aria-label="Who this author serves" className="bg-muted/40 py-12">
+      <div className="mx-auto max-w-3xl px-4 sm:px-6 lg:px-8">
+        <h2 className="mb-4 text-center text-2xl font-bold text-foreground">Who I help</h2>
+        <ul className="grid gap-3 sm:grid-cols-2">
+          {author.servesWho.map((who) => (
+            <li
+              key={who}
+              className="rounded-lg border border-border bg-card px-4 py-3 text-sm text-card-foreground"
+            >
+              {who}
+            </li>
+          ))}
+        </ul>
+      </div>
+    </section>
+  ) : null
+}
+
+function renderOriginStorySection(author: AuthorProfile): ReactNode {
+  return author.originStory && author.originStory.length > 0 ? (
+    <section key="originStory" aria-label="Author origin story" className="bg-background py-12">
+      <div className="mx-auto max-w-3xl px-4 sm:px-6 lg:px-8">
+        <h2 className="mb-6 text-2xl font-bold text-foreground">My story</h2>
+        <div className="space-y-6">
+          {author.originStory.map((block, blockIndex) => (
+            <div key={block.heading ?? blockIndex}>
+              {block.heading && (
+                <h3 className="mb-2 text-lg font-semibold text-foreground">{block.heading}</h3>
+              )}
+              {block.paragraphs.map((paragraph, paragraphIndex) => (
+                <p
+                  key={`${block.heading ?? blockIndex}-${paragraph.slice(0, 40)}-${paragraphIndex}`}
+                  className="mb-3 text-muted-foreground"
+                >
+                  {paragraph}
+                </p>
+              ))}
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  ) : null
+}
+
+function renderPrinciplesSection(author: AuthorProfile): ReactNode {
+  return author.principles && author.principles.length > 0 ? (
+    <section key="principles" aria-label="Author principles" className="bg-muted/40 py-12">
+      <div className="mx-auto max-w-3xl px-4 sm:px-6 lg:px-8">
+        <h2 className="mb-4 text-center text-2xl font-bold text-foreground">What I believe</h2>
+        <ul className="space-y-3">
+          {author.principles.map((principle) => (
+            <li
+              key={principle}
+              className="rounded-lg border border-border bg-card px-4 py-3 text-sm text-card-foreground"
+            >
+              {principle}
+            </li>
+          ))}
+        </ul>
+      </div>
+    </section>
+  ) : null
+}
+
+function renderProofSection(author: AuthorProfile): ReactNode {
+  return author.proof && author.proof.length > 0 ? (
+    <section key="proof" aria-label="Author proof" className="bg-background py-12">
+      <div className="mx-auto max-w-4xl px-4 sm:px-6 lg:px-8">
+        <h2 className="mb-6 text-center text-2xl font-bold text-foreground">Proof</h2>
+        <div className="grid gap-4 sm:grid-cols-2">
+          {author.proof.map((item) => (
+            <div
+              key={`${item.claim}-${item.url ?? item.source ?? ''}`}
+              className="rounded-lg border border-border bg-card p-4 text-card-foreground"
+            >
+              <p className="font-medium">{item.claim}</p>
+              {(item.source || item.url) && (
+                <p className="mt-1 text-sm text-muted-foreground">
+                  {item.url ? (
+                    <Link href={item.url} className="hover:text-primary hover:underline">
+                      {item.source ?? item.url}
+                    </Link>
+                  ) : (
+                    item.source
+                  )}
+                </p>
+              )}
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  ) : null
+}
+
+function renderCtaSection(author: AuthorProfile, config?: ArticlesConfig): ReactNode {
+  return author.primaryCta ? (
+    <CtaViewTracker key="cta" ctaId={`author-cta:${author.slug}`} config={config}>
+      <section aria-label="Author call to action" className="bg-muted/40 py-12">
+        <div className="mx-auto max-w-2xl px-4 text-center sm:px-6 lg:px-8">
+          <Link
+            href={author.primaryCta.href}
+            onClick={() =>
+              emitArticleEvent(config?.onEvent, {
+                name: 'cta_clicked',
+                ctaId: `author-cta:${author.slug}`,
+              })
+            }
+            className="inline-flex items-center justify-center rounded-md bg-primary px-6 py-3 text-sm font-semibold text-primary-foreground hover:bg-primary/90"
+          >
+            {author.primaryCta.label}
+          </Link>
+        </div>
+      </section>
+    </CtaViewTracker>
+  ) : null
+}
 
+function renderArticlesSection(
+  author: AuthorProfile,
+  articles: Article[],
+  pageSize: number,
+  pagination?: ListingPaginationContext
+): ReactNode {
   return (
-    <div>
+    <section key="articles" aria-label="Articles by this author" className="bg-background py-16">
+      <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+        <div className="mb-8 flex items-center justify-between gap-4">
+          <Link href="/articles" className="text-sm text-primary hover:underline">
+            All Articles
+          </Link>
+          <p className="text-sm text-muted-foreground">Articles by {author.name}</p>
+        </div>
+        <LatestArticles articles={articles} pageSize={pageSize} pagination={pagination} />
+      </div>
+    </section>
+  )
+}
+
+function renderAuthorSection(section: AuthorPageSection, ctx: AuthorSectionContext): ReactNode {
+  const { author, articleCount, articles, pageSize, pagination, customSection, config } = ctx
+
+  switch (section) {
+    case 'hero':
+      return renderHeroSection(author, articleCount)
+    case 'promise':
+      return renderPromiseSection(author)
+    case 'servesWho':
+      return renderServesWhoSection(author)
+    case 'originStory':
+      return renderOriginStorySection(author)
+    case 'principles':
+      return renderPrinciplesSection(author)
+    case 'proof':
+      return renderProofSection(author)
+    case 'cta':
+      return renderCtaSection(author, config)
+    case 'articles':
+      return renderArticlesSection(author, articles, pageSize, pagination)
+    case 'custom':
+      return customSection ?? null
+    default:
+      return null
+  }
+}
+
+export function AuthorArticlesPage({
+  author,
+  articles,
+  config,
+  page,
+  totalPages,
+  totalCount,
+  sections,
+  customSection,
+}: AuthorArticlesPageProps) {
+  const pageSize = config.pageSize ?? DEFAULT_PAGE_SIZE
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const articleCount = totalCount ?? articles.length
+  const pagination: ListingPaginationContext | undefined =
+    config.listingPagination === 'pages' && page !== undefined && totalPages !== undefined
+      ? { page, totalPages, basePath: `/articles/authors/${author.slug}` }
+      : undefined
+
+  const schemas = (
+    <>
       <script
         type="application/ld+json"
         dangerouslySetInnerHTML={{
-          __html: JSON.stringify(getPersonSchema(author, config, articles.length)),
+          __html: JSON.stringify(getPersonSchema(author, config, articleCount)),
         }}
       />
-      <section className="bg-background py-16">
-        <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
-          <div className="mb-8 flex items-center justify-between gap-4">
-            <Link href="/articles" className="text-sm text-primary hover:underline">
-              All Articles
-            </Link>
-            <p className="text-sm text-muted-foreground">Articles by {author.name}</p>
+      <CollectionPageSchema
+        title={`${author.name} | ${config.siteName}`}
+        description={`Articles by ${author.name} on ${config.siteName}.`}
+        url={author.url ?? `${siteUrl}/articles/authors/${author.slug}`}
+        articleCount={articleCount}
+        items={articles.slice(0, pageSize).map((article, index) => ({
+          position: index + 1,
+          url: `${siteUrl}/articles/${article.slug}`,
+          name: article.title,
+        }))}
+      />
+    </>
+  )
+
+  if (!sections) {
+    return (
+      <div>
+        {schemas}
+        <section className="bg-background py-16">
+          <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+            <div className="mb-8 flex items-center justify-between gap-4">
+              <Link href="/articles" className="text-sm text-primary hover:underline">
+                All Articles
+              </Link>
+              <p className="text-sm text-muted-foreground">Articles by {author.name}</p>
+            </div>
+            <LatestArticles articles={articles} pageSize={pageSize} pagination={pagination} />
           </div>
-          <LatestArticles articles={articles} pageSize={pageSize} />
-        </div>
-      </section>
+        </section>
+      </div>
+    )
+  }
+
+  const sectionCtx: AuthorSectionContext = {
+    author,
+    articleCount,
+    articles,
+    pageSize,
+    pagination,
+    customSection,
+    config,
+  }
+
+  return (
+    <div>
+      {schemas}
+      {sections.map((section) => renderAuthorSection(section, sectionCtx))}
     </div>
   )
 }

package/src/AuthorCard.tsx

@@ -22,7 +22,7 @@ type AuthorCardProps = Readonly<{
   showSocial?: boolean
 }>
 
-function getInitials(name: string): string {
+export function getInitials(name: string): string {
   return name
     .split(' ')
     .filter(Boolean)

package/src/CategoryArticlesPage.tsx

@@ -3,6 +3,7 @@
 import Image from 'next/image'
 import Link from 'next/link'
 import { Breadcrumb } from './Breadcrumb'
+import { CollectionPageSchema } from './ArticleSchemas'
 import { LatestArticles } from './LatestArticles'
 import {
   breadcrumbsAreEnabled,
@@ -12,6 +13,7 @@ import {
   type CategoryBreadcrumbEntry,
   type CustomBreadcrumbItem,
 } from './articlesConfig'
+import type { ListingPaginationContext } from './pagination'
 import type { Article, BreadcrumbItem } from './articleTypes'
 
 function getCategoryDescription(
@@ -29,6 +31,12 @@ type CategoryArticlesPageProps = Readonly<{
   category: string
   articles: Article[]
   config: ArticlesConfig
+  /** Current page number in `listingPagination: 'pages'` mode. Ignored (with `totalPages`/`totalCount`) unless `config.listingPagination === 'pages'`. `articles` should already be this page's slice. */
+  page?: number
+  /** Total page count in `'pages'` mode, from `getTotalPages`. */
+  totalPages?: number
+  /** True total article count across every page. Defaults to `articles.length`. */
+  totalCount?: number
 }>
 
 function buildCategoryBreadcrumbItems(
@@ -74,7 +82,14 @@ function buildCategoryBreadcrumbEntry(
   return [{ name: context.categoryName }]
 }
 
-export function CategoryArticlesPage({ category, articles, config }: CategoryArticlesPageProps) {
+export function CategoryArticlesPage({
+  category,
+  articles,
+  config,
+  page,
+  totalPages,
+  totalCount,
+}: CategoryArticlesPageProps) {
   if (articles.length === 0) return null
 
   const categoryName = articles[0].category
@@ -83,9 +98,26 @@ export function CategoryArticlesPage({ category, articles, config }: CategoryArt
   const pageSize = config.pageSize ?? DEFAULT_PAGE_SIZE
   const breadcrumbConfig = getBreadcrumbsConfig(config)
   const breadcrumbItems = buildCategoryBreadcrumbItems(config, categoryName)
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const articleCount = totalCount ?? articles.length
+  const pagination: ListingPaginationContext | undefined =
+    config.listingPagination === 'pages' && page !== undefined && totalPages !== undefined
+      ? { page, totalPages, basePath: `/articles/category/${category}` }
+      : undefined
 
   return (
     <div>
+      <CollectionPageSchema
+        title={`${categoryName} | ${config.siteName}`}
+        description={description.short}
+        url={`${siteUrl}/articles/category/${category}`}
+        articleCount={articleCount}
+        items={articles.slice(0, pageSize).map((article, index) => ({
+          position: index + 1,
+          url: `${siteUrl}/articles/${article.slug}`,
+          name: article.title,
+        }))}
+      />
       {breadcrumbsAreEnabled(config) && (
         <Breadcrumb
           items={breadcrumbItems}
@@ -144,7 +176,7 @@ export function CategoryArticlesPage({ category, articles, config }: CategoryArt
             </Link>
             <p className="text-sm text-muted-foreground">{description.short}</p>
           </div>
-          <LatestArticles articles={articles} pageSize={pageSize} />
+          <LatestArticles articles={articles} pageSize={pageSize} pagination={pagination} />
         </div>
       </section>
     </div>

package/src/LatestArticles.tsx

@@ -3,19 +3,46 @@
 import { useState, useEffect } from 'react'
 import type { Article } from './articleTypes'
 import { ArticleCard } from './ArticleCard'
+import { PaginationNav } from './PaginationNav'
+import type { ListingPaginationContext } from './pagination'
 
 interface LatestArticlesProps {
   readonly articles: Article[]
   readonly pageSize: number
+  /**
+   * Switches from the default client-only "Load more" button to real
+   * paginated routes: renders every article in `articles` as-is (the caller
+   * has already sliced to the current page, e.g. via `paginateArticles`) and
+   * a `PaginationNav` instead of the button. Omit to keep the existing
+   * `listingPagination: 'load-more'` behavior, unchanged.
+   */
+  readonly pagination?: ListingPaginationContext
 }
 
-export function LatestArticles({ articles, pageSize }: Readonly<LatestArticlesProps>) {
+export function LatestArticles({ articles, pageSize, pagination }: Readonly<LatestArticlesProps>) {
   const [visibleCount, setVisibleCount] = useState(pageSize)
 
   useEffect(() => {
     setVisibleCount(pageSize)
   }, [articles, pageSize])
 
+  if (pagination) {
+    return (
+      <div>
+        <div className="grid md:grid-cols-2 lg:grid-cols-3 gap-8">
+          {articles.map((article) => (
+            <ArticleCard key={article.slug} article={article} />
+          ))}
+        </div>
+        <PaginationNav
+          basePath={pagination.basePath}
+          page={pagination.page}
+          totalPages={pagination.totalPages}
+        />
+      </div>
+    )
+  }
+
   const visible = articles.slice(0, visibleCount)
   const hasMore = visibleCount < articles.length
 

package/src/LatestArticlesSection.tsx

@@ -3,12 +3,20 @@
 import { Search } from 'lucide-react'
 import type { Article } from './articleTypes'
 import { LatestArticles } from './LatestArticles'
+import type { ListingPaginationContext } from './pagination'
 
 interface LatestArticlesSectionProps {
   readonly articles: Article[]
   readonly searchQuery: string
   readonly onClearSearch: () => void
   readonly pageSize?: number
+  /**
+   * `'pages'` mode pagination context. Ignored while `searchQuery` is set -
+   * search results stay unpaginated/client-only in both `listingPagination`
+   * modes (search URLs aren't meant to be indexed, so real pagination adds
+   * no SEO value there).
+   */
+  readonly pagination?: ListingPaginationContext
 }
 
 function DescriptionText({
@@ -30,6 +38,7 @@ export function LatestArticlesSection({
   searchQuery,
   onClearSearch,
   pageSize = 6,
+  pagination,
 }: Readonly<LatestArticlesSectionProps>) {
   return (
     <section id="latest" className="py-16 bg-muted/50">
@@ -60,7 +69,12 @@ export function LatestArticlesSection({
             </div>
           </div>
         ) : (
-          <LatestArticles articles={articles} pageSize={pageSize} key={searchQuery} />
+          <LatestArticles
+            articles={articles}
+            pageSize={pageSize}
+            pagination={searchQuery ? undefined : pagination}
+            key={searchQuery}
+          />
         )}
       </div>
     </section>