@xexr/blog-platform 1.0.9 → 1.0.11

package/README.md

@@ -237,7 +237,7 @@ export default async function ArticlePage({
 }
 ```
 
-> **Note**: The `navigation` prop is optional. You can omit `previousArticle` and `nextArticle` if you don't want article navigation links.
+> **Note**: The `navigation` prop is optional. You can omit `previousArticle` and `nextArticle` if you don't want article navigation links. Bloggy can also publish a site-scoped `newsletter` configuration; pass it through to `BlogHomePage` or `BlogArticlePage` if you are not using the article/site objects returned by Bloggy storage directly. The newsletter form posts back to Bloggy's `/api/newsletter/subscribe` endpoint so subscribers are captured consistently across host apps.
 
 **`app/blog/authors/[slug]/page.tsx`** - Author profile pages:
 

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

@@ -1,8 +1,11 @@
 import type { ReactElement } from "react";
-import type { PublishedArticle } from "../../../types/contracts";
+import type {
+  PublishedArticle,
+  PublishedNewsletterSettings,
+} from "../../../types/contracts";
 import type { BlogTheme } from "../../../lib/article-ui";
 
-interface ArticlePageProps {
+export interface ArticlePageProps {
   article: PublishedArticle;
   className?: string;
   navigation?: {
@@ -31,6 +34,8 @@ interface ArticlePageProps {
     href: string;
     label: string;
   };
+  newsletter?: PublishedNewsletterSettings;
+  newsletterPreviewMode?: boolean;
   relatedArticles?: PublishedArticle[];
   showShareLinks?: boolean;
 }

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

@@ -5,6 +5,7 @@ import { MDXRemote } from "next-mdx-remote-client/rsc";
 import {
   type PublishedArticle,
   type PublishedAuthor,
+  type PublishedNewsletterSettings,
 } from "../../../types/contracts";
 import { cn } from "../../../lib/utils";
 import { ArrowLeft, ArrowUpRight, Globe, Mail } from "lucide-react";
@@ -25,6 +26,7 @@ import {
   buildBlogPath,
   normalizeBlogBasePath,
 } from "../../../lib/urls";
+import { NewsletterSignup } from "../../../components/NewsletterSignup";
 import {
   type BlogTheme,
   extractTableOfContents,
@@ -32,7 +34,7 @@ import {
   getBlogThemeStyle,
 } from "../../../lib/article-ui";
 
-interface ArticlePageProps {
+export interface ArticlePageProps {
   article: PublishedArticle;
   className?: string;
   /** Optional navigation links */
@@ -65,6 +67,10 @@ interface ArticlePageProps {
     href: string;
     label: string;
   };
+  /** Optional Bloggy-owned newsletter capture configuration. */
+  newsletter?: PublishedNewsletterSettings;
+  /** Render interactive preview success without persisting subscribers. */
+  newsletterPreviewMode?: boolean;
   /** Optional related articles supplied by the host site. */
   relatedArticles?: PublishedArticle[];
   /** Whether to render static article share links. */
@@ -86,6 +92,46 @@ function formatReadingTime(seconds: number): string {
   return `${minutes} min read`;
 }
 
+function formatCreditUrl(url: string): string {
+  try {
+    return new URL(url).hostname.replace(/^www\./, "");
+  } catch {
+    return url;
+  }
+}
+
+function FeaturedImageCredit({
+  creditText,
+  creditUrl,
+}: {
+  creditText?: string;
+  creditUrl?: string;
+}) {
+  if (!creditText && !creditUrl) {
+    return null;
+  }
+
+  const label = creditText ?? formatCreditUrl(creditUrl ?? "");
+
+  return (
+    <span>
+      Credit:{" "}
+      {creditUrl ? (
+        <a
+          href={creditUrl}
+          target="_blank"
+          rel="noreferrer"
+          className="underline underline-offset-2 transition-colors hover:text-[var(--blog-text-accent)]"
+        >
+          {label}
+        </a>
+      ) : (
+        label
+      )}
+    </span>
+  );
+}
+
 export default function ArticlePage({
   article,
   className,
@@ -93,6 +139,8 @@ export default function ArticlePage({
   basePath = "/blog",
   theme,
   postArticleCta,
+  newsletter,
+  newsletterPreviewMode = false,
   relatedArticles = [],
   showShareLinks = true,
 }: ArticlePageProps) {
@@ -106,9 +154,15 @@ export default function ArticlePage({
   const articleUrl =
     article.meta.canonicalUrl ??
     buildBlogPath(normalizedBasePath, article.slug);
+  const newsletterSettings = newsletter ?? article.site.newsletter;
 
   // Use the featured image URL provided by Bloggy (hosted on Bloggy's domain)
   const imageUrl = article.featuredImage;
+  const hasFeaturedImageMeta = Boolean(
+    article.featuredImageCaption ??
+      article.featuredImageCreditText ??
+      article.featuredImageCreditUrl,
+  );
 
   return (
     <article
@@ -140,6 +194,45 @@ export default function ArticlePage({
         </header>
       )}
 
+      <style>{`
+        .article-content figure > p {
+          margin-top: 0 !important;
+          margin-bottom: 0 !important;
+        }
+
+        .article-content figure figcaption {
+          margin-top: 0.5rem !important;
+          text-align: center;
+          font-size: 0.875rem !important;
+          line-height: 1.35 !important;
+          color: hsl(var(--muted-foreground));
+        }
+
+        .article-content figure figcaption .blog-image-credit {
+          display: block;
+          margin-top: 0.25rem;
+          font-size: 0.75rem;
+          line-height: 1.25;
+          letter-spacing: 0.025em;
+          opacity: 0.8;
+        }
+
+        .article-content figure figcaption > span:not(.blog-image-credit) {
+          margin-left: 0.5rem;
+          padding-left: 0.5rem;
+          border-left: 1px solid var(--blog-accent-border);
+          font-size: 0.75rem;
+          letter-spacing: 0.025em;
+          opacity: 0.8;
+        }
+
+        .article-content figure figcaption a {
+          color: inherit;
+          text-decoration-line: underline;
+          text-underline-offset: 0.18em;
+        }
+      `}</style>
+
       {/* Article Header */}
       <header className="article-header mx-auto mb-6 max-w-4xl space-y-4 text-center sm:mb-8 sm:space-y-6 lg:mb-12 lg:space-y-8">
         {/* Title */}
@@ -237,18 +330,38 @@ export default function ArticlePage({
 
       {/* Featured Image */}
       {imageUrl && (
-        <div className="article-featured-image mx-auto my-8 aspect-[16/9] w-full max-w-4xl overflow-hidden rounded-3xl border border-[var(--blog-accent-border)] shadow-[0_24px_80px_rgb(168_85_247_/_0.14)] 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>
+        <figure className="article-featured-image mx-auto my-8 w-full max-w-4xl sm:my-12 lg:my-16">
+          <div className="aspect-[16/9] overflow-hidden rounded-3xl border border-[var(--blog-accent-border)] shadow-[0_24px_80px_rgb(168_85_247_/_0.14)]">
+            <Image
+              src={imageUrl}
+              alt={
+                article.featuredImageAlt ??
+                `Featured image for ${article.title}`
+              }
+              className="h-full w-full object-cover"
+              width={800}
+              height={450}
+              priority
+            />
+          </div>
+
+          {hasFeaturedImageMeta && (
+            <figcaption className="text-muted-foreground mt-3 space-y-1 px-2 text-center text-sm leading-relaxed sm:px-0">
+              {article.featuredImageCaption && (
+                <p>{article.featuredImageCaption}</p>
+              )}
+              {(article.featuredImageCreditText ??
+                article.featuredImageCreditUrl) && (
+                <p className="text-xs">
+                  <FeaturedImageCredit
+                    creditText={article.featuredImageCreditText}
+                    creditUrl={article.featuredImageCreditUrl}
+                  />
+                </p>
+              )}
+            </figcaption>
+          )}
+        </figure>
       )}
 
       {/* Article Content */}
@@ -265,7 +378,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)] 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)] [&_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"
           >
             <MDXRemote
               source={article.content}
@@ -327,11 +440,22 @@ export default function ArticlePage({
       )}
 
       {((postArticleCta ?? false) ||
+        (newsletterSettings?.enabled ?? false) ||
         showShareLinks ||
         relatedArticles.length > 0) && (
         <div className="mx-auto mt-12 max-w-4xl space-y-8">
           <Separator />
           {postArticleCta && <PostArticleCta cta={postArticleCta} />}
+          {newsletterSettings?.enabled && (
+            <NewsletterSignup
+              siteId={article.site.id}
+              settings={newsletterSettings}
+              sourceSurface="article"
+              sourceArticleSlug={article.slug}
+              sourceUrl={articleUrl}
+              previewMode={newsletterPreviewMode}
+            />
+          )}
           {showShareLinks && (
             <ArticleShareLinks title={article.title} url={articleUrl} />
           )}

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

@@ -0,0 +1,59 @@
+import type { ReactElement } from "react";
+import type {
+  PublishedArticle,
+  PublishedNewsletterSettings,
+  PublishedSite,
+} from "../../types/contracts";
+import type { BlogTheme } from "../../lib/article-ui";
+
+export interface BlogHomePageProps {
+  articles: PublishedArticle[];
+  siteName?: string;
+  siteTagline?: string;
+  className?: string;
+  site?: PublishedSite;
+  includeStructuredData?: boolean;
+  basePath?: string;
+  pagination?: {
+    currentPage: number;
+    totalPages: number;
+    baseUrl?: string;
+  };
+  theme?: BlogTheme;
+  newsletter?: PublishedNewsletterSettings;
+  newsletterPreviewMode?: boolean;
+}
+
+export default function BlogHomePage(props: BlogHomePageProps): ReactElement;
+
+export function generateBlogHomeMetadata(
+  siteName?: string,
+  siteTagline?: string,
+  siteUrl?: string,
+  pagination?: {
+    currentPage: number;
+    totalPages: number;
+  },
+  basePath?: string,
+): {
+  title: string;
+  description: string;
+  openGraph: {
+    title: string;
+    description: string;
+    type: string;
+    url?: string;
+  };
+  twitter: {
+    card: string;
+    title: string;
+    description: string;
+  };
+  alternates: {
+    canonical?: string;
+  };
+  other: {
+    prev?: string;
+    next?: string;
+  };
+};

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

@@ -0,0 +1,83 @@
+import React from "react";
+import { renderToPipeableStream } from "react-dom/server";
+import { PassThrough } from "stream";
+import { describe, expect, it } from "vitest";
+
+import BlogHomePage from "./page";
+import type { PublishedArticle } from "../../types/contracts";
+
+const article: PublishedArticle = {
+  id: "article-1",
+  slug: "useful-routines",
+  title: "Useful routines",
+  excerpt: "A practical guide to keeping routines useful.",
+  content: "Routines work best when they are easy to maintain.",
+  readingSeconds: 360,
+  wordCount: 900,
+  publishedAt: "2026-05-06T12:00:00.000Z",
+  updatedAt: "2026-05-07T12:00:00.000Z",
+  author: null,
+  site: {
+    id: "site-1",
+    name: "Example Blog",
+    tagline: "Useful writing",
+    description: "Articles about useful systems.",
+    domain: "example.com",
+    toneAdjectives: [],
+    locale: "en",
+  },
+  meta: {
+    canonicalUrl: "https://example.com/blog/useful-routines",
+    keywords: [],
+  },
+  version: 1,
+};
+
+describe("BlogHomePage", () => {
+  it("renders the newsletter form when configured", async () => {
+    const html = await renderToHtml(
+      React.createElement(BlogHomePage, {
+        articles: [article],
+        siteName: "Example Blog",
+        newsletter: {
+          enabled: true,
+          title: "Get product updates",
+          description: "Follow new articles and product notes.",
+          buttonLabel: "Get updates",
+          captureBaseUrl: "https://bloggy.example.com",
+          publicSubscribeToken: "public_subscribe_token",
+        },
+      }),
+    );
+
+    expect(html).toContain("Get product updates");
+    expect(html).toContain("Follow new articles and product notes.");
+    expect(html).toContain('type="email"');
+    expect(html).toContain('name="name"');
+    expect(html.indexOf("Get product updates")).toBeGreaterThan(
+      html.indexOf("Useful routines"),
+    );
+  });
+});
+
+function renderToHtml(element: React.ReactElement): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let html = "";
+    const stream = new PassThrough();
+    stream.setEncoding("utf8");
+    stream.on("data", (chunk: string) => {
+      html += chunk;
+    });
+    stream.on("end", () => resolve(html));
+    stream.on("error", reject);
+
+    const { pipe } = renderToPipeableStream(element, {
+      onAllReady() {
+        pipe(stream);
+      },
+      onError(error) {
+        reject(error instanceof Error ? error : new Error(String(error)));
+      },
+    });
+  });
+}

package/dist/app/blog/page.tsx

@@ -4,6 +4,7 @@ import Image from "next/image";
 import {
   type PublishedArticle,
   type PublishedAuthor,
+  type PublishedNewsletterSettings,
   type PublishedSite,
 } from "../../types/contracts";
 import { cn } from "../../lib/utils";
@@ -19,6 +20,7 @@ import {
 } from "../../lib/urls";
 import { formatDistanceToNow } from "date-fns";
 import { type BlogTheme, getBlogThemeStyle } from "../../lib/article-ui";
+import { NewsletterSignup } from "../../components/NewsletterSignup";
 
 interface BlogHomePageProps {
   articles: PublishedArticle[];
@@ -39,6 +41,10 @@ interface BlogHomePageProps {
   };
   /** Optional theme values for host-site brand integration. */
   theme?: BlogTheme;
+  /** Optional Bloggy-owned newsletter capture configuration. */
+  newsletter?: PublishedNewsletterSettings;
+  /** Render interactive preview success without persisting subscribers. */
+  newsletterPreviewMode?: boolean;
 }
 
 /**
@@ -58,8 +64,12 @@ export default function BlogHomePage({
   basePath = "/blog",
   pagination,
   theme,
+  newsletter,
+  newsletterPreviewMode = false,
 }: BlogHomePageProps) {
   const normalizedBasePath = normalizeBlogBasePath(basePath) || "/";
+  const newsletterSettings = newsletter ?? site?.newsletter;
+  const newsletterSiteId = site?.id ?? articles[0]?.site.id;
 
   return (
     <div
@@ -119,6 +129,16 @@ export default function BlogHomePage({
         )}
       </main>
 
+      {newsletterSettings?.enabled && newsletterSiteId && (
+        <NewsletterSignup
+          siteId={newsletterSiteId}
+          settings={newsletterSettings}
+          sourceSurface="blog_home"
+          previewMode={newsletterPreviewMode}
+          className="mt-10 sm:mt-12"
+        />
+      )}
+
       {/* JSON-LD Structured Data */}
       {includeStructuredData &&
         site &&