@fullstackdatasolutions/articles 0.1.0

package/src/CategoryArticlesPage.tsx

@@ -0,0 +1,84 @@
+'use client'
+
+import Image from 'next/image'
+import Link from 'next/link'
+import { BreadcrumbSchema } from './ArticleSchemas'
+import { LatestArticles } from './LatestArticles'
+import { ArticlesConfig, DEFAULT_PAGE_SIZE } from './articlesConfig'
+import type { Article } from './articleTypes'
+
+function getCategoryDescription(
+  config: ArticlesConfig,
+  slug: string,
+  categoryName: string
+): { short: string; long?: string } {
+  const raw = config.categoryDescriptions?.[slug]
+  if (!raw) return { short: `Browse all articles in ${categoryName}.` }
+  if (typeof raw === 'string') return { short: raw }
+  return raw
+}
+
+type CategoryArticlesPageProps = Readonly<{
+  category: string
+  articles: Article[]
+  config: ArticlesConfig
+}>
+
+export function CategoryArticlesPage({ category, articles, config }: CategoryArticlesPageProps) {
+  if (articles.length === 0) return null
+
+  const categoryName = articles[0].category
+  const heroImage = articles[0].featuredImage
+  const description = getCategoryDescription(config, category, categoryName)
+  const pageSize = config.pageSize ?? DEFAULT_PAGE_SIZE
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+
+  return (
+    <div>
+      <BreadcrumbSchema
+        items={[
+          { name: 'Home', url: siteUrl },
+          { name: 'Articles', url: `${siteUrl}/articles` },
+          { name: categoryName, url: `${siteUrl}/articles/category/${category}` },
+        ]}
+      />
+      {/* Hero */}
+      <section className="relative h-72 md:h-96 flex items-center justify-center overflow-hidden">
+        <Image
+          src={heroImage}
+          alt={categoryName}
+          fill
+          sizes="100vw"
+          className="object-cover"
+          priority
+        />
+        <div className="absolute inset-0 bg-black/60" />
+        <div className="relative z-10 text-center text-white px-4">
+          <p className="text-sm font-semibold uppercase tracking-widest mb-3 opacity-80">
+            Category
+          </p>
+          <h1 className="text-4xl md:text-5xl font-bold mb-3">{categoryName}</h1>
+          {description.long && (
+            <p className="text-lg opacity-90 max-w-2xl mx-auto mt-2">{description.long}</p>
+          )}
+          <p className="text-lg opacity-70 mt-2">
+            {articles.length} article{articles.length === 1 ? '' : 's'}
+          </p>
+        </div>
+      </section>
+
+      {/* Articles */}
+      <section className="py-16 bg-muted/50 flex-1">
+        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <div className="mb-8 flex items-center justify-between">
+            <Link href="/articles" className="text-sm text-primary hover:underline">
+              ← All Articles
+            </Link>
+            <p className="text-sm text-muted-foreground">{description.short}</p>
+          </div>
+          <LatestArticles articles={articles} pageSize={pageSize} />
+        </div>
+      </section>
+    </div>
+  )
+}

package/src/CommentForm.tsx

@@ -0,0 +1,98 @@
+'use client'
+
+import { useState } from 'react'
+
+const MAX_LENGTH = 2000
+const WARN_THRESHOLD = 1800
+
+function submitLabel(submitting: boolean, parentId?: string): string {
+  if (submitting) return 'Posting…'
+  return parentId ? 'Reply' : 'Post comment'
+}
+
+interface CommentFormProps {
+  readonly articleSlug: string
+  readonly parentId?: string
+  readonly onSuccess: () => void
+  readonly onCancel?: () => void
+}
+
+export function CommentForm({ articleSlug, parentId, onSuccess, onCancel }: CommentFormProps) {
+  const [body, setBody] = useState('')
+  const [submitting, setSubmitting] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const remaining = MAX_LENGTH - body.length
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault()
+    if (!body.trim() || submitting) return
+
+    setSubmitting(true)
+    setError(null)
+
+    try {
+      const res = await fetch(`/api/articles/${articleSlug}/comments`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ body: body.trim(), parentId: parentId ?? null }),
+      })
+
+      if (!res.ok) {
+        const data = (await res.json()) as { error?: string }
+        setError(data.error ?? 'Failed to post comment')
+        return
+      }
+
+      setBody('')
+      onSuccess()
+    } catch {
+      setError('Network error — please try again')
+    } finally {
+      setSubmitting(false)
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-2">
+      <textarea
+        value={body}
+        onChange={(e) => setBody(e.target.value)}
+        maxLength={MAX_LENGTH}
+        rows={parentId ? 3 : 4}
+        placeholder={parentId ? 'Write a reply…' : 'Join the discussion…'}
+        disabled={submitting}
+        className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-primary/50 disabled:opacity-50 resize-none"
+        aria-label={parentId ? 'Reply text' : 'Comment text'}
+      />
+
+      {remaining <= MAX_LENGTH - WARN_THRESHOLD && (
+        <p className={`text-xs ${remaining < 0 ? 'text-destructive' : 'text-muted-foreground'}`}>
+          {remaining} characters remaining
+        </p>
+      )}
+
+      {error && <p className="text-xs text-destructive">{error}</p>}
+
+      <div className="flex gap-2">
+        <button
+          type="submit"
+          disabled={submitting || body.trim().length === 0 || body.length > MAX_LENGTH}
+          className="rounded-md bg-primary px-4 py-1.5 text-sm font-medium text-primary-foreground hover:bg-primary/90 disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          {submitLabel(submitting, parentId)}
+        </button>
+
+        {onCancel && (
+          <button
+            type="button"
+            onClick={onCancel}
+            className="rounded-md px-4 py-1.5 text-sm font-medium text-muted-foreground hover:text-foreground"
+          >
+            Cancel
+          </button>
+        )}
+      </div>
+    </form>
+  )
+}

