@decocms/apps-blog 7.84.0 → 7.85.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-blog",
-  "version": "7.84.0",
+  "version": "7.85.0",
   "type": "module",
   "description": "Deco app: blog content and CMS integration",
   "repository": {
@@ -38,9 +38,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.84.0",
-    "@decocms/apps-commerce": "7.84.0",
-    "@decocms/apps-website": "7.84.0"
+    "@decocms/blocks": "7.85.0",
+    "@decocms/apps-commerce": "7.85.0",
+    "@decocms/apps-website": "7.85.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/README.md

@@ -56,6 +56,19 @@ the Deno app *threw* `"Deco Records not installed!"` on a view sort without the
 backend; degrading was chosen instead, since view sorting is an enhancement and
 a missing backend shouldn't blank a listing.
 
+## Draft preview (`?draft=true`)
+
+A post that isn't live (see `isLivePost`) only renders on its own page when
+the URL carries `?draft=true`: `BlogPostPage` and `BlogPostItem` answer `null`
+for it otherwise, as for a slug that doesn't exist, and mark it `noIndexing`
+in a preview. Only the literal `true` turns it on. Listings are unaffected:
+they never show a non-live post. `isDraftPreview(url)` is exported for a site
+that renders its own post page.
+
+Anyone who knows the parameter can open an unpublished post: it is a
+convenience for previews, not access control. Same behaviour as
+`deco-cx/apps` (deco-cx/apps#1698).
+
 ## Divergences from upstream worth knowing
 
 - **Title and view sorts are inverted** — `title_asc` yields Z-A, and

package/src/__tests__/publicationStatus.test.ts

@@ -4,8 +4,8 @@
  * Scope: the read-time publication gate — `isPublishedStatus` / `isLivePost`,
  * `filterRoutablePosts`, and the fact that the gate runs *before* pagination so
  * `count` yields `count` renderable posts. Also covers the counterpart on the
- * detail loaders: a non-live post still renders (it is the CMS preview) but is
- * marked `noIndexing`.
+ * detail loaders: a non-live post only renders in a `?draft=true` preview, and
+ * then is marked `noIndexing`.
  *
  * Deliberately not covered here: the strict-parsing edge cases of
  * `scheduledTime` (see `date.test.ts`) and anything requiring a records
@@ -145,29 +145,65 @@ describe("listing pagination applies the gate before slicing", () => {
   });
 });
 
