@carlonicora/nextjs-jsonapi 5.3.0 → 5.5.0

package/src/features/blog/components/public/BlogPostCard.tsx

@@ -0,0 +1,125 @@
+"use client";
+
+import Image from "next/image";
+import { MicroLabel, SectionHeader } from "../../../../components/typography";
+import { Link } from "../../../../shadcnui";
+import { cn } from "../../../../utils/cn";
+import { isRemoteImageSrc } from "../../../../utils/isRemoteImageSrc";
+import type { PublicBlogCategory, PublicBlogPost } from "../../types/blog-public.types";
+import { blogPostHref, resolvePostCategory } from "./blogPublicHelpers";
+import { BlogPostMeta } from "./BlogPostMeta";
+
+/**
+ * Cover image in a fixed-ratio frame. With no image it renders a
+ * token-coloured placeholder of the same footprint, so rows stay aligned.
+ */
+export function BlogPostCover(props: {
+  src?: string;
+  alt?: string;
+  sizes: string;
+  priority?: boolean;
+  className?: string;
+}) {
+  const { src, alt, sizes, priority, className } = props;
+  return (
+    <div className={cn("border-border bg-primary/10 relative overflow-hidden rounded-lg border", className)}>
+      {src ? (
+        <Image
+          src={src}
+          alt={alt ?? ""}
+          fill
+          sizes={sizes}
+          priority={priority}
+          className="object-cover"
+          unoptimized={isRemoteImageSrc(src)}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+type BlogPostCardVariant = "hero" | "large" | "card" | "row";
+
+/**
+ * One post in a public list.
+ * - hero: image and text side by side, author and date (featured layout)
+ * - large: image above text, author and date (rail layout)
+ * - card: small grid card (featured grid, rail columns, related posts)
+ * - row: image at the start, text at the end (column layout)
+ * The title link is stretched over the whole card, so the card is one target
+ * whose accessible name is the title alone.
+ */
+export function BlogPostCard(props: {
+  post: PublicBlogPost;
+  categories: PublicBlogCategory[];
+  basePath: string;
+  variant?: BlogPostCardVariant;
+  priority?: boolean;
+  headingLevel?: "h2" | "h3";
+}) {
+  const { post, categories, basePath, variant = "card", priority, headingLevel = "h2" } = props;
+  const category = resolvePostCategory(post, categories);
+  const isProminent = variant === "hero" || variant === "large";
+
+  const eyebrow = category?.name;
+
+  const text = (
+    <div className="flex min-w-0 flex-col">
+      {eyebrow ? <MicroLabel as="span">{eyebrow}</MicroLabel> : null}
+      <SectionHeader level={headingLevel === "h3" ? 3 : 2} className="mt-1.5">
+        <Link href={blogPostHref(basePath, post.slug)} className="after:absolute after:inset-0">
+          {post.title}
+        </Link>
+      </SectionHeader>
+      {post.summary ? <p className="text-muted-foreground mt-2 text-sm leading-relaxed">{post.summary}</p> : null}
+      <BlogPostMeta post={post} showAuthor={isProminent} className="mt-3" />
+    </div>
+  );
+
+  if (variant === "hero") {
+    return (
+      <article className="group relative grid items-center gap-6 md:grid-cols-[1.4fr_1fr] md:gap-10">
+        <BlogPostCover
+          src={post.coverImage}
+          alt={post.coverImageAlt}
+          sizes="(min-width: 1024px) 560px, (min-width: 768px) 58vw, 100vw"
+          priority={priority}
+          className="aspect-[16/10]"
+        />
+        {text}
+      </article>
+    );
+  }
+
+  if (variant === "row") {
+    return (
+      <article className="group relative grid items-center gap-4 sm:grid-cols-[10rem_1fr] sm:gap-6">
+        <BlogPostCover
+          src={post.coverImage}
+          alt={post.coverImageAlt}
+          sizes="(min-width: 640px) 160px, 100vw"
+          priority={priority}
+          className="aspect-[16/10]"
+        />
+        {text}
+      </article>
+    );
+  }
+
+  return (
+    <article className="group relative flex flex-col gap-4">
+      <BlogPostCover
+        src={post.coverImage}
+        alt={post.coverImageAlt}
+        sizes={
+          variant === "large"
+            ? "(min-width: 1024px) 760px, 100vw"
+            : "(min-width: 1024px) 320px, (min-width: 640px) 50vw, 100vw"
+        }
+        priority={priority}
+        className={variant === "large" ? "aspect-[16/8]" : "aspect-[16/10]"}
+      />
+      {text}
+    </article>
+  );
+}

package/src/features/blog/components/public/BlogPostMeta.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { useFormatter, useTranslations } from "next-intl";
+import { cn } from "../../../../utils/cn";
+import type { PublicBlogPost } from "../../types/blog-public.types";
+
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * "author · date · updated · reading time". Each part except reading time is
+ * opt-in. The public blog shows no dates, so its callers pass only showAuthor.
+ */
+export function BlogPostMeta(props: {
+  post: PublicBlogPost;
+  showAuthor?: boolean;
+  showDate?: boolean;
+  showUpdated?: boolean;
+  className?: string;
+}) {
+  const { post, showAuthor, showDate, showUpdated, className } = props;
+  const t = useTranslations();
+  const format = useFormatter();
+
+  const parts: string[] = [];
+  if (showAuthor && post.authorName) parts.push(t("blog.public.by", { author: post.authorName }));
+  if (showDate && post.publishedAt) {
+    parts.push(format.dateTime(new Date(post.publishedAt), { dateStyle: "medium" }));
+  }
+  if (
+    showUpdated &&
+    post.publishedAt &&
+    post.updatedAt &&
+    new Date(post.updatedAt).getTime() - new Date(post.publishedAt).getTime() > ONE_DAY_MS
+  ) {
+    parts.push(t("blog.public.updated", { date: format.dateTime(new Date(post.updatedAt), { dateStyle: "medium" }) }));
+  }
+  parts.push(t("blog.public.readingTime", { minutes: post.readingMinutes }));
+
+  return (
+    <p className={cn("text-muted-foreground text-xs", className)}>
+      {parts.map((part, index) => (
+        <span key={index}>
+          {index > 0 ? " · " : null}
+          {part}
+        </span>
+      ))}
+    </p>
+  );
+}

package/src/features/blog/components/public/BlogPostView.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import { ArrowLeftIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import type { ReactNode } from "react";
+import { BlockNoteEditorContainer } from "../../../../components/editors/BlockNoteEditorContainer";
+import { ContentTitle } from "../../../../components/navigations/ContentTitle";
+import { SectionHeader } from "../../../../components/typography";
+import { Link } from "../../../../shadcnui";
+import type { PublicBlogCategory, PublicBlogPost } from "../../types/blog-public.types";
+import { resolvePostCategory } from "./blogPublicHelpers";
+import { BlogPostCard, BlogPostCover } from "./BlogPostCard";
+import { BlogPostMeta } from "./BlogPostMeta";
+
+/**
+ * Public post page: back link, category, title, summary, meta, cover, body,
+ * then up to three posts from the same category.
+ *
+ * `body` replaces the client-only editor with server-rendered content (the app
+ * passes BlockNoteServerContent from `@carlonicora/nextjs-jsonapi/blocknote/server`),
+ * so the post text is in the HTML crawlers read.
+ */
+export function BlogPostView(props: {
+  post: PublicBlogPost;
+  categories: PublicBlogCategory[];
+  related: PublicBlogPost[];
+  basePath: string;
+  body?: ReactNode;
+}) {
+  const { post, categories, related, basePath, body } = props;
+  const t = useTranslations();
+  const category = resolvePostCategory(post, categories);
+  const more = related.slice(0, 3);
+
+  return (
+    <article className="px-4 pt-12 pb-20 md:pt-16">
+      <div className="mx-auto max-w-3xl">
+        <Link href={basePath} className="inline-flex items-center gap-1.5">
+          <ArrowLeftIcon className="size-4 rtl:rotate-180" />
+          {t("blog.public.back")}
+        </Link>
+        <header className="mt-8">
+          <ContentTitle type={category?.name} element={post.title} headingLevel={1} className="mb-0" />
+          {post.summary ? <p className="text-muted-foreground mt-3 text-sm leading-relaxed">{post.summary}</p> : null}
+          <BlogPostMeta post={post} showAuthor className="mt-4" />
+        </header>
+        {post.coverImage ? (
+          <BlogPostCover
+            src={post.coverImage}
+            alt={post.coverImageAlt}
+            sizes="(min-width: 768px) 768px, 100vw"
+            priority
+            className="mt-8 aspect-[16/9]"
+          />
+        ) : null}
+        <div className="mt-8">
+          {body ?? <BlockNoteEditorContainer id={post.id} type="blog-post" initialContent={post.body} />}
+        </div>
+      </div>
+      {more.length > 0 ? (
+        <section className="mx-auto mt-16 max-w-5xl">
+          <div className="border-border border-t pt-10">
+            <SectionHeader level={2}>{t("blog.public.moreIn", { category: category?.name ?? "" })}</SectionHeader>
+            <div className="mt-6 grid gap-x-6 gap-y-10 sm:grid-cols-2 lg:grid-cols-3">
+              {more.map((relatedPost) => (
+                <BlogPostCard
+                  key={relatedPost.id}
+                  post={relatedPost}
+                  categories={categories}
+                  basePath={basePath}
+                  headingLevel="h3"
+                />
+              ))}
+            </div>
+          </div>
+        </section>
+      ) : null}
+    </article>
+  );
+}

package/src/features/blog/components/public/BlogSearchBox.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { SearchIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { FormEvent, useEffect, useState } from "react";
+import { useI18nRouter } from "../../../../i18n";
+import { InputGroup, InputGroupAddon, InputGroupInput } from "../../../../shadcnui";
+import { blogListHref } from "./blogPublicHelpers";
+
+/**
+ * Search form for the public list. The current query and category come in as
+ * props (the page already parsed the search params), so this component never
+ * reads `useSearchParams` and needs no Suspense boundary of its own.
+ * Submitting keeps the category and resets to page one.
+ */
+export function BlogSearchBox(props: {
+  basePath: string;
+  query?: string;
+  activeCategorySlug?: string;
+  className?: string;
+}) {
+  const { basePath, query, activeCategorySlug, className } = props;
+  const t = useTranslations();
+  const router = useI18nRouter();
+  const [value, setValue] = useState(query ?? "");
+
+  useEffect(() => setValue(query ?? ""), [query]);
+
+  const onSubmit = (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const q = value.trim();
+    router.push(blogListHref(basePath, { category: activeCategorySlug, q: q || undefined }));
+  };
+
+  return (
+    <form role="search" onSubmit={onSubmit} className={className}>
+      <InputGroup>
+        <InputGroupAddon>
+          <SearchIcon />
+        </InputGroupAddon>
+        <InputGroupInput
+          type="search"
+          name="q"
+          value={value}
+          onChange={(event) => setValue(event.target.value)}
+          placeholder={t("blog.public.searchPlaceholder")}
+          aria-label={t("blog.public.search")}
+        />
+      </InputGroup>
+    </form>
+  );
+}

package/src/features/blog/components/public/__tests__/BlogList.spec.tsx

@@ -0,0 +1,175 @@
+import { render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { configureI18n } from "../../../../../i18n";
+import type { PublicBlogCategory, PublicBlogPost } from "../../../types/blog-public.types";
+import { BlogList } from "../BlogList";
+
+// t interpolates its values after the key so assertions can see them.
+vi.mock("next-intl", () => ({
+  useTranslations: () => (key: string, values?: Record<string, unknown>) =>
+    values ? `${key} ${Object.values(values).join(" ")}` : key,
+  useFormatter: () => ({ dateTime: (date: Date) => date.toISOString().slice(0, 10) }),
+}));
+vi.mock("next/image", () => ({
+  default: ({ src, alt }: { src: string; alt: string }) => <img src={src} alt={alt} />,
+}));
+
+const cats: PublicBlogCategory[] = [
+  { id: "c1", name: "Game prep", slug: "game-prep" },
+  { id: "c2", name: "Product", slug: "product" },
+];
+
+const post = (overrides: Partial<PublicBlogPost>): PublicBlogPost => ({
+  id: "p",
+  language: "en",
+  title: "Title",
+  slug: "title",
+  summary: "Summary",
+  readingMinutes: 4,
+  publishedAt: "2026-10-12T09:00:00.000Z",
+  updatedAt: "2026-10-12T09:00:00.000Z",
+  authorName: "Carlo Nicora",
+  categoryIds: ["c1"],
+  ...overrides,
+});
+
+const p1 = post({
+  id: "p1",
+  title: "Prep situations, not plots",
+  slug: "prep-situations",
+  summary: "Why a scene that can go three ways beats a scene that must go one way.",
+  coverImage: "https://cdn.test/p1.webp",
+});
+const p2 = post({
+  id: "p2",
+  title: "Voice attribution, explained",
+  slug: "voice",
+  summary: "How it knows who spoke.",
+  categoryIds: ["c2"],
+});
+const p3 = post({
+  id: "p3",
+  title: "Clues that point, not explain",
+  slug: "clues",
+  summary: "Make every clue a pointer.",
+});
+
+beforeEach(() => {
+  configureI18n({
+    useRouter: () => ({
+      push: () => {},
+      replace: () => {},
+      back: () => {},
+      forward: () => {},
+      refresh: () => {},
+      prefetch: () => {},
+    }),
+    useTranslations: () => (key: string) => key,
+    usePathname: () => "/blog",
+    getLocale: async () => "en",
+    Link: ({ href, children, prefetch: _prefetch, scroll: _scroll, ...props }: any) => (
+      <a href={href} {...props}>
+        {children}
+      </a>
+    ),
+  });
+});
+
+describe("BlogList", () => {
+  it.each(["featured", "column", "rail"] as const)("%s layout renders every post title and a summary", (layout) => {
+    render(
+      <BlogList
+        layout={layout}
+        list={{ posts: [p1, p2, p3], hasMore: false }}
+        categories={cats}
+        page={1}
+        basePath="/blog"
+      />,
+    );
+
+    expect(screen.getAllByRole("link", { name: /Prep situations/ })[0]).toHaveAttribute(
+      "href",
+      "/blog/prep-situations",
+    );
+    expect(screen.getAllByRole("link", { name: /Voice attribution/ })[0]).toHaveAttribute("href", "/blog/voice");
+    expect(screen.getAllByRole("link", { name: /Clues that point/ })[0]).toHaveAttribute("href", "/blog/clues");
+    expect(screen.getByText(p3.summary!)).toBeInTheDocument();
+    expect(screen.getAllByText(/blog\.public\.readingTime 4/).length).toBeGreaterThanOrEqual(3);
+    // One real h1 per page (public SEO page), carried by ContentTitle; the eyebrow is not part of it.
+    expect(screen.getAllByRole("heading", { level: 1 })).toHaveLength(1);
+    expect(screen.getByRole("heading", { level: 1, name: "blog.public.title" })).toBeInTheDocument();
+    expect(screen.getByText("blog.public.eyebrow")).toBeInTheDocument();
+    // The public blog shows no dates in any layout.
+    expect(screen.queryByText(/2026-10-12/)).not.toBeInTheDocument();
+  });
+
+  it("active category chip is marked and links back to all", () => {
+    render(
+      <BlogList
+        layout="featured"
+        list={{ posts: [p1], hasMore: false }}
+        categories={cats}
+        activeCategorySlug="game-prep"
+        page={1}
+        basePath="/blog"
+      />,
+    );
+
+    const active = screen.getByRole("link", { name: "Game prep" });
+    expect(active).toHaveAttribute("aria-current", "page");
+    expect(active).toHaveAttribute("href", "/blog?category=game-prep");
+    expect(screen.getByRole("link", { name: "Product" })).not.toHaveAttribute("aria-current");
+    const all = screen.getByRole("link", { name: "blog.public.all" });
+    expect(all).toHaveAttribute("href", "/blog");
+    expect(all).not.toHaveAttribute("aria-current");
+  });
+
+  it("load more links to the next page keeping filters", () => {
+    render(
+      <BlogList
+        layout="column"
+        list={{ posts: [p1], hasMore: true }}
+        categories={cats}
+        activeCategorySlug="game-prep"
+        query="x"
+        page={1}
+        basePath="/blog"
+      />,
+    );
+
+    expect(screen.getByRole("link", { name: "blog.public.loadMore" })).toHaveAttribute(
+      "href",
+      "/blog?category=game-prep&q=x&page=2",
+    );
+  });
+
+  it("hides load more when there is nothing more", () => {
+    render(
+      <BlogList layout="rail" list={{ posts: [p1], hasMore: false }} categories={cats} page={1} basePath="/blog" />,
+    );
+    expect(screen.queryByRole("link", { name: "blog.public.loadMore" })).not.toBeInTheDocument();
+  });
+
+  it("empty list with a query shows noResults", () => {
+    render(
+      <BlogList
+        layout="featured"
+        list={{ posts: [], hasMore: false }}
+        categories={cats}
+        query="zzz"
+        page={1}
+        basePath="/blog"
+      />,
+    );
+    expect(screen.getByText("blog.public.noResults")).toBeInTheDocument();
+    expect(screen.queryByText("blog.public.empty")).not.toBeInTheDocument();
+  });
+
+  it("empty list without a query shows empty", () => {
+    render(
+      <BlogList layout="column" list={{ posts: [], hasMore: false }} categories={cats} page={1} basePath="/blog" />,
+    );
+    expect(screen.getByText("blog.public.empty")).toBeInTheDocument();
+  });
+});

package/src/features/blog/components/public/__tests__/BlogPostView.spec.tsx

@@ -0,0 +1,134 @@
+import { render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { configureI18n } from "../../../../../i18n";
+import type { PublicBlogCategory, PublicBlogPost } from "../../../types/blog-public.types";
+import { BlogPostView } from "../BlogPostView";
+
+// t interpolates its values after the key so assertions can see them.
+vi.mock("next-intl", () => ({
+  useTranslations: () => (key: string, values?: Record<string, unknown>) =>
+    values ? `${key} ${Object.values(values).join(" ")}` : key,
+  useFormatter: () => ({ dateTime: (date: Date) => date.toISOString().slice(0, 10) }),
+}));
+vi.mock("next/image", () => ({
+  default: ({ src, alt }: { src: string; alt: string }) => <img src={src} alt={alt} />,
+}));
+// The real editor is a next/dynamic ssr:false import; assert on the props it receives.
+vi.mock("../../../../../components/editors/BlockNoteEditorContainer", () => ({
+  BlockNoteEditorContainer: ({ id, type, initialContent }: { id: string; type: string; initialContent: unknown }) => (
+    <div data-testid="post-body" data-id={id} data-type={type}>
+      {JSON.stringify(initialContent)}
+    </div>
+  ),
+}));
+
+const cats: PublicBlogCategory[] = [{ id: "c1", name: "Game prep", slug: "game-prep" }];
+
+const post = (overrides: Partial<PublicBlogPost>): PublicBlogPost => ({
+  id: "p",
+  language: "en",
+  title: "Title",
+  slug: "title",
+  readingMinutes: 4,
+  publishedAt: "2026-10-12T09:00:00.000Z",
+  updatedAt: "2026-10-12T09:00:00.000Z",
+  categoryIds: ["c1"],
+  ...overrides,
+});
+
+const main = post({
+  id: "p1",
+  title: "Prep situations, not plots",
+  slug: "prep-situations",
+  summary: "Why a scene that can go three ways beats a scene that must go one way.",
+  body: [{ type: "paragraph", content: [{ type: "text", text: "Every GM has lived that moment" }] }],
+  coverImage: "https://cdn.test/p1.webp",
+  coverImageAlt: "A table with dice",
+  readingMinutes: 6,
+  authorName: "Carlo Nicora",
+  updatedAt: "2026-10-15T09:00:00.000Z",
+});
+const r1 = post({
+  id: "r1",
+  title: "Clues that point, not explain",
+  slug: "clues",
+  summary: "Make every clue a pointer.",
+});
+const r2 = post({ id: "r2", title: "Three-way scenes", slug: "three-way" });
+
+beforeEach(() => {
+  configureI18n({
+    useRouter: () => ({
+      push: () => {},
+      replace: () => {},
+      back: () => {},
+      forward: () => {},
+      refresh: () => {},
+      prefetch: () => {},
+    }),
+    useTranslations: () => (key: string) => key,
+    usePathname: () => "/blog/prep-situations",
+    getLocale: async () => "en",
+    Link: ({ href, children, prefetch: _prefetch, scroll: _scroll, ...props }: any) => (
+      <a href={href} {...props}>
+        {children}
+      </a>
+    ),
+  });
+});
+
+describe("BlogPostView", () => {
+  it("shows category, title, author, reading time and more-in links", () => {
+    render(<BlogPostView post={main} categories={cats} related={[r1, r2]} basePath="/blog" />);
+
+    expect(screen.getByRole("link", { name: /blog\.public\.back/ })).toHaveAttribute("href", "/blog");
+    expect(screen.getAllByText("Game prep")[0]).toBeInTheDocument();
+    expect(screen.getAllByRole("heading", { level: 1 })).toHaveLength(1);
+    expect(screen.getByRole("heading", { level: 1, name: "Prep situations, not plots" })).toBeInTheDocument();
+    expect(screen.getByText(main.summary!)).toBeInTheDocument();
+    expect(screen.getByText("blog.public.by Carlo Nicora")).toBeInTheDocument();
+    expect(screen.getByText(/blog\.public\.readingTime 6/)).toBeInTheDocument();
+    expect(screen.getByAltText("A table with dice")).toHaveAttribute("src", "https://cdn.test/p1.webp");
+    const body = screen.getByTestId("post-body");
+    expect(body).toHaveTextContent("Every GM has lived that moment");
+    expect(body).toHaveAttribute("data-id", "p1");
+    expect(body).toHaveAttribute("data-type", "blog-post");
+
+    expect(screen.getByRole("heading", { level: 2, name: "blog.public.moreIn Game prep" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Clues that point, not explain" })).toHaveAttribute("href", "/blog/clues");
+    expect(screen.getByRole("link", { name: "Three-way scenes" })).toHaveAttribute("href", "/blog/three-way");
+  });
+
+  it("shows neither the publish date nor the updated date", () => {
+    render(<BlogPostView post={main} categories={cats} related={[]} basePath="/blog" />);
+    expect(screen.queryByText(/2026-10-12/)).not.toBeInTheDocument();
+    expect(screen.queryByText(/2026-10-15/)).not.toBeInTheDocument();
+    expect(screen.queryByText(/blog\.public\.updated/)).not.toBeInTheDocument();
+  });
+
+  it("omits the more-in section when there are no related posts", () => {
+    render(<BlogPostView post={main} categories={cats} related={[]} basePath="/blog" />);
+    expect(screen.queryByText(/blog\.public\.moreIn/)).not.toBeInTheDocument();
+  });
+
+  it("renders the body prop in place of the editor when given", () => {
+    render(
+      <BlogPostView
+        post={main}
+        categories={cats}
+        related={[]}
+        basePath="/blog"
+        body={<div data-testid="server-body">Server-rendered text</div>}
+      />,
+    );
+    expect(screen.getByTestId("server-body")).toHaveTextContent("Server-rendered text");
+    expect(screen.queryByTestId("post-body")).not.toBeInTheDocument();
+  });
+
+  it("caps related posts at three", () => {
+    const many = [1, 2, 3, 4].map((n) => post({ id: `r${n}`, title: `Related ${n}`, slug: `related-${n}` }));
+    render(<BlogPostView post={main} categories={cats} related={many} basePath="/blog" />);
+    expect(screen.getAllByRole("heading", { level: 3 })).toHaveLength(3);
+  });
+});

package/src/features/blog/components/public/blogPublicHelpers.ts

@@ -0,0 +1,30 @@
+import type { PublicBlogCategory, PublicBlogPost } from "../../types/blog-public.types";
+
+/**
+ * Locale-free href to the public list, keeping the active filters.
+ * Parameter order is fixed (category, q, page) so links are stable.
+ */
+export function blogListHref(basePath: string, params: { category?: string; q?: string; page?: number }): string {
+  const search = new URLSearchParams();
+  if (params.category) search.set("category", params.category);
+  if (params.q) search.set("q", params.q);
+  if (params.page && params.page > 1) search.set("page", String(params.page));
+  const query = search.toString();
+  return query ? `${basePath}?${query}` : basePath;
+}
+
+export function blogPostHref(basePath: string, slug: string): string {
+  return `${basePath}/${encodeURIComponent(slug)}`;
+}
+
+/** The first of the post's categories that the visitor's category list knows. */
+export function resolvePostCategory(
+  post: PublicBlogPost,
+  categories: PublicBlogCategory[],
+): PublicBlogCategory | undefined {
+  for (const id of post.categoryIds) {
+    const category = categories.find((c) => c.id === id);
+    if (category) return category;
+  }
+  return undefined;
+}

package/src/features/blog/components/public/index.ts

@@ -0,0 +1,3 @@
+export { BlogList } from "./BlogList";
+export type { BlogListProps } from "./BlogList";
+export { BlogPostView } from "./BlogPostView";