@decocms/apps-blog 8.0.0 → 8.1.0-next.0

package/src/loaders/BlogpostListing.ts

@@ -1,101 +1,167 @@
+import { logger, serializeError } from "@decocms/blocks/sdk/logger";
+import {
+  ancestorsOf,
+  descendantSlugs,
+  indexCategories,
+  withCategoryPath,
+} from "../core/categoryTree";
 import handlePosts, { slicePosts } from "../core/handlePosts";
 import { getRecordsByPath } from "../core/records";
-import type { BlogPost, BlogPostListingPage, PageInfo, SortBy } from "../types";
+import type { BlogPost, BlogPostListingPage, Category, PageInfo, SortBy } from "../types";
 
 const COLLECTION_PATH = "collections/blog/posts";
 const ACCESSOR = "post";
+const CATEGORIES_PATH = "collections/blog/categories";
+const CATEGORY_ACCESSOR = "category";
 
 export interface Props {
-	/**
-	 * @title Category Slug
-	 * @description Filter by a specific category slug.
-	 */
-	slug?: string;
-	/**
-	 * @title Items per page
-	 * @description Number of posts per page to display.
-	 */
-	count?: number;
-	/**
-	 * @title Page query parameter
-	 * @description The current page number. Defaults to 1.
-	 */
-	page?: number;
-	/**
-	 * @title Page sorting parameter
-	 * @description The sorting option. Default is "date_desc"
-	 */
-	sortBy?: SortBy;
-	/**
-	 * @description Overrides the query term at url
-	 */
-	query?: string;
+  /**
+   * @title Category Slug
+   * @description Filter by a category slug. May be a full path
+   * ("parent/child"); posts of every subcategory below the last segment are
+   * included.
+   */
+  slug?: string;
+  /**
+   * @title Items per page
+   * @description Number of posts per page to display.
+   */
+  count?: number;
+  /**
+   * @title Page query parameter
+   * @description The current page number. Defaults to 1.
+   */
+  page?: number;
+  /**
+   * @title Page sorting parameter
+   * @description The sorting option. Default is "date_desc"
+   */
+  sortBy?: SortBy;
+  /**
+   * @description Overrides the query term at url
+   */
+  query?: string;
 }
 
+const report = (scope: string, e: unknown) => {
+  const error = serializeError(e);
+  logger.error(error.message, { error, scope });
+};
+
+/** Categories with a usable name and slug, alphabetically. */
+const loadCategories = (): Category[] =>
+  getRecordsByPath<Category>(CATEGORIES_PATH, CATEGORY_ACCESSOR)
+    .filter(
+      (c) =>
+        typeof c?.name === "string" &&
+        c.name.length > 0 &&
+        typeof c?.slug === "string" &&
+        c.slug.length > 0,
+    )
+    .sort((a, b) => a.name.localeCompare(b.name));
+
 /**
- * @title BlogPostList
- * @description Retrieves a paginated list of blog posts.
+ * @title BlogPostListing
+ * @description Retrieves a paginated listing page of blog posts.
  */
