@xexr/blog-platform 0.2.0

package/dist/app/blog/[slug]/page.tsx

@@ -0,0 +1,304 @@
+import React from "react";
+import Image from "next/image";
+import Link from "next/link";
+import { MDXRemote } from "next-mdx-remote-client/rsc";
+import { type PublishedArticle } from "../../../types/contracts";
+import { format, formatDistanceToNow } from "date-fns";
+import { cn } from "../../../lib/utils";
+import { ArrowLeft } from "lucide-react";
+import { Badge } from "../../../components/ui/badge";
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "../../../components/ui/card";
+import { Separator } from "../../../components/ui/separator";
+import {
+  generateCompleteArticleStructuredData,
+  createStructuredDataScript,
+} from "../../../lib/structured-data";
+
+interface ArticlePageProps {
+  article: PublishedArticle;
+  className?: string;
+  /** Optional navigation links */
+  navigation?: {
+    backToHome?: {
+      url: string;
+      label?: string;
+    };
+    previousArticle?: {
+      url: string;
+      title: string;
+    };
+    nextArticle?: {
+      url: string;
+      title: string;
+    };
+  };
+}
+
+/**
+ * Individual article page component that displays full article content.
+ *
+ * This component is designed to be used by customers who install the
+ * @xexr/blog-platform package. It provides a complete article view
+ * with proper SEO metadata, structured data, and accessibility features.
+ */
+/**
+ * Helper function to format reading time in minutes
+ */
+function formatReadingTime(seconds: number): string {
+  const minutes = Math.ceil(seconds / 60);
+  return `${minutes} min read`;
+}
+
+export default function ArticlePage({
+  article,
+  className,
+  navigation,
+}: ArticlePageProps) {
+  const publishedDate = new Date(article.publishedAt);
+  const updatedDate = new Date(article.updatedAt);
+  const isUpdated = updatedDate.getTime() !== publishedDate.getTime();
+  const formattedDate = formatDistanceToNow(publishedDate, { addSuffix: true });
+  const readingTime = formatReadingTime(article.readingSeconds);
+
+  // Use the featured image URL provided by Bloggy (hosted on Bloggy's domain)
+  const imageUrl = article.featuredImage;
+
+  return (
+    <article
+      className={cn(
+        "article-page mx-auto max-w-4xl px-4 py-6 pb-12 sm:px-6 sm:py-8 sm:pb-16 lg:px-8 lg:py-12 lg:pb-24",
+        className,
+      )}
+    >
+      {/* Navigation */}
+      {navigation?.backToHome && (
+        <header className="mb-8 sm:mb-12 lg:mb-16">
+          <Link
+            href={navigation.backToHome.url}
+            className="text-muted-foreground hover:text-foreground group focus-visible:ring-ring inline-flex touch-manipulation items-center space-x-2 rounded-md px-2 py-1 transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none sm:space-x-3"
+            aria-label={navigation.backToHome.label ?? "Return to blog"}
+          >
+            <ArrowLeft
+              className="h-4 w-4 transition-transform group-hover:-translate-x-1 sm:h-5 sm:w-5"
+              aria-hidden="true"
+            />
+            <span className="text-sm font-medium sm:text-base">
+              <span className="hidden sm:inline">
+                {navigation.backToHome.label ?? "Back to all articles"}
+              </span>
+              <span className="sm:hidden">Back</span>
+            </span>
+          </Link>
+        </header>
+      )}
+
+      {/* Article Header */}
+      <header className="article-header mb-6 space-y-4 text-center sm:mb-8 sm:space-y-6 lg:mb-12 lg:space-y-8">
+        {/* Title */}
+        <h1 className="article-title text-foreground px-4 text-2xl leading-tight font-light tracking-tight sm:px-0 sm:text-3xl md:text-4xl lg:text-5xl xl:text-6xl">
+          {article.title}
+        </h1>
+
+        {/* Excerpt */}
+        {article.excerpt && (
+          <p className="article-excerpt text-muted-foreground mx-auto mt-6 max-w-xs px-4 text-base leading-relaxed sm:mt-8 sm:max-w-lg sm:px-0 sm:text-lg md:max-w-2xl md:text-xl lg:max-w-4xl lg:text-2xl">
+            {article.excerpt}
+          </p>
+        )}
+
+        {/* Article Metadata */}
+        <div className="article-meta text-muted-foreground flex flex-col items-center gap-2 text-sm sm:gap-3 sm:text-base">
+          {article.author && (
+            <div className="flex items-center gap-2">
+              <span className="sr-only">Author</span>
+              <span className="font-medium">{article.author.name}</span>
+              {article.author.isGuest && (
+                <Badge variant="outline" className="text-xs">
+                  Guest Author
+                </Badge>
+              )}
+            </div>
+          )}
+
+          <div className="flex flex-wrap items-center justify-center gap-x-3 gap-y-1">
+            <time
+              dateTime={article.publishedAt}
+              className="font-medium"
+              aria-label={`Published ${formattedDate}`}
+            >
+              Published {formattedDate}
+            </time>
+            <span className="text-border">•</span>
+            <span className="font-medium">{readingTime}</span>
+          </div>
+
+          {isUpdated && (
+            <time dateTime={article.updatedAt} className="text-xs">
+              Updated {format(updatedDate, "MMMM d, yyyy")}
+            </time>
+          )}
+
+          <div className="bg-border h-px w-6 sm:w-8" aria-hidden="true"></div>
+
+          <span
+            className="text-xs tracking-wider uppercase sm:text-sm"
+            role="text"
+          >
+            From {article.site.name}
+          </span>
+        </div>
+      </header>
+
+      {/* Featured Image */}
+      {imageUrl && (
+        <div className="article-featured-image relative my-8 aspect-[16/9] w-full overflow-hidden rounded-lg sm:my-12 lg:my-16">
+          <Image
+            src={imageUrl}
+            alt={
+              article.featuredImageAlt ?? `Featured image for ${article.title}`
+            }
+            className="h-full w-full object-cover"
+            width={800}
+            height={450}
+            priority
+          />
+        </div>
+      )}
+
+      {/* Article Content */}
+      <div className="article-content">
+        <div className="prose prose-sm sm:prose-base lg:prose-lg xl:prose-xl prose-gray dark:prose-invert prose-headings:scroll-mt-20 prose-headings:font-light prose-h1:text-2xl sm:prose-h1:text-3xl lg:prose-h1:text-4xl prose-h2:text-xl sm:prose-h2:text-2xl lg:prose-h2:text-3xl prose-h3:text-lg sm:prose-h3:text-xl lg:prose-h3:text-2xl prose-p:leading-relaxed prose-img:mx-auto prose-img:rounded-lg prose-a:transition-colors max-w-none">
+          <MDXRemote source={article.content} />
+        </div>
+      </div>
+
+      {/* Author Bio */}
+      {article.author?.bio && (
+        <div className="author-bio mt-12">
+          <Separator className="mb-8" />
+          <Card>
+            <CardHeader>
+              <CardTitle className="flex items-center gap-2">
+                About {article.author.name}
+                {article.author.isGuest && (
+                  <Badge variant="outline" className="text-xs">
+                    Guest Author
+                  </Badge>
+                )}
+              </CardTitle>
+            </CardHeader>
+            <CardContent>
+              <div className="prose dark:prose-invert">
+                <p className="text-muted-foreground">{article.author.bio}</p>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      )}
+
+      {/* Article Navigation */}
+      {(Boolean(navigation?.previousArticle) ||
+        Boolean(navigation?.nextArticle)) && (
+        <nav className="article-nav mt-12">
+          <Separator className="mb-8" />
+          <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+            {navigation?.previousArticle && (
+              <Card className="group hover:bg-accent/50 cursor-pointer transition-colors">
+                <Link href={navigation.previousArticle.url} className="block">
+                  <CardContent className="p-4">
+                    <div className="text-muted-foreground mb-2 text-sm font-medium">
+                      ← Previous Article
+                    </div>
+                    <div className="text-foreground group-hover:text-primary transition-colors">
+                      {navigation.previousArticle.title}
+                    </div>
+                  </CardContent>
+                </Link>
+              </Card>
+            )}
+            {navigation?.nextArticle && (
+              <Card
+                className={cn(
+                  "group hover:bg-accent/50 cursor-pointer transition-colors",
+                  !navigation?.previousArticle && "md:col-start-2",
+                )}
+              >
+                <Link href={navigation.nextArticle.url} className="block">
+                  <CardContent className="p-4 md:text-right">
+                    <div className="text-muted-foreground mb-2 text-sm font-medium">
+                      Next Article →
+                    </div>
+                    <div className="text-foreground group-hover:text-primary transition-colors">
+                      {navigation.nextArticle.title}
+                    </div>
+                  </CardContent>
+                </Link>
+              </Card>
+            )}
+          </div>
+        </nav>
+      )}
+
+      {/* JSON-LD Structured Data */}
+      {(() => {
+        const structuredDataProps = createStructuredDataScript(
+          generateCompleteArticleStructuredData(article),
+        );
+        return (
+          <script
+            type={structuredDataProps.type}
+            dangerouslySetInnerHTML={
+              structuredDataProps.dangerouslySetInnerHTML
+            }
+          />
+        );
+      })()}
+    </article>
+  );
+}
+
+/**
+ * Generate metadata for the article page for SEO optimization.
+ * This function should be used in the Next.js metadata API.
+ */
+export function generateArticleMetadata(article: PublishedArticle) {
+  const title = article.meta.title ?? article.title;
+  const description = article.meta.description ?? article.excerpt;
+  const canonicalUrl =
+    article.meta.canonicalUrl ?? `${article.site.domain}/blog/${article.slug}`;
+  const ogImage = article.meta.ogImage ?? article.featuredImage;
+
+  return {
+    title,
+    description,
+    keywords: article.meta.keywords.join(", "),
+    authors: article.author ? [{ name: article.author.name }] : undefined,
+    openGraph: {
+      title,
+      description,
+      type: "article",
+      url: canonicalUrl,
+      images: ogImage
+        ? [{ url: ogImage, alt: article.featuredImageAlt ?? title }]
+        : undefined,
+      publishedTime: article.publishedAt,
+      modifiedTime: article.updatedAt,
+      authors: article.author ? [article.author.name] : undefined,
+      siteName: article.site.name,
+    },
+    twitter: {
+      card: "summary_large_image",
+      title,
+      description,
+      images: ogImage ? [ogImage] : undefined,
+    },
+    alternates: {
+      canonical: canonicalUrl,
+    },
+  };
+}