-describe("detail loaders serve non-live posts as previews, unindexed", () => {
+describe("detail loaders serve non-live posts only in a ?draft=true preview", () => {
   beforeEach(() => {
     vi.clearAllMocks();
   });
 
-  it("BlogPostPage marks a draft noIndexing but still renders it", () => {
+  const preview = new Request("http://localhost/blog/d?draft=true");
+
+  it("BlogPostPage renders a draft in preview, marked noIndexing", () => {
     mockGetRecords.mockReturnValue([post({ slug: "d", status: "draft" })]);
-    const result = BlogPostPageLoader({ slug: "d" });
+    const result = BlogPostPageLoader({ slug: "d" }, preview);
     expect(result?.post.slug).toBe("d");
     expect(result?.seo?.noIndexing).toBe(true);
   });
 
+  it("BlogPostPage answers null for a draft without the flag", () => {
+    mockGetRecords.mockReturnValue([post({ slug: "d", status: "draft" })]);
+    expect(BlogPostPageLoader({ slug: "d" })).toBeNull();
+    for (const query of ["", "?draft=1", "?draft=false", "?draft", "?__draft=true"]) {
+      const req = new Request(`http://localhost/blog/d${query}`);
+      expect(BlogPostPageLoader({ slug: "d" }, req)).toBeNull();
+    }
+  });
+
+  it("BlogPostPage gates a scheduled post until its instant, unless previewed", () => {
+    mockGetRecords.mockReturnValue([
+      post({ slug: "s", status: "scheduled", scheduledDatetime: iso(HOUR) }),
+      post({ slug: "p", status: "scheduled", scheduledDatetime: iso(-HOUR) }),
+    ]);
+    expect(BlogPostPageLoader({ slug: "s" })).toBeNull();
+    expect(BlogPostPageLoader({ slug: "s" }, preview)?.seo?.noIndexing).toBe(true);
+    expect(BlogPostPageLoader({ slug: "p" })?.seo?.noIndexing).toBe(false);
+  });
+
+  it("BlogPostPage reads the flag from __pageUrl when there is no request", () => {
+    mockGetRecords.mockReturnValue([post({ slug: "d", status: "draft" })]);
+    const result = BlogPostPageLoader({
+      slug: "d",
+      __pageUrl: "http://localhost/blog/d?draft=true",
+    });
+    expect(result?.post.slug).toBe("d");
+  });
+
   it("BlogPostPage leaves a live post indexable", () => {
     mockGetRecords.mockReturnValue([post({ slug: "p", status: "published" })]);
     expect(BlogPostPageLoader({ slug: "p" })?.seo?.noIndexing).toBe(false);
   });
 
-  it("BlogPostItem stamps noIndexing without discarding the post's own seo", () => {
+  it("BlogPostItem stamps noIndexing in preview without discarding the post's own seo", () => {
     mockGetRecords.mockReturnValue([post({ slug: "d", status: "draft", seo: { title: "Kept" } })]);
-    const result = BlogPostItem({ slug: "d" });
+    const result = BlogPostItem({ slug: "d" }, preview);
     expect(result?.seo).toEqual({ title: "Kept", noIndexing: true });
   });
 
+  it("BlogPostItem answers null for a draft without the flag", () => {
+    mockGetRecords.mockReturnValue([post({ slug: "d", status: "draft" })]);
+    expect(BlogPostItem({ slug: "d" })).toBeNull();
+    expect(BlogPostItem({ slug: "d" }, new Request("http://localhost/blog/d"))).toBeNull();
+  });
+
   it("BlogPostItem returns a live post untouched", () => {
     const live = post({ slug: "p" });
     mockGetRecords.mockReturnValue([live]);

package/src/index.ts

@@ -53,6 +53,7 @@ export type {
 export { isLivePost, isPublishedStatus } from "./types";
 export { blocksToSections } from "./utils/blocksToSections";
 export { dateToTime, scheduledTime } from "./utils/date";
+export { DRAFT_PREVIEW_PARAM, isDraftPreview } from "./utils/draftPreview";
 export { hardSanitize } from "./utils/hardSanitize";
 export { toBlogPosting, toBreadcrumbList, toOrganization, withCanonicalBase } from "./utils/jsonLD";
 export { sanitizeHref, sanitizeHtml } from "./utils/sanitizeHtml";

package/src/loaders/BlogPostItem.ts

@@ -1,6 +1,7 @@
 import { getRecordsByPath } from "../core/records";
 import type { BlogPost } from "../types";
 import { isLivePost } from "../types";
+import { isDraftPreview } from "../utils/draftPreview";
 
 export interface Props {
   slug: string;
@@ -11,7 +12,10 @@ export interface Props {
  * @description Fetches a single blog post by slug. Returns the BlogPost
  * directly (not wrapped in BlogPostPage).
  */
-export default function BlogPostItem(props: Props & { __pageUrl?: string }): BlogPost | null {
+export default function BlogPostItem(
+  props: Props & { __pageUrl?: string },
+  req?: Request,
+): BlogPost | null {
   const { slug } = props;
   if (!slug) return null;
 
@@ -19,11 +23,13 @@ export default function BlogPostItem(props: Props & { __pageUrl?: string }): Blo
   const post = posts.find((p) => p?.slug === slug);
 
   if (!post) return null;
+  if (isLivePost(post)) return post;
 
   // A post that isn't live yet — unpublished, or scheduled for an instant still
-  // ahead — is still served, because that page *is* the CMS preview. It just
-  // must never be indexed. Everything else the post declared under `seo` is
-  // kept as-is, and a scheduled post becomes indexable on its own once its
-  // instant passes.
-  return isLivePost(post) ? post : { ...post, seo: { ...post.seo, noIndexing: true } };
+  // ahead — is only served in a `?draft=true` preview, and then must never be
+  // indexed. Everything else the post declared under `seo` is kept as-is, and a
+  // scheduled post becomes indexable on its own once its instant passes.
+  const url = new URL(req?.url ?? props.__pageUrl ?? "http://localhost/");
+  if (!isDraftPreview(url)) return null;
+  return { ...post, seo: { ...post.seo, noIndexing: true } };
 }

package/src/loaders/BlogPostPage.ts

@@ -3,6 +3,7 @@ import { ancestorsOf, indexCategories, withCategoryPath } from "../core/category
 import { getRecordsByPath } from "../core/records";
 import type { BlogPost, BlogPostPage, Category } from "../types";
 import { isLivePost } from "../types";
+import { isDraftPreview } from "../utils/draftPreview";
 
 const COLLECTION_PATH = "collections/blog/posts";
 const ACCESSOR = "post";
@@ -30,6 +31,11 @@ export default function BlogPostPageLoader(
 
   if (!post) return null;
 
+  // A post that isn't live yet — unpublished, or scheduled for an instant still
+  // ahead — only renders in a `?draft=true` preview. Without it the page
+  // answers as if the post didn't exist.
+  if (!isLivePost(post) && !isDraftPreview(url)) return null;
+
   // The post lives under the full path of its primary category, so the
   // breadcrumb and the canonical need that category's ancestor chain. A broken
   // categories collection must not take the post page down with it.
@@ -66,10 +72,9 @@ export default function BlogPostPageLoader(
       description: post?.seo?.description || post?.excerpt,
       canonical: post?.seo?.canonical || canonical || url.href,
       image: post?.seo?.image || post?.image,
-      // A post that isn't live yet — unpublished, or scheduled for an instant
-      // still ahead — renders anyway, because that page *is* the CMS preview.
-      // It just must never be indexed, even if the URL leaks. A scheduled post
-      // becomes indexable on its own once its instant passes.
+      // A non-live post reaching this point is a draft preview: it must never
+      // be indexed, even if the URL leaks. A scheduled post becomes indexable
+      // on its own once its instant passes.
       noIndexing: post?.seo?.noIndexing || !isLivePost(post),
     },
   };

package/src/types.ts

@@ -95,7 +95,7 @@ export interface BlogPost {
   slug: string;
   /**
    * @title Status
-   * @description Publication status. Anything other than `published` is kept out of listings and never indexed. Posts with no status are treated as published.
+   * @description Publication status. A post is live with no status, as `published`, or as `scheduled` once its scheduled date has passed. Any other post (a draft, a `scheduled` post before its date, or any other status) is kept out of listings and never indexed, and its page only renders with `?draft=true` in the URL.
    */
   status?: PostStatus;
   /**
@@ -146,8 +146,9 @@ export interface BlogPost {
 /**
  * Publication status of a post. `published` (or an absent value, for legacy
  * posts) renders on the live site; `scheduled` renders once its
- * `scheduledDatetime` has passed; every other value keeps the post out of
- * listings and out of the index.
+ * `scheduledDatetime` has passed. Until then, and for every other value, the
+ * post is kept out of listings and out of the index, and its own page only
+ * renders in a `?draft=true` preview.
  *
  * `generating` and `awaiting_review` are written by the autonomous-blog agent
  * while a post is still being produced, which is why the checks below are

package/src/utils/draftPreview.ts

@@ -0,0 +1,13 @@
+/** Query parameter that opens a post page in draft preview. */
+export const DRAFT_PREVIEW_PARAM = "draft";
+
+/**
+ * Whether the page was opened as a draft preview (`?draft=true`).
+ *
+ * A post that isn't live (a draft, a post still being generated, a scheduled
+ * post whose instant hasn't arrived) only renders on its own page in a
+ * preview; anywhere else the page answers as if the post didn't exist. Only the
+ * literal `true` turns it on: any other value, or none, is the live site.
+ */
+export const isDraftPreview = (url: URL): boolean =>
+  url.searchParams.get(DRAFT_PREVIEW_PARAM) === "true";