-export default function BlogPostList(
-	props: Props & { __pageUrl?: string },
-	req?: Request,
-): BlogPostListingPage | null {
-	const { page, count, slug, sortBy, query } = props;
-	const rawUrl = req?.url ?? props.__pageUrl ?? "http://localhost/";
-	const url = new URL(rawUrl);
-	const params = url.searchParams;
-	const postsPerPage = Number(count ?? params.get("count") ?? 12);
-	const pageNumber = Number(page ?? params.get("page") ?? 1);
-	const pageSort = sortBy ?? (params.get("sortBy") as SortBy) ?? "date_desc";
-	const term = query ?? params.get("q") ?? undefined;
-
-	const posts = getRecordsByPath<BlogPost>(COLLECTION_PATH, ACCESSOR);
-
-	try {
-		const handledPosts = handlePosts(posts, pageSort, slug, undefined, term);
-
-		if (!handledPosts) return null;
-
-		const slicedPosts = slicePosts(handledPosts, pageNumber, postsPerPage);
-		if (slicedPosts.length === 0) return null;
-
-		const category = slicedPosts[0].categories?.find((c) => c.slug === slug);
-
-		return {
-			posts: slicedPosts,
-			pageInfo: toPageInfo(handledPosts, postsPerPage, pageNumber, params),
-			seo: {
-				title: category?.name ?? "",
-				canonical: new URL(url.pathname, url.origin).href,
-			},
-		};
-	} catch (e) {
-		console.error("[BlogpostListing]", e);
-		return null;
-	}
+export default async function BlogPostListing(
+  props: Props & { __pageUrl?: string },
+  req?: Request,
+): Promise<BlogPostListingPage | null> {
+  const { page, count, slug, sortBy, query } = props;
+  const rawUrl = req?.url ?? props.__pageUrl ?? "http://localhost/";
+  const url = new URL(rawUrl);
+  const params = url.searchParams;
+  const postsPerPage = Number(count ?? params.get("count") ?? 12);
+  const pageNumber = Number(page ?? params.get("page") ?? 1);
+  const pageSort = sortBy ?? (params.get("sortBy") as SortBy) ?? "date_desc";
+  const term = query ?? params.get("q") ?? undefined;
+
+  const posts = getRecordsByPath<BlogPost>(COLLECTION_PATH, ACCESSOR);
+
+  try {
+    let categories: Category[] | null = null;
+    try {
+      categories = loadCategories();
+    } catch (e) {
+      report("blog/BlogpostListing/categories", e);
+    }
+
+    // The slug prop carries the whole category path ("pai/filho") when the
+    // site routes the listing as a catch-all; only the leaf identifies the
+    // category, the segments before it are its ancestors.
+    const requestedSegments = (slug ?? "").split("/").filter(Boolean);
+    const leafSlug = requestedSegments[requestedSegments.length - 1];
+
+    const index = indexCategories(categories);
+    const chain = leafSlug ? ancestorsOf(leafSlug, index) : null;
+
+    // A parent lists its own posts plus every descendant's.
+    const categorySlugs = leafSlug ? descendantSlugs(leafSlug, categories) : undefined;
+
+    const handledPosts = await handlePosts(posts, pageSort, categorySlugs, undefined, term);
+
+    if (!handledPosts) return null;
+
+    const slicedPosts = slicePosts(handledPosts, pageNumber, postsPerPage);
+    if (slicedPosts.length === 0) return null;
+
+    let category: Category | null = null;
+    if (leafSlug) {
+      // Prefer the standalone category record (it carries description and
+      // sections); fall back to the denormalized copy embedded in a post,
+      // which is all a site that never created category records will have.
+      category =
+        index.get(leafSlug) ??
+        slicedPosts[0]?.categories?.find((c) => c?.slug === leafSlug) ??
+        null;
+    }
+
+    // Only a chain that came out of the records is trustworthy enough to name
+    // a canonical URL; a missing or broken one keeps the flat behaviour.
+    const canonical = chain ? withCategoryPath(url, chain, { requested: requestedSegments }) : null;
+
+    return {
+      posts: slicedPosts,
+      category,
+      categories,
+      categoryPath: chain ?? (category ? [category] : null),
+      pageInfo: toPageInfo(handledPosts, postsPerPage, pageNumber, params),
+      seo: {
+        title: category?.name ?? "",
+        description: category?.description,
+        // Reached through a stale or wrong path, the page still renders and
+        // points at the one canonical URL instead of 404ing.
+        canonical: canonical ?? new URL(url.pathname, url.origin).href,
+      },
+    };
+  } catch (e) {
+    report("blog/BlogpostListing", e);
+    return null;
+  }
 }
 
 function toPageInfo(
-	posts: BlogPost[],
-	postsPerPage: number,
-	pageNumber: number,
-	params: URLSearchParams,
+  posts: BlogPost[],
+  postsPerPage: number,
+  pageNumber: number,
+  params: URLSearchParams,
 ): PageInfo {
-	const totalPosts = posts.length;
-	const totalPages = Math.ceil(totalPosts / postsPerPage);
-	const hasNextPage = totalPages > pageNumber;
-	const hasPrevPage = pageNumber > 1;
-	const nextPage = new URLSearchParams(params);
-	const previousPage = new URLSearchParams(params);
-
-	if (hasNextPage) nextPage.set("page", (pageNumber + 1).toString());
-	if (hasPrevPage) previousPage.set("page", (pageNumber - 1).toString());
-
-	return {
-		nextPage: hasNextPage ? `?${nextPage}` : undefined,
-		previousPage: hasPrevPage ? `?${previousPage}` : undefined,
-		currentPage: pageNumber,
-		records: totalPosts,
-		recordPerPage: postsPerPage,
-	};
+  const totalPosts = posts.length;
+  const totalPages = Math.ceil(totalPosts / postsPerPage);
+  const hasNextPage = totalPages > pageNumber;
+  const hasPrevPage = pageNumber > 1;
+  const nextPage = new URLSearchParams(params);
+  const previousPage = new URLSearchParams(params);
+
+  if (hasNextPage) nextPage.set("page", (pageNumber + 1).toString());
+  if (hasPrevPage) previousPage.set("page", (pageNumber - 1).toString());
+
+  return {
+    nextPage: hasNextPage ? `?${nextPage}` : undefined,
+    previousPage: hasPrevPage ? `?${previousPage}` : undefined,
+    currentPage: pageNumber,
+    records: totalPosts,
+    recordPerPage: postsPerPage,
+  };
 }

package/src/loaders/GetCategories.ts

@@ -1,3 +1,4 @@
+import { childrenOf } from "../core/categoryTree";
 import { getRecordsByPath } from "../core/records";
 import type { Category } from "../types";
 
@@ -5,21 +6,26 @@ const COLLECTION_PATH = "collections/blog/categories";
 const ACCESSOR = "category";
 
 export interface Props {
-	/**
-	 * @title Category Slug
-	 * @description Get the category data from a specific slug.
-	 */
-	slug?: string;
-	/**
-	 * @title Items count
-	 * @description Number of categories to return
-	 */
-	count?: number;
-	/**
-	 * @title Sort
-	 * @description The sorting option. Default is "title_desc"
-	 */
-	sortBy?: "title_asc" | "title_desc";
+  /**
+   * @title Category Slug
+   * @description Get the category data from a specific slug.
+   */
+  slug?: string;
+  /**
+   * @title Parent category slug
+   * @description Return only the direct children of this category.
+   */
+  parentSlug?: string;
+  /**
+   * @title Items count
+   * @description Number of categories to return
+   */
+  count?: number;
+  /**
+   * @title Sort
+   * @description The sorting option. Default is "title_desc"
+   */
+  sortBy?: "title_asc" | "title_desc";
 }
 
 /**
@@ -27,22 +33,39 @@ export interface Props {
  * @description Retrieves a list of blog categories.
  */
 export default function GetCategories({
-	count,
-	slug,
-	sortBy = "title_desc",
+  count,
+  slug,
+  parentSlug,
+  sortBy = "title_desc",
 }: Props): Category[] | null {
-	const categories = getRecordsByPath<Category>(COLLECTION_PATH, ACCESSOR);
+  const categories = getRecordsByPath<Category>(COLLECTION_PATH, ACCESSOR);
 
-	if (!categories?.length) return null;
+  if (!categories?.length) return null;
 
-	if (slug) {
-		return categories.filter((c) => c.slug === slug);
-	}
+  // Records come straight from the CMS, so name/slug are strings only by
+  // convention. A record missing either has no route and no label, so it would
+  // render as a blank chip linking nowhere — and would throw in the
+  // `localeCompare` sort below.
+  const validCategories = categories.filter(
+    (c) =>
+      typeof c?.name === "string" &&
+      c.name.length > 0 &&
+      typeof c?.slug === "string" &&
+      c.slug.length > 0,
+  );
 
-	const sortedCategories = categories.sort((a, b) => {
-		const comparison = a.name.localeCompare(b.name);
-		return sortBy.endsWith("_desc") ? comparison : -comparison;
-	});
+  if (slug) {
+    return validCategories.filter((c) => c.slug === slug);
+  }
 
-	return count ? sortedCategories.slice(0, count) : sortedCategories;
+  if (!validCategories.length) return null;
+
+  const scoped = parentSlug ? childrenOf(parentSlug, validCategories) : validCategories;
+
+  const sortedCategories = scoped.sort((a, b) => {
+    const comparison = a.name.localeCompare(b.name);
+    return sortBy.endsWith("_desc") ? comparison : -comparison;
+  });
+
+  return count ? sortedCategories.slice(0, count) : sortedCategories;
 }

package/src/loaders/extensions/BlogpostList/ratings.ts

@@ -0,0 +1,36 @@
+import { getRatings } from "../../../core/records";
+import type { BlogPost, Ignore } from "../../../types";
+import type { ExtensionOf } from "../types";
+
+export interface Props {
+  /**
+   * @description Ignore ratings in the aggregateRating calc
+   */
+  ignoreRatings?: Ignore;
+  /**
+   * @description Return only aggregate rating object
+   */
+  onlyAggregate?: boolean;
+}
+
+/**
+ * @title ExtensionOf BlogPost list: Ratings
+ * @description It can harm performance. Use wisely
+ */
+export default function ratingsExt({
+  ignoreRatings,
+  onlyAggregate,
+}: Props): ExtensionOf<BlogPost[] | null> {
+  return async (posts: BlogPost[] | null) => {
+    if (!posts || posts.length === 0) {
+      return null;
+    }
+
+    return Promise.all(
+      posts.map(async (post) => {
+        const ratings = await getRatings({ post, ignoreRatings, onlyAggregate });
+        return { ...post, ...ratings };
+      }),
+    );
+  };
+}

package/src/loaders/extensions/BlogpostList/reviews.ts

@@ -0,0 +1,36 @@
+import { getReviews } from "../../../core/records";
+import type { BlogPost, Ignore } from "../../../types";
+import type { ExtensionOf } from "../types";
+
+export interface Props {
+  /**
+   * @description Ignore specific reviews
+   */
+  ignoreReviews?: Ignore;
+  /**
+   * @description Order By
+   */
+  orderBy?: "date_asc" | "date_desc";
+}
+
+/**
+ * @title ExtensionOf BlogPost list: Reviews
+ * @description It can harm performance. Use wisely
+ */
+export default function reviewsExt({
+  ignoreReviews,
+  orderBy,
+}: Props): ExtensionOf<BlogPost[] | null> {
+  return async (posts: BlogPost[] | null) => {
+    if (!posts || posts.length === 0) {
+      return null;
+    }
+
+    return Promise.all(
+      posts.map(async (post) => {
+        const reviews = await getReviews({ post, ignoreReviews, orderBy });
+        return { ...post, ...reviews };
+      }),
+    );
+  };
+}

package/src/loaders/extensions/BlogpostListing/ratings.ts

@@ -0,0 +1,38 @@
+import { getRatings } from "../../../core/records";
+import type { BlogPostListingPage, Ignore } from "../../../types";
+import type { ExtensionOf } from "../types";
+
+export interface Props {
+  /**
+   * @description Ignore ratings in the aggregateRating calc
+   */
+  ignoreRatings?: Ignore;
+  /**
+   * @description Return only aggregate rating object
+   */
+  onlyAggregate?: boolean;
+}
+
+/**
+ * @title ExtensionOf BlogPostListing: Ratings
+ * @description It can harm performance. Use wisely
+ */
+export default function ratingsExt({
+  ignoreRatings,
+  onlyAggregate,
+}: Props): ExtensionOf<BlogPostListingPage | null> {
+  return async (blogpostListingPage: BlogPostListingPage | null) => {
+    if (!blogpostListingPage) {
+      return null;
+    }
+
+    const posts = await Promise.all(
+      blogpostListingPage.posts.map(async (post) => {
+        const ratings = await getRatings({ post, onlyAggregate, ignoreRatings });
+        return { ...post, ...ratings };
+      }),
+    );
+
+    return { ...blogpostListingPage, posts };
+  };
+}

package/src/loaders/extensions/BlogpostListing/reviews.ts

@@ -0,0 +1,38 @@
+import { getReviews } from "../../../core/records";
+import type { BlogPostListingPage, Ignore } from "../../../types";
+import type { ExtensionOf } from "../types";
+
+export interface Props {
+  /**
+   * @description Ignore specific reviews
+   */
+  ignoreReviews?: Ignore;
+  /**
+   * @description Order By
+   */
+  orderBy?: "date_asc" | "date_desc";
+}
+
+/**
+ * @title ExtensionOf BlogPostListing: Reviews
+ * @description It can harm performance. Use wisely
+ */
+export default function reviewsExt({
+  ignoreReviews,
+  orderBy,
+}: Props): ExtensionOf<BlogPostListingPage | null> {
+  return async (blogpostListingPage: BlogPostListingPage | null) => {
+    if (!blogpostListingPage) {
+      return null;
+    }
+
+    const posts = await Promise.all(
+      blogpostListingPage.posts.map(async (post) => {
+        const reviews = await getReviews({ post, ignoreReviews, orderBy });
+        return { ...post, ...reviews };
+      }),
+    );
+
+    return { ...blogpostListingPage, posts };
+  };
+}

package/src/loaders/extensions/BlogpostPage/ratings.ts

@@ -0,0 +1,24 @@
+import { getRatings } from "../../../core/records";
+import type { BlogPostPage, Ignore } from "../../../types";
+import type { ExtensionOf } from "../types";
+
+export interface Props {
+  /**
+   * @description Ignore ratings in the aggregateRating calc
+   */
+  ignoreRatings?: Ignore;
+}
+
+/**
+ * @title ExtensionOf BlogPostPage: Ratings
+ * @description It can harm performance. Use wisely
+ */
+export default function ratingsExt({ ignoreRatings }: Props): ExtensionOf<BlogPostPage | null> {
+  return async (blogpostPage: BlogPostPage | null) => {
+    if (!blogpostPage) {
+      return null;
+    }
+    const post = await getRatings({ post: blogpostPage.post, ignoreRatings });
+    return { ...blogpostPage, post };
+  };
+}

package/src/loaders/extensions/BlogpostPage/reviews.ts

@@ -0,0 +1,31 @@
+import { getReviews } from "../../../core/records";
+import type { BlogPostPage, Ignore } from "../../../types";
+import type { ExtensionOf } from "../types";
+
+export interface Props {
+  /**
+   * @description Ignore specific reviews
+   */
+  ignoreReviews?: Ignore;
+  /**
+   * @description Order By
+   */
+  orderBy?: "date_asc" | "date_desc";
+}
+
+/**
+ * @title ExtensionOf BlogPostPage: Reviews
+ * @description It can harm performance. Use wisely
+ */
+export default function reviewsExt({
+  ignoreReviews,
+  orderBy,
+}: Props): ExtensionOf<BlogPostPage | null> {
+  return async (blogpostPage: BlogPostPage | null) => {
+    if (!blogpostPage) {
+      return null;
+    }
+    const post = await getReviews({ post: blogpostPage.post, ignoreReviews, orderBy });
+    return { ...blogpostPage, post };
+  };
+}

package/src/loaders/extensions/types.ts

@@ -0,0 +1,15 @@
+/**
+ * An enrichment step applied to a loader's already-resolved output.
+ *
+ * In `deco-cx/apps` this type comes from `website/loaders/extension.ts`, which
+ * also ships the generic `extension` loader that composes a list of these over
+ * one data source. That loader has not been ported into
+ * `@decocms/apps-website`, so the type is declared here rather than imported —
+ * the *composition* plumbing is a website-app concern and porting it into
+ * apps-blog would put it in the wrong package (see this package's README for
+ * the tracked gap).
+ *
+ * Each extension below is therefore usable directly: call it to obtain the
+ * enrichment function, then apply that to the loader result.
+ */
+export type ExtensionOf<T> = (data: T) => Promise<T>;