package/dist/app/blog/page.tsx

@@ -0,0 +1,316 @@
+import React from "react";
+import Link from "next/link";
+import Image from "next/image";
+import {
+  type PublishedArticle,
+  type PublishedSite,
+} from "../../types/contracts";
+import { cn } from "../../lib/utils";
+import Pagination from "../../components/Pagination";
+import {
+  generateBlogHomeStructuredData,
+  createStructuredDataScript,
+} from "../../lib/structured-data";
+import { formatDistanceToNow } from "date-fns";
+
+interface BlogHomePageProps {
+  articles: PublishedArticle[];
+  siteName?: string;
+  siteTagline?: string;
+  className?: string;
+  /** Site data for structured data generation */
+  site?: PublishedSite;
+  /** Whether to include structured data */
+  includeStructuredData?: boolean;
+  /** Pagination configuration */
+  pagination?: {
+    currentPage: number;
+    totalPages: number;
+    baseUrl?: string;
+  };
+}
+
+/**
+ * Blog home page component that displays a list of published articles.
+ *
+ * This component is designed to be used by customers who install the
+ * @xexr/blog-platform package. It provides a clean, SEO-friendly
+ * article listing with proper metadata.
+ */
+export default function BlogHomePage({
+  articles,
+  siteName,
+  siteTagline,
+  className,
+  site,
+  includeStructuredData = false,
+  pagination,
+}: BlogHomePageProps) {
+  return (
+    <div
+      className={cn(
+        "blog-home-page container mx-auto max-w-5xl px-4 py-8 sm:px-6 sm:py-12 lg:px-8 lg:py-16",
+        className,
+      )}
+    >
+      {/* Site Header */}
+      {siteName && (
+        <header className="blog-header mb-8 text-center sm:mb-12 lg:mb-16">
+          <h1 className="blog-title text-foreground mb-2 text-3xl font-light tracking-tight sm:text-4xl lg:text-5xl">
+            {siteName}
+          </h1>
+          {siteTagline && (
+            <p className="blog-tagline text-muted-foreground text-base sm:text-lg">
+              {siteTagline}
+            </p>
+          )}
+        </header>
+      )}
+
+      {/* Articles List */}
+      <main className="articles-list">
+        {articles.length === 0 ? (
+          <div className="no-articles text-muted-foreground py-16 text-center sm:py-24 lg:py-32">
+            <h2 className="mb-3 text-xl font-light sm:mb-4 sm:text-2xl lg:text-3xl">
+              No articles yet
+            </h2>
+            <p className="text-muted-foreground/70 mx-auto max-w-md text-base sm:text-lg">
+              This blog doesn&apos;t have any published articles yet.
+            </p>
+          </div>
+        ) : (
+          <div className="space-y-0">
+            {articles.map((article) => (
+              <ArticlePreview key={article.id} article={article} />
+            ))}
+          </div>
+        )}
+
+        {/* Pagination */}
+        {pagination && pagination.totalPages > 1 && (
+          <div className="pagination-wrapper mt-12">
+            <Pagination
+              currentPage={pagination.currentPage}
+              totalPages={pagination.totalPages}
+              baseUrl={pagination.baseUrl ?? "/blog"}
+              className="justify-center"
+            />
+          </div>
+        )}
+      </main>
+
+      {/* JSON-LD Structured Data */}
+      {includeStructuredData &&
+        site &&
+        (() => {
+          const structuredDataProps = createStructuredDataScript(
+            generateBlogHomeStructuredData(site, articles.slice(0, 5)),
+          );
+          return (
+            <script
+              type={structuredDataProps.type}
+              dangerouslySetInnerHTML={
+                structuredDataProps.dangerouslySetInnerHTML
+              }
+            />
+          );
+        })()}
+    </div>
+  );
+}
+
+/**
+ * Helper function to format reading time in minutes
+ */
+function formatReadingTime(seconds: number): string {
+  const minutes = Math.ceil(seconds / 60);
+  return `${minutes} min read`;
+}
+
+/**
+ * Individual article preview component for the blog listing.
+ */
+function ArticlePreview({ article }: { article: PublishedArticle }) {
+  const articleUrl = `/blog/${article.slug}`;
+  const formattedDate = formatDistanceToNow(new Date(article.publishedAt), {
+    addSuffix: true,
+  });
+  const readingTime = formatReadingTime(article.readingSeconds);
+
+  // Use the featured image URL provided by Bloggy (hosted on Bloggy's domain)
+  const imageUrl = article.featuredImage;
+
+  return (
+    <article className="group border-border mb-6 block border-b pb-6 last:mb-0 last:border-b-0 last:pb-0 sm:mb-8 sm:pb-8">
+      <Link
+        href={articleUrl}
+        className="focus-visible:ring-ring block rounded-lg hover:no-underline focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none"
+        aria-label={`Read article: ${article.title}`}
+      >
+        {/* Mobile/Small Tablet: Vertical layout */}
+        <div className="space-y-4 lg:hidden">
+          {imageUrl && (
+            <div className="relative aspect-[16/10] w-full overflow-hidden rounded-lg">
+              <Image
+                src={imageUrl}
+                alt={
+                  article.featuredImageAlt ??
+                  `Featured image for ${article.title}`
+                }
+                width={400}
+                height={250}
+                className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
+              />
+            </div>
+          )}
+
+          <div className="space-y-3">
+            <h2 className="group-hover:text-primary text-lg leading-tight font-bold transition-colors sm:text-xl md:text-2xl">
+              {article.title}
+            </h2>
+
+            <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground">
+              {article.author && (
+                <>
+                  <span className="font-medium">{article.author.name}</span>
+                  <span className="text-border">•</span>
+                </>
+              )}
+              <time
+                dateTime={article.publishedAt}
+                className="font-medium"
+                aria-label={`Published ${formattedDate}`}
+              >
+                {formattedDate}
+              </time>
+              <span className="text-border">•</span>
+              <span className="font-medium">{readingTime}</span>
+            </div>
+
+            {article.excerpt && (
+              <p className="text-muted-foreground line-clamp-3 text-sm leading-relaxed sm:text-base">
+                {article.excerpt}
+              </p>
+            )}
+          </div>
+        </div>
+
+        {/* Large Tablet/Desktop: Horizontal layout */}
+        <div className="hidden items-start gap-6 lg:flex xl:gap-8">
+          {imageUrl && (
+            <div className="relative aspect-[16/10] w-64 shrink-0 overflow-hidden rounded-lg xl:w-72">
+              <Image
+                src={imageUrl}
+                alt={
+                  article.featuredImageAlt ??
+                  `Featured image for ${article.title}`
+                }
+                width={288}
+                height={180}
+                className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
+              />
+            </div>
+          )}
+
+          <div className="flex min-h-[180px] flex-1 flex-col justify-between space-y-4 xl:min-h-[200px]">
+            <div className="space-y-4">
+              <h2 className="group-hover:text-primary text-2xl leading-tight font-bold transition-colors xl:text-3xl">
+                {article.title}
+              </h2>
+
+              {article.excerpt && (
+                <p className="text-muted-foreground line-clamp-3 text-base leading-relaxed xl:text-lg">
+                  {article.excerpt}
+                </p>
+              )}
+            </div>
+
+            <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground">
+              {article.author && (
+                <>
+                  <span className="font-medium">{article.author.name}</span>
+                  <span className="text-border">•</span>
+                </>
+              )}
+              <time
+                dateTime={article.publishedAt}
+                className="font-medium"
+                aria-label={`Published ${formattedDate}`}
+              >
+                {formattedDate}
+              </time>
+              <span className="text-border">•</span>
+              <span className="font-medium">{readingTime}</span>
+            </div>
+          </div>
+        </div>
+      </Link>
+    </article>
+  );
+}
+
+/**
+ * Generate metadata for the blog home page for SEO optimization.
+ * This function should be used in the Next.js metadata API.
+ */
+export function generateBlogHomeMetadata(
+  siteName?: string,
+  siteDescription?: string,
+  siteUrl?: string,
+  pagination?: {
+    currentPage: number;
+    totalPages: number;
+  },
+) {
+  const baseTitle = siteName ? `${siteName} - Blog` : "Blog";
+  const title =
+    pagination && pagination.currentPage > 1
+      ? `${baseTitle} - Page ${pagination.currentPage}`
+      : baseTitle;
+
+  const description =
+    siteDescription ?? "Read our latest articles and insights.";
+
+  // Generate pagination URLs for SEO
+  const baseUrl = "/blog";
+  const canonicalUrl = siteUrl
+    ? `${siteUrl}${pagination && pagination.currentPage > 1 ? `${baseUrl}?page=${pagination.currentPage}` : baseUrl}`
+    : undefined;
+
+  const prevUrl =
+    pagination && pagination.currentPage > 1
+      ? siteUrl
+        ? `${siteUrl}${pagination.currentPage === 2 ? baseUrl : `${baseUrl}?page=${pagination.currentPage - 1}`}`
+        : undefined
+      : undefined;
+
+  const nextUrl =
+    pagination && pagination.currentPage < pagination.totalPages
+      ? siteUrl
+        ? `${siteUrl}${baseUrl}?page=${pagination.currentPage + 1}`
+        : undefined
+      : undefined;
+
+  return {
+    title,
+    description,
+    openGraph: {
+      title,
+      description,
+      type: "website",
+      ...(siteUrl && { url: canonicalUrl }),
+    },
+    twitter: {
+      card: "summary_large_image",
+      title,
+      description,
+    },
+    alternates: {
+      ...(canonicalUrl && { canonical: canonicalUrl }),
+    },
+    other: {
+      ...(prevUrl && { prev: prevUrl }),
+      ...(nextUrl && { next: nextUrl }),
+    },
+  };
+}