@xexr/blog-platform 1.1.3 → 1.1.5

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

@@ -28,6 +28,7 @@ import {
   normalizeBlogBasePath,
 } from "../../../lib/urls";
 import { NewsletterSignup } from "../../../components/NewsletterSignup";
+import { SeriesNavigation } from "../../../components/SeriesNavigation";
 import {
   BLOG_PAGE_TITLE_GRADIENT_CLASS,
   type BlogTheme,
@@ -162,8 +163,8 @@ export default function ArticlePage({
   const imageUrl = article.featuredImage;
   const hasFeaturedImageMeta = Boolean(
     article.featuredImageCaption ??
-      article.featuredImageCreditText ??
-      article.featuredImageCreditUrl,
+    article.featuredImageCreditText ??
+    article.featuredImageCreditUrl,
   );
   const resolvedRelatedArticles =
     relatedArticles.length > 0
@@ -386,7 +387,7 @@ export default function ArticlePage({
 
           <div
             id="article-body"
-            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-headings:text-balance prose-headings:text-[var(--blog-text-accent)] 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-p:text-pretty prose-a:text-[var(--blog-text-accent)] prose-a:transition-colors hover:prose-a:text-[var(--blog-text-accent-hover)] [&_figure>p]:!my-0 [&_figcaption]:!mt-2 [&_figcaption]:text-center [&_figcaption]:!text-sm [&_figcaption]:!leading-snug [&_figcaption]:text-muted-foreground [&_figcaption_.blog-image-credit]:mt-1 [&_figcaption_.blog-image-credit]:block [&_figcaption_.blog-image-credit]:text-xs [&_figcaption_.blog-image-credit]:tracking-wide [&_figcaption_.blog-image-credit]:text-muted-foreground/80 [&_figcaption>span:not(.blog-image-credit)]:ml-2 [&_figcaption>span:not(.blog-image-credit)]:border-l [&_figcaption>span:not(.blog-image-credit)]:border-[var(--blog-accent-border)] [&_figcaption>span:not(.blog-image-credit)]:pl-2 [&_figcaption>span:not(.blog-image-credit)]:text-xs [&_figcaption>span:not(.blog-image-credit)]:tracking-wide [&_figcaption>span:not(.blog-image-credit)]:text-muted-foreground/80 max-w-none"
+            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-headings:text-balance prose-headings:text-[var(--blog-text-accent)] 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-p:text-pretty prose-a:text-[var(--blog-text-accent)] prose-a:transition-colors hover:prose-a:text-[var(--blog-text-accent-hover)] [&_figcaption]:text-muted-foreground [&_figcaption_.blog-image-credit]:text-muted-foreground/80 [&_figcaption>span:not(.blog-image-credit)]:text-muted-foreground/80 max-w-none [&_figcaption]:!mt-2 [&_figcaption]:text-center [&_figcaption]:!text-sm [&_figcaption]:!leading-snug [&_figcaption_.blog-image-credit]:mt-1 [&_figcaption_.blog-image-credit]:block [&_figcaption_.blog-image-credit]:text-xs [&_figcaption_.blog-image-credit]:tracking-wide [&_figcaption>span:not(.blog-image-credit)]:ml-2 [&_figcaption>span:not(.blog-image-credit)]:border-l [&_figcaption>span:not(.blog-image-credit)]:border-[var(--blog-accent-border)] [&_figcaption>span:not(.blog-image-credit)]:pl-2 [&_figcaption>span:not(.blog-image-credit)]:text-xs [&_figcaption>span:not(.blog-image-credit)]:tracking-wide [&_figure>p]:!my-0"
           >
             <MDXRemote
               source={article.content}
@@ -404,6 +405,12 @@ export default function ArticlePage({
         />
       </div>
 
+      <SeriesNavigation
+        article={article}
+        basePath={normalizedBasePath}
+        className="mx-auto mt-12 max-w-4xl"
+      />
+
       {/* Author Bio */}
       {article.author?.bio && (
         <div id="about-author" className="author-bio mx-auto mt-12 max-w-4xl">
@@ -823,7 +830,7 @@ function ArticleCardImage({ src, alt }: { src: string; alt: string }) {
         alt={alt}
         width={480}
         height={270}
-        className="h-full w-full object-contain"
+        className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
       />
     </div>
   );

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

@@ -315,7 +315,7 @@ function AuthorArticlePreview({
               }
               width={320}
               height={200}
-              className="h-full w-full object-contain"
+              className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
             />
           </div>
         )}

package/dist/app/blog/page.test.ts

@@ -79,6 +79,26 @@ describe("BlogHomePage", () => {
     expect(html).toContain("Recurring work and routines");
   });
 
+  it("renders article preview images as clipped cover thumbnails", async () => {
+    const html = await renderToHtml(
+      React.createElement(BlogHomePage, {
+        articles: [
+          {
+            ...article,
+            featuredImage: "https://cdn.example.com/articles/routines.webp",
+            featuredImageAlt: "A tidy workspace",
+          },
+        ],
+      }),
+    );
+
+    expect(html).toContain("overflow-hidden rounded-2xl");
+    expect(html).toContain(
+      "h-full w-full object-cover transition-transform duration-300 group-hover:scale-105",
+    );
+    expect(html).not.toContain("h-full w-full object-contain");
+  });
+
   it("renders the newsletter form when configured", async () => {
     const html = await renderToHtml(
       React.createElement(BlogHomePage, {

package/dist/app/blog/page.tsx

@@ -117,6 +117,12 @@ export default function BlogHomePage({
             >
               Topics
             </Link>
+            <Link
+              href={buildBlogPath(normalizedBasePath, "series")}
+              className="text-muted-foreground rounded-full border border-transparent px-3 py-1.5 font-medium transition-colors hover:border-[var(--blog-accent-border)] hover:text-[var(--blog-accent)] hover:no-underline"
+            >
+              Series
+            </Link>
             <Link
               href={buildBlogPath(normalizedBasePath, "authors")}
               className="text-muted-foreground rounded-full border border-transparent px-3 py-1.5 font-medium transition-colors hover:border-[var(--blog-accent-border)] hover:text-[var(--blog-accent)] hover:no-underline"
@@ -240,7 +246,7 @@ function ArticlePreview({
               }
               width={400}
               height={250}
-              className="h-full w-full object-contain"
+              className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
             />
           </Link>
         )}
@@ -282,11 +288,7 @@ function ArticlePreview({
           {(article.topics ?? []).length > 0 && (
             <div className="flex flex-wrap gap-2">
               {(article.topics ?? []).map((topic) => (
-                <TopicChip
-                  key={topic.id}
-                  topic={topic}
-                  basePath={basePath}
-                />
+                <TopicChip key={topic.id} topic={topic} basePath={basePath} />
               ))}
             </div>
           )}
@@ -309,7 +311,7 @@ function ArticlePreview({
               }
               width={288}
               height={180}
-              className="h-full w-full object-contain"
+              className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
             />
           </Link>
         )}
@@ -334,11 +336,7 @@ function ArticlePreview({
             {(article.topics ?? []).length > 0 && (
               <div className="flex flex-wrap gap-2">
                 {(article.topics ?? []).map((topic) => (
-                  <TopicChip
-                    key={topic.id}
-                    topic={topic}
-                    basePath={basePath}
-                  />
+                  <TopicChip key={topic.id} topic={topic} basePath={basePath} />
                 ))}
               </div>
             )}
@@ -383,7 +381,10 @@ function TopicChip({
   }
 
   return (
-    <Link href={buildBlogPath(basePath, `topics/${slug}`)} className={className}>
+    <Link
+      href={buildBlogPath(basePath, `topics/${slug}`)}
+      className={className}
+    >
       {topic.name}
     </Link>
   );

package/dist/app/blog/series/[slug]/page.d.ts

@@ -0,0 +1,28 @@
+import type { ReactElement } from "react";
+import type { PublishedArticle } from "../../../../types/contracts";
+import type { BlogTheme } from "../../../../lib/article-ui";
+
+export interface BlogSeriesArchiveRoutePageProps {
+  articles: PublishedArticle[];
+  seriesSlug: string;
+  basePath?: string;
+  className?: string;
+  theme?: BlogTheme;
+}
+
+export default function BlogSeriesArchiveRoutePage(
+  props: BlogSeriesArchiveRoutePageProps,
+): ReactElement;
+
+export function generateSeriesArchiveMetadata(options: {
+  title: string;
+  description?: string;
+  slug: string;
+  basePath?: string;
+}): {
+  title: string;
+  description: string;
+  alternates: {
+    canonical: string;
+  };
+};

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

@@ -0,0 +1,39 @@
+import React from "react";
+
+import { BlogSeriesArchivePage } from "../../../../components/SeriesArchivePages";
+import type { PublishedArticle } from "../../../../types/contracts";
+import type { BlogTheme } from "../../../../lib/article-ui";
+
+export interface BlogSeriesArchiveRoutePageProps {
+  articles: PublishedArticle[];
+  seriesSlug: string;
+  basePath?: string;
+  className?: string;
+  theme?: BlogTheme;
+}
+
+export default function BlogSeriesArchiveRoutePage(
+  props: BlogSeriesArchiveRoutePageProps,
+) {
+  return <BlogSeriesArchivePage {...props} />;
+}
+
+export function generateSeriesArchiveMetadata({
+  title,
+  description,
+  slug,
+  basePath = "/blog",
+}: {
+  title: string;
+  description?: string;
+  slug: string;
+  basePath?: string;
+}) {
+  return {
+    title,
+    description: description ?? `Read the ${title} article series.`,
+    alternates: {
+      canonical: `${basePath.replace(/\/$/, "")}/series/${slug}`,
+    },
+  };
+}

package/dist/app/blog/series/page.d.ts

@@ -0,0 +1,24 @@
+import type { ReactElement } from "react";
+import type { PublishedArticle } from "../../../types/contracts";
+import type { BlogTheme } from "../../../lib/article-ui";
+
+export interface BlogSeriesPageProps {
+  articles: PublishedArticle[];
+  basePath?: string;
+  title?: string;
+  description?: string;
+  className?: string;
+  theme?: BlogTheme;
+}
+
+export default function BlogSeriesPage(
+  props: BlogSeriesPageProps,
+): ReactElement;
+
+export function generateSeriesIndexMetadata(basePath?: string): {
+  title: string;
+  description: string;
+  alternates: {
+    canonical: string;
+  };
+};

package/dist/app/blog/series/page.tsx

@@ -0,0 +1,28 @@
+import React from "react";
+
+import { BlogSeriesIndexPage } from "../../../components/SeriesArchivePages";
+import type { PublishedArticle } from "../../../types/contracts";
+import type { BlogTheme } from "../../../lib/article-ui";
+
+export interface BlogSeriesPageProps {
+  articles: PublishedArticle[];
+  basePath?: string;
+  title?: string;
+  description?: string;
+  className?: string;
+  theme?: BlogTheme;
+}
+
+export default function BlogSeriesPage(props: BlogSeriesPageProps) {
+  return <BlogSeriesIndexPage {...props} />;
+}
+
+export function generateSeriesIndexMetadata(basePath = "/blog") {
+  return {
+    title: "Series",
+    description: "Browse related article series.",
+    alternates: {
+      canonical: `${basePath.replace(/\/$/, "")}/series`,
+    },
+  };
+}

package/dist/components/SeriesArchivePages.tsx

@@ -0,0 +1,212 @@
+import React from "react";
+import Image from "next/image.js";
+import Link from "next/link.js";
+import { formatDistanceToNow } from "date-fns";
+
+import type { PublishedArticle } from "../types/contracts";
+import type { BlogTheme } from "../lib/article-ui";
+import {
+  BLOG_PAGE_TITLE_GRADIENT_CLASS,
+  getBlogThemeStyle,
+} from "../lib/article-ui";
+import { getAllSeries, getSeriesArchive } from "../lib/series";
+import {
+  buildBlogPath,
+  buildSeriesPath,
+  normalizeBlogBasePath,
+} from "../lib/urls";
+import { cn } from "../lib/utils";
+
+interface BlogSeriesIndexPageProps {
+  articles: PublishedArticle[];
+  basePath?: string;
+  title?: string;
+  description?: string;
+  className?: string;
+  theme?: BlogTheme;
+}
+
+interface BlogSeriesArchivePageProps {
+  articles: PublishedArticle[];
+  seriesSlug: string;
+  basePath?: string;
+  className?: string;
+  theme?: BlogTheme;
+}
+
+export function BlogSeriesIndexPage({
+  articles,
+  basePath = "/blog",
+  title = "Series",
+  description = "Browse related article series.",
+  className,
+  theme,
+}: BlogSeriesIndexPageProps) {
+  const normalizedBasePath = normalizeBlogBasePath(basePath) || "/";
+  const allSeries = getAllSeries(articles);
+
+  return (
+    <main
+      style={getBlogThemeStyle(theme)}
+      className={cn(
+        "blog-series-page container mx-auto max-w-5xl px-4 py-8 sm:px-6 sm:py-12 lg:px-8 lg:py-16",
+        className,
+      )}
+    >
+      <header className="mb-10 space-y-3 text-center">
+        <Link
+          href={normalizedBasePath}
+          className="text-muted-foreground text-sm font-medium transition-colors hover:text-[var(--blog-accent)]"
+        >
+          Back to all articles
+        </Link>
+        <h1
+          className={cn(
+            "text-4xl font-light tracking-tight text-balance sm:text-5xl",
+            BLOG_PAGE_TITLE_GRADIENT_CLASS,
+          )}
+        >
+          {title}
+        </h1>
+        <p className="text-muted-foreground mx-auto max-w-2xl text-lg text-pretty">
+          {description}
+        </p>
+      </header>
+
+      {allSeries.length === 0 ? (
+        <p className="text-muted-foreground rounded-2xl border p-8 text-center">
+          No series have published articles yet.
+        </p>
+      ) : (
+        <div className="grid gap-4 md:grid-cols-2">
+          {allSeries.map((series) => (
+            <Link
+              key={series.slug}
+              href={buildSeriesPath(normalizedBasePath, series.slug)}
+              className="group rounded-2xl border border-[var(--blog-accent-border)] bg-[var(--blog-card-bg)] p-5 transition hover:border-[var(--blog-accent)] hover:no-underline"
+            >
+              <p className="text-muted-foreground mb-2 text-sm font-medium">
+                {series.total} {series.total === 1 ? "article" : "articles"}
+              </p>
+              <h2 className="text-xl font-semibold transition-colors group-hover:text-[var(--blog-accent)]">
+                {series.title}
+              </h2>
+              {series.description && (
+                <p className="text-muted-foreground mt-2 line-clamp-3 text-sm leading-relaxed">
+                  {series.description}
+                </p>
+              )}
+            </Link>
+          ))}
+        </div>
+      )}
+    </main>
+  );
+}
+
+export function BlogSeriesArchivePage({
+  articles,
+  seriesSlug,
+  basePath = "/blog",
+  className,
+  theme,
+}: BlogSeriesArchivePageProps) {
+  const normalizedBasePath = normalizeBlogBasePath(basePath) || "/";
+  const archive = getSeriesArchive(articles, seriesSlug);
+
+  return (
+    <main
+      style={getBlogThemeStyle(theme)}
+      className={cn(
+        "blog-series-archive-page container mx-auto max-w-5xl px-4 py-8 sm:px-6 sm:py-12 lg:px-8 lg:py-16",
+        className,
+      )}
+    >
+      <header className="mb-10 space-y-3 text-center">
+        <Link
+          href={buildBlogPath(normalizedBasePath, "series")}
+          className="text-muted-foreground text-sm font-medium transition-colors hover:text-[var(--blog-accent)]"
+        >
+          Back to all series
+        </Link>
+        <h1
+          className={cn(
+            "text-4xl font-light tracking-tight text-balance sm:text-5xl",
+            BLOG_PAGE_TITLE_GRADIENT_CLASS,
+          )}
+        >
+          {archive?.series.title ?? "Series not found"}
+        </h1>
+        {archive?.series.description && (
+          <p className="text-muted-foreground mx-auto max-w-2xl text-lg text-pretty">
+            {archive.series.description}
+          </p>
+        )}
+      </header>
+
+      {!archive ? (
+        <p className="text-muted-foreground rounded-2xl border p-8 text-center">
+          No published articles were found for this series.
+        </p>
+      ) : (
+        <div className="grid gap-5 md:grid-cols-2">
+          {archive.articles.map((article) => (
+            <SeriesArticleCard
+              key={article.id}
+              article={article}
+              basePath={normalizedBasePath}
+            />
+          ))}
+        </div>
+      )}
+    </main>
+  );
+}
+
+function SeriesArticleCard({
+  article,
+  basePath,
+}: {
+  article: PublishedArticle;
+  basePath: string;
+}) {
+  const articleUrl = buildBlogPath(basePath, article.slug);
+  const publishedAgo = formatDistanceToNow(new Date(article.publishedAt), {
+    addSuffix: true,
+  });
+
+  return (
+    <Link
+      href={articleUrl}
+      className="group overflow-hidden rounded-2xl border border-[var(--blog-accent-border)] bg-[var(--blog-card-bg)] transition hover:border-[var(--blog-accent)] hover:no-underline"
+    >
+      {article.featuredImage && (
+        <div className="relative aspect-[16/9] overflow-hidden">
+          <Image
+            src={article.featuredImage}
+            alt={article.featuredImageAlt ?? article.title}
+            width={640}
+            height={360}
+            className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
+          />
+        </div>
+      )}
+      <div className="space-y-3 p-5">
+        {article.series && (
+          <span className="inline-flex rounded-full border border-[var(--blog-accent-border)] px-2.5 py-1 text-xs font-medium text-[var(--blog-text-accent)]">
+            Part {article.series.position}
+          </span>
+        )}
+        <h2 className="text-xl font-semibold text-balance transition-colors group-hover:text-[var(--blog-accent)]">
+          {article.title}
+        </h2>
+        {article.excerpt && (
+          <p className="text-muted-foreground line-clamp-3 text-sm leading-relaxed">
+            {article.excerpt}
+          </p>
+        )}
+        <p className="text-muted-foreground text-sm">{publishedAgo}</p>
+      </div>
+    </Link>
+  );
+}

package/dist/components/SeriesNavigation.tsx

@@ -0,0 +1,117 @@
+import React from "react";
+import Link from "next/link.js";
+
+import type { PublishedArticle } from "../types/contracts";
+import { buildBlogPath, buildSeriesPath } from "../lib/urls";
+import { cn } from "../lib/utils";
+
+interface SeriesNavigationProps {
+  article: PublishedArticle;
+  basePath?: string;
+  className?: string;
+}
+
+export function SeriesNavigation({
+  article,
+  basePath = "/blog",
+  className,
+}: SeriesNavigationProps) {
+  const series = article.series;
+
+  if (!series) {
+    return null;
+  }
+
+  return (
+    <section
+      aria-labelledby="article-series-title"
+      className={cn(
+        "rounded-2xl border border-[var(--blog-accent-border)] bg-[var(--blog-accent-bg)] p-5 sm:p-6",
+        className,
+      )}
+    >
+      <div className="flex flex-col gap-5 md:flex-row md:items-start md:justify-between">
+        <div className="space-y-2">
+          <p className="text-muted-foreground text-sm font-medium">
+            Part {series.position} of {series.total}
+          </p>
+          <h2 id="article-series-title" className="text-xl font-semibold">
+            <Link
+              href={buildSeriesPath(basePath, series.slug)}
+              className="transition-colors hover:text-[var(--blog-accent)] hover:no-underline"
+            >
+              {series.title}
+            </Link>
+          </h2>
+          {series.description && (
+            <p className="text-muted-foreground max-w-2xl leading-relaxed">
+              {series.description}
+            </p>
+          )}
+        </div>
+
+        {(series.previous ?? series.next) && (
+          <div className="grid shrink-0 gap-2 sm:grid-cols-2 md:min-w-64 md:grid-cols-1">
+            {series.previous && (
+              <Link
+                href={buildBlogPath(basePath, series.previous.slug)}
+                className="rounded-xl border border-[var(--blog-accent-border)] bg-[var(--blog-card-bg)] px-3 py-2 text-sm transition-colors hover:border-[var(--blog-accent)] hover:no-underline"
+              >
+                <span className="text-muted-foreground block text-xs">
+                  Previous
+                </span>
+                <span className="line-clamp-2 font-medium">
+                  {series.previous.title}
+                </span>
+              </Link>
+            )}
+            {series.next && (
+              <Link
+                href={buildBlogPath(basePath, series.next.slug)}
+                className="rounded-xl border border-[var(--blog-accent-border)] bg-[var(--blog-card-bg)] px-3 py-2 text-sm transition-colors hover:border-[var(--blog-accent)] hover:no-underline"
+              >
+                <span className="text-muted-foreground block text-xs">
+                  Next
+                </span>
+                <span className="line-clamp-2 font-medium">
+                  {series.next.title}
+                </span>
+              </Link>
+            )}
+          </div>
+        )}
+      </div>
+
+      {series.articles.length > 0 && (
+        <ol className="mt-5 grid gap-2">
+          {series.articles.map((seriesArticle) => (
+            <li key={seriesArticle.id}>
+              <Link
+                href={buildBlogPath(basePath, seriesArticle.slug)}
+                aria-current={seriesArticle.isCurrent ? "page" : undefined}
+                className={cn(
+                  "hover:bg-background/60 flex gap-3 rounded-xl px-3 py-2 text-sm transition-colors hover:no-underline",
+                  seriesArticle.isCurrent && "bg-background/70",
+                )}
+              >
+                <span className="text-muted-foreground shrink-0 tabular-nums">
+                  {seriesArticle.position}
+                </span>
+                <span
+                  className={cn(
+                    "line-clamp-2",
+                    seriesArticle.isCurrent
+                      ? "font-semibold text-[var(--blog-text-accent)]"
+                      : "font-medium",
+                  )}
+                >
+                  {seriesArticle.title}
+                </span>
+              </Link>
+            </li>
+          ))}
+        </ol>
+      )}
+    </section>
+  );
+}

package/dist/components/TopicArchivePages.test.ts

@@ -76,4 +76,26 @@ describe("Blog topic archive pages", () => {
     expect(html).toContain("via-[var(--blog-text-accent)]");
     expect(html).toContain("to-fuchsia-200");
   });
+
+  it("renders topic archive article images as clipped cover thumbnails", () => {
+    const html = renderToStaticMarkup(
+      React.createElement(BlogTopicArchivePage, {
+        articles: [
+          {
+            ...article,
+            featuredImage: "https://cdn.example.com/articles/routines.webp",
+            featuredImageAlt: "A tidy workspace",
+          },
+        ],
+        topicSlug: "recurring-work-and-routines",
+        basePath: "/new-blog",
+      }),
+    );
+
+    expect(html).toContain("overflow-hidden rounded-2xl");
+    expect(html).toContain(
+      "h-full w-full object-cover transition-transform duration-300 group-hover:scale-105",
+    );
+    expect(html).not.toContain("h-full w-full object-contain");
+  });
 });

package/dist/components/TopicArchivePages.tsx

@@ -194,7 +194,7 @@ function TopicArticleCard({
             alt={article.featuredImageAlt ?? article.title}
             width={640}
             height={360}
-            className="h-full w-full object-contain"
+            className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
           />
         </div>
       )}