package/src/CommentItem.tsx

@@ -0,0 +1,123 @@
+'use client'
+
+import { useState } from 'react'
+import { CommentForm } from './CommentForm'
+import type { ArticleComment, ArticleCommentWithReplies } from './commentTypes'
+
+function relativeTime(iso: string): string {
+  const diff = Date.now() - new Date(iso).getTime()
+  const minutes = Math.floor(diff / 60_000)
+  if (minutes < 1) return 'just now'
+  if (minutes < 60) return `${minutes}m ago`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return `${hours}h ago`
+  const days = Math.floor(hours / 24)
+  if (days < 30) return `${days}d ago`
+  const months = Math.floor(days / 30)
+  if (months < 12) return `${months}mo ago`
+  return `${Math.floor(months / 12)}y ago`
+}
+
+interface CommentItemProps {
+  readonly comment: ArticleCommentWithReplies | ArticleComment
+  readonly articleSlug: string
+  readonly currentUserId?: string
+  readonly isReply?: boolean
+  readonly onRefresh: () => void
+}
+
+export function CommentItem({
+  comment,
+  articleSlug,
+  currentUserId,
+  isReply = false,
+  onRefresh,
+}: CommentItemProps) {
+  const [showReplyForm, setShowReplyForm] = useState(false)
+  const [deleting, setDeleting] = useState(false)
+
+  const replies = 'replies' in comment ? comment.replies : []
+  const canReply = !isReply && !!currentUserId && !comment.isDeleted
+  const canDelete = !!currentUserId && currentUserId === comment.authorId && !comment.isDeleted
+
+  async function handleDelete() {
+    if (deleting) return
+    setDeleting(true)
+    try {
+      await fetch(`/api/articles/${articleSlug}/comments/${comment.id}`, { method: 'DELETE' })
+      onRefresh()
+    } finally {
+      setDeleting(false)
+    }
+  }
+
+  return (
+    <div className={`${isReply ? 'ml-8 border-l-2 border-border pl-4' : ''}`}>
+      <div className="rounded-lg bg-muted/40 p-3 space-y-1">
+        {comment.isDeleted ? (
+          <p className="text-sm italic text-muted-foreground">Comment removed</p>
+        ) : (
+          <>
+            <div className="flex items-center justify-between gap-2">
+              <span className="text-sm font-medium text-foreground">{comment.authorName}</span>
+              <span className="text-xs text-muted-foreground">
+                {relativeTime(comment.createdAt)}
+              </span>
+            </div>
+            <p className="text-sm text-foreground whitespace-pre-wrap break-words">
+              {comment.body}
+            </p>
+            <div className="flex gap-3 pt-1">
+              {canReply && (
+                <button
+                  onClick={() => setShowReplyForm((v) => !v)}
+                  className="text-xs text-muted-foreground hover:text-foreground"
+                >
+                  {showReplyForm ? 'Cancel' : 'Reply'}
+                </button>
+              )}
+              {canDelete && (
+                <button
+                  onClick={handleDelete}
+                  disabled={deleting}
+                  className="text-xs text-muted-foreground hover:text-destructive disabled:opacity-50"
+                >
+                  {deleting ? 'Deleting…' : 'Delete'}
+                </button>
+              )}
+            </div>
+          </>
+        )}
+      </div>
+
+      {showReplyForm && (
+        <div className="mt-2 ml-2">
+          <CommentForm
+            articleSlug={articleSlug}
+            parentId={comment.id}
+            onSuccess={() => {
+              setShowReplyForm(false)
+              onRefresh()
+            }}
+            onCancel={() => setShowReplyForm(false)}
+          />
+        </div>
+      )}
+
+      {replies.length > 0 && (
+        <div className="mt-2 space-y-2">
+          {replies.map((reply) => (
+            <CommentItem
+              key={reply.id}
+              comment={{ ...reply, replies: [] }}
+              articleSlug={articleSlug}
+              currentUserId={currentUserId}
+              isReply
+              onRefresh={onRefresh}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/CommentThread.tsx

@@ -0,0 +1,40 @@
+'use client'
+
+import { CommentItem } from './CommentItem'
+import type { ArticleCommentWithReplies } from './commentTypes'
+
+interface CommentThreadProps {
+  readonly comments: ArticleCommentWithReplies[]
+  readonly articleSlug: string
+  readonly currentUserId?: string
+  readonly onRefresh: () => void
+}
+
+export function CommentThread({
+  comments,
+  articleSlug,
+  currentUserId,
+  onRefresh,
+}: CommentThreadProps) {
+  if (comments.length === 0) {
+    return (
+      <p className="text-sm text-muted-foreground text-center py-6">
+        No comments yet. Be the first to share your thoughts.
+      </p>
+    )
+  }
+
+  return (
+    <div className="space-y-4">
+      {comments.map((comment) => (
+        <CommentItem
+          key={comment.id}
+          comment={comment}
+          articleSlug={articleSlug}
+          currentUserId={currentUserId}
+          onRefresh={onRefresh}
+        />
+      ))}
+    </div>
+  )
+}

package/src/CommentsSection.tsx

@@ -0,0 +1,84 @@
+'use client'
+
+import { useSession, signIn } from 'next-auth/react'
+import { useCallback, useEffect, useState } from 'react'
+import { CommentForm } from './CommentForm'
+import { CommentThread } from './CommentThread'
+import type { CommentsConfig } from './articlesConfig'
+import type { ArticleCommentWithReplies } from './commentTypes'
+
+interface CommentsSectionProps {
+  readonly articleSlug: string
+  readonly config: CommentsConfig
+}
+
+export function CommentsSection({ articleSlug, config }: CommentsSectionProps) {
+  const { data: session, status } = useSession()
+  const [comments, setComments] = useState<ArticleCommentWithReplies[]>([])
+  const [loading, setLoading] = useState(true)
+  const [fetchError, setFetchError] = useState<string | null>(null)
+
+  const perArticleEnabled = config.perArticleOverride?.[articleSlug] ?? true
+  const enabled = config.enabled && perArticleEnabled
+
+  const currentUserId = session?.user?.email ?? session?.user?.name ?? undefined
+
+  const fetchComments = useCallback(async () => {
+    setLoading(true)
+    setFetchError(null)
+    try {
+      const res = await fetch(`/api/articles/${articleSlug}/comments`)
+      if (!res.ok) throw new Error('Failed to load comments')
+      const data = (await res.json()) as { comments: ArticleCommentWithReplies[] }
+      setComments(data.comments)
+    } catch {
+      setFetchError('Could not load comments. Please try again.')
+    } finally {
+      setLoading(false)
+    }
+  }, [articleSlug])
+
+  useEffect(() => {
+    if (enabled) {
+      fetchComments().catch(() => undefined)
+    }
+  }, [fetchComments, enabled])
+
+  if (!enabled) return null
+
+  const count = comments.length
+  const label = count === 1 ? '1 comment' : `${count} comments`
+
+  return (
+    <section aria-label="Comments" className="mt-12 pt-8 border-t border-border space-y-6">
+      <h2 className="text-xl font-semibold text-foreground">{loading ? 'Comments' : label}</h2>
+
+      {status === 'authenticated' ? (
+        <CommentForm articleSlug={articleSlug} onSuccess={fetchComments} />
+      ) : (
+        <p className="text-sm text-muted-foreground">
+          <button
+            onClick={() => signIn()}
+            className="text-primary underline hover:no-underline focus:outline-none"
+          >
+            Sign in
+          </button>{' '}
+          to join the discussion.
+        </p>
+      )}
+
+      {fetchError && <p className="text-sm text-destructive">{fetchError}</p>}
+
+      {loading ? (
+        <p className="text-sm text-muted-foreground">Loading comments…</p>
+      ) : (
+        <CommentThread
+          comments={comments}
+          articleSlug={articleSlug}
+          currentUserId={currentUserId}
+          onRefresh={fetchComments}
+        />
+      )}
+    </section>
+  )
+}

package/src/FeaturedArticle.tsx

@@ -0,0 +1,63 @@
+import Link from 'next/link'
+import Image from 'next/image'
+import { ArrowRight, Calendar, Clock, User } from 'lucide-react'
+import type { Article } from './articleTypes'
+
+type FeaturedArticleProps = Readonly<{
+  article: Article
+}>
+
+export function FeaturedArticle({ article }: FeaturedArticleProps) {
+  return (
+    <section className="py-16 bg-background">
+      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+        <div className="grid lg:grid-cols-2 gap-12 items-center">
+          <div>
+            <span className="inline-block bg-primary/10 text-primary text-sm font-medium px-3 py-1 rounded-full mb-4">
+              FEATURED ARTICLE
+            </span>
+            <h2 className="text-3xl font-bold text-foreground mb-4">{article.title}</h2>
+            <p className="text-lg text-muted-foreground mb-6">{article.excerpt}</p>
+            <div className="flex items-center gap-6 text-sm text-muted-foreground mb-6">
+              {article.date && (
+                <div className="flex items-center gap-2">
+                  <Calendar className="h-4 w-4" />
+                  <span>{article.date}</span>
+                </div>
+              )}
+              <div className="flex items-center gap-2">
+                <Clock className="h-4 w-4" />
+                <span>{article.readTime}</span>
+              </div>
+              <div className="flex items-center gap-2">
+                <User className="h-4 w-4" />
+                <span>{article.author}</span>
+              </div>
+            </div>
+            <Link
+              href={`/articles/${article.slug}`}
+              className="inline-flex items-center justify-center px-4 py-2 bg-primary hover:bg-primary/90 text-primary-foreground rounded-md font-medium text-sm transition-colors"
+            >
+              Read Full Article
+              <ArrowRight className="ml-2 h-4 w-4" />
+            </Link>
+          </div>
+          <div className="bg-card rounded-lg p-8">
+            <Image
+              src={article.featuredImage}
+              alt={article.title}
+              width={800}
+              height={450}
+              className="w-full h-64 object-cover rounded-lg mb-4"
+            />
+            <div className="flex gap-2">
+              <span className="bg-primary/10 text-primary text-xs font-medium px-2 py-1 rounded">
+                {article.category}
+              </span>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+  )
+}

package/src/LatestArticles.tsx

@@ -0,0 +1,42 @@
+'use client'
+
+import { useState, useEffect } from 'react'
+import type { Article } from './articleTypes'
+import { ArticleCard } from './ArticleCard'
+
+interface LatestArticlesProps {
+  readonly articles: Article[]
+  readonly pageSize: number
+}
+
+export function LatestArticles({ articles, pageSize }: Readonly<LatestArticlesProps>) {
+  const [visibleCount, setVisibleCount] = useState(pageSize)
+
+  useEffect(() => {
+    setVisibleCount(pageSize)
+  }, [articles, pageSize])
+
+  const visible = articles.slice(0, visibleCount)
+  const hasMore = visibleCount < articles.length
+
+  return (
+    <div>
+      <div className="grid md:grid-cols-2 lg:grid-cols-3 gap-8">
+        {visible.map((article) => (
+          <ArticleCard key={article.slug} article={article} />
+        ))}
+      </div>
+      {hasMore && (
+        <div className="mt-10 text-center">
+          <button
+            type="button"
+            onClick={() => setVisibleCount((c) => c + pageSize)}
+            className="inline-flex items-center justify-center px-4 py-2 border border-input bg-background hover:bg-accent rounded-md font-medium text-sm transition-colors"
+          >
+            Load more articles
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/LatestArticlesSection.tsx

@@ -0,0 +1,68 @@
+'use client'
+
+import { Search } from 'lucide-react'
+import type { Article } from './articleTypes'
+import { LatestArticles } from './LatestArticles'
+
+interface LatestArticlesSectionProps {
+  readonly articles: Article[]
+  readonly searchQuery: string
+  readonly onClearSearch: () => void
+  readonly pageSize?: number
+}
+
+function DescriptionText({
+  searchQuery,
+  count,
+}: {
+  readonly searchQuery: string
+  readonly count: number
+}) {
+  const pluralSuffix = count === 1 ? '' : 's'
+  const text = searchQuery
+    ? `Found ${count} article${pluralSuffix} matching your search.`
+    : 'Stay informed with our latest insights on voter engagement, campaign strategies, and civic technology.'
+  return <p className="text-lg text-muted-foreground">{text}</p>
+}
+
+export function LatestArticlesSection({
+  articles,
+  searchQuery,
+  onClearSearch,
+  pageSize = 6,
+}: Readonly<LatestArticlesSectionProps>) {
+  return (
+    <section id="latest" className="py-16 bg-muted/50">
+      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+        <div className="text-center mb-12">
+          <h2 className="text-3xl font-bold text-foreground mb-4">
+            {searchQuery ? 'Search Results' : 'Latest Articles'}
+          </h2>
+          <DescriptionText searchQuery={searchQuery} count={articles.length} />
+        </div>
+
+        {articles.length === 0 && searchQuery ? (
+          <div className="text-center py-12">
+            <div className="max-w-md mx-auto">
+              <Search className="h-12 w-12 text-muted-foreground mx-auto mb-4" />
+              <h3 className="text-lg font-semibold text-foreground mb-2">No articles found</h3>
+              <p className="text-muted-foreground mb-4">
+                We couldn&apos;t find any articles matching &quot;{searchQuery}&quot;. Try adjusting
+                your search terms.
+              </p>
+              <button
+                type="button"
+                onClick={onClearSearch}
+                className="inline-flex items-center justify-center px-4 py-2 border border-input bg-background hover:bg-accent rounded-md font-medium text-sm transition-colors"
+              >
+                Clear search
+              </button>
+            </div>
+          </div>
+        ) : (
+          <LatestArticles articles={articles} pageSize={pageSize} key={searchQuery} />
+        )}
+      </div>
+    </section>
+  )
+}

package/src/__tests__/ArticleCard.test.tsx

@@ -0,0 +1,78 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import type { Article } from '../articleTypes'
+import { ArticleCard } from '../ArticleCard'
+
+jest.mock('next/link', () => ({
+  __esModule: true,
+  default: ({ href, children }: { href: string; children: React.ReactNode }) => (
+    <a href={href}>{children}</a>
+  ),
+}))
+
+jest.mock('next/image', () => ({
+  __esModule: true,
+  default: (props: React.ComponentProps<'img'>) => <img alt="test" {...props} />,
+}))
+
+const baseArticle: Article = {
+  slug: 'test-article',
+  title: 'Test Article Title',
+  excerpt: 'A short excerpt about the article.',
+  author: 'Jane Doe',
+  category: 'Campaigns',
+  categories: ['Campaigns'],
+  readTime: '5 min read',
+  featuredImage: '/articles/test-article/image.jpg',
+  tags: ['campaigns'],
+}
+
+describe('ArticleCard', () => {
+  it('renders the article title linked to the article page', () => {
+    render(<ArticleCard article={baseArticle} />)
+    const link = screen.getByRole('link', { name: 'Test Article Title' })
+    expect(link).toHaveAttribute('href', '/articles/test-article')
+  })
+
+  it('renders the excerpt', () => {
+    render(<ArticleCard article={baseArticle} />)
+    expect(screen.getByText('A short excerpt about the article.')).toBeInTheDocument()
+  })
+
+  it('renders the category badge', () => {
+    render(<ArticleCard article={baseArticle} />)
+    expect(screen.getByText('Campaigns')).toBeInTheDocument()
+  })
+
+  it('renders the read time', () => {
+    render(<ArticleCard article={baseArticle} />)
+    expect(screen.getByText('5 min read')).toBeInTheDocument()
+  })
+
+  it('renders the featured image with correct alt text', () => {
+    render(<ArticleCard article={baseArticle} />)
+    const img = screen.getByAltText('Test Article Title')
+    expect(img).toBeInTheDocument()
+  })
+
+  it('renders the date when article.date is set', () => {
+    render(<ArticleCard article={{ ...baseArticle, date: '2025-06-15' }} />)
+    expect(screen.getByText('2025-06-15')).toBeInTheDocument()
+  })
+
+  it('does not render a date when article.date is absent', () => {
+    render(<ArticleCard article={baseArticle} />)
+    expect(screen.queryByText(/2025/)).not.toBeInTheDocument()
+  })
+
+  it('arrow link also points to the article page', () => {
+    render(<ArticleCard article={baseArticle} />)
+    const links = screen
+      .getAllByRole('link')
+      .filter((l) => l.getAttribute('href') === '/articles/test-article')
+    expect(links.length).toBeGreaterThanOrEqual(2)
+  })
+})