@postedin/cms-client 0.1.0

package/src/cms-to-href.ts

@@ -0,0 +1,70 @@
+import type { CmsLink } from './collections/header-footer';
+import type { Locale } from './locales';
+import type { Author, Category, Page, Post, Tag } from './payload-types';
+import type { CreateRoutes, HomePageRef } from './routes';
+
+export type CmsToHref = ReturnType<typeof defineCmsToHref>;
+
+/** `cmsToHref`, bound to the site's route builder. Pure; islands use it too. */
+export function defineCmsToHref(createRoutes: CreateRoutes) {
+	return (
+		link: Partial<CmsLink>,
+		locale: Locale,
+		homePage: HomePageRef,
+	): string | undefined => cmsToHref(createRoutes, link, locale, homePage);
+}
+
+function cmsToHref(
+	createRoutes: CreateRoutes,
+	{ type, url, reference }: Partial<CmsLink>,
+	locale: Locale,
+	// The page configured as the site homepage — read it with `getHomePageRef`
+	// (server) or take it as a prop (islands). `createRoutes` owns the collapse
+	// to `/`, so every `routes.page()` caller gets the same behaviour; passing it
+	// here just hands it through. Required so a new call site can't silently fall
+	// back to the wrong URL.
+	homePage: HomePageRef,
+): string | undefined {
+	if (type === 'custom') {
+		return url ?? undefined;
+	}
+
+	if (!reference?.relationTo || !reference.value) {
+		return undefined;
+	}
+
+	const routes = createRoutes(locale, homePage);
+
+	if (reference.relationTo === 'pages') {
+		const page = reference.value as Page | string;
+
+		// An unpopulated reference is just an id, so there is no path to route by.
+		// The homepage is still recoverable — it routes by id.
+		if (typeof page === 'string') {
+			return homePage && page === homePage.id ? routes.root() : undefined;
+		}
+
+		const rawPath = page.breadcrumbs?.at(-1)?.url ?? page.slug;
+		if (!rawPath) {
+			return undefined;
+		}
+		const path = rawPath.replace(/^\//, '');
+		return routes.find('page', path);
+	}
+
+	if (reference.relationTo === 'categories') {
+		return routes.find('category', (reference.value as Category).slug);
+	}
+
+	if (reference.relationTo === 'posts') {
+		return routes.find('post', (reference.value as Post).slug);
+	}
+
+	if (reference.relationTo === 'authors') {
+		return routes.find('author', (reference.value as Author).slug);
+	}
+
+	if (reference.relationTo === 'tags') {
+		return routes.find('tag', (reference.value as Tag).slug);
+	}
+}

package/src/cms.ts

@@ -0,0 +1,86 @@
+import appearance from './collections/appearance';
+import areas from './collections/areas';
+import authors from './collections/authors';
+import banners from './collections/banners';
+import categories, { type CountedCategory } from './collections/categories';
+import forms from './collections/forms';
+import headerFooter from './collections/header-footer';
+import imageLinks from './collections/image-links';
+import media from './collections/media';
+import options from './collections/options';
+import pages from './collections/pages';
+import posts from './collections/posts';
+import project from './collections/project';
+import questions from './collections/questions';
+import seo from './collections/seo';
+import tags from './collections/tags';
+import teamMembers from './collections/team-members';
+import type { Context } from './context';
+import type { Locale } from './locales';
+
+export type Cms = ReturnType<typeof buildCms>;
+
+export function buildCms(ctx: Context, locale: Locale) {
+	const categoriesService = categories(ctx, locale);
+	const postsService = posts(ctx, locale);
+
+	return {
+		locale,
+		areas: areas(ctx, locale),
+		authors: authors(ctx, locale),
+		banners: banners(ctx, locale),
+		appearance: appearance(ctx),
+		imageLinks: imageLinks(ctx, locale),
+		categories: {
+			...categoriesService,
+			populated: async () => {
+				const cats = await categoriesService.all();
+				const allPosts = await postsService.all();
+				const ids = new Set([
+					...allPosts.map((p) => p.category?.id).filter(Boolean),
+					...allPosts.flatMap((p) =>
+						(p.secondaryCategories ?? []).map((c) => c.id),
+					),
+				]);
+				return cats.filter((c) => ids.has(c.id));
+			},
+			// Categories that hold posts, each with how many. `populated()`
+			// answers only whether that number is non-zero and has five callers
+			// depending on its shape, so this is a second reading of the same
+			// fold rather than a change to it. Both collections are already
+			// cached, so it costs no extra fetch.
+			withCounts: async (): Promise<CountedCategory[]> => {
+				const cats = await categoriesService.all();
+				const allPosts = await postsService.all();
+
+				const counts = new Map<string, number>();
+				for (const post of allPosts) {
+					const ids = new Set(
+						[
+							post.category?.id,
+							...(post.secondaryCategories ?? []).map((c) => c.id),
+						].filter((id): id is string => !!id),
+					);
+					for (const id of ids) {
+						counts.set(id, (counts.get(id) ?? 0) + 1);
+					}
+				}
+
+				return cats
+					.map((c) => ({ ...c, postCount: counts.get(c.id) ?? 0 }))
+					.filter((c) => c.postCount > 0);
+			},
+		},
+		forms: forms(ctx, locale),
+		headerFooter: headerFooter(ctx, locale),
+		media: media(ctx, locale),
+		options: options(ctx, locale),
+		pages: pages(ctx, locale),
+		posts: postsService,
+		project: project(ctx),
+		questions: questions(ctx, locale),
+		seo: seo(ctx, locale),
+		tags: tags(ctx, locale),
+		teamMembers: teamMembers(ctx, locale),
+	};
+}

package/src/collections/appearance.ts

@@ -0,0 +1,94 @@
+import type { Context } from '../context';
+import { createGlobalLoader } from '../loader';
+import type { Appearance } from '../payload-types';
+
+export type WiredAppearance = Appearance & {
+	branding: NonNullable<Appearance['branding']> & {
+		brandColor: NonNullable<NonNullable<Appearance['branding']>['brandColor']>;
+		logo: NonNullable<NonNullable<Appearance['branding']>['logo']>;
+	};
+	backgroundColor: {
+		lightTheme: string;
+		darkTheme: string;
+	};
+};
+
+/**
+ * What a blank Appearance field falls back to. Both are CSS values, and both
+ * are a site's own: the template states them in its theme file, so its
+ * defaults are variables that file defines.
+ */
+export interface AppearanceFallbacks {
+	brandColor: string;
+	backgroundColor: { lightTheme: string; darkTheme: string };
+}
+
+export const DEFAULT_APPEARANCE_FALLBACKS: AppearanceFallbacks = {
+	// The theme ramp's 500.
+	brandColor: 'var(--color-theme-500)',
+	backgroundColor: {
+		lightTheme: 'var(--site-background-light)',
+		darkTheme: 'var(--site-background-dark)',
+	},
+};
+
+function removeInvalid<T extends Record<string, any>>(
+	obj: T | null | undefined,
+): Partial<T> {
+	if (obj === null || obj === undefined) {
+		return {};
+	}
+
+	const cleaned: Partial<T> = {};
+	for (const [key, value] of Object.entries(obj)) {
+		if (value !== null && value !== undefined && value !== '') {
+			cleaned[key as keyof T] = value;
+		}
+	}
+
+	return cleaned;
+}
+
+// Appearance (theme/colors/fonts) is fetched once, at config time, and handed
+// to `createClient`. It has no text content that needs translation, so every
+// locale reads the same document.
+//
+// Header theming is deliberately absent: it is not an Appearance field, so it
+// lives in the site.
+export default function (ctx: Context) {
+	return createGlobalLoader<Appearance, WiredAppearance>(
+		async () => {
+			if (!ctx.options.appearance) {
+				throw new Error(
+					'cms.appearance() needs the `appearance` option of createClient: the Appearance document fetched at config time.',
+				);
+			}
+			return ctx.options.appearance;
+		},
+		{
+			transform: (appearance) => {
+				const fallbacks =
+					ctx.options.appearanceFallbacks ?? DEFAULT_APPEARANCE_FALLBACKS;
+				return {
+					...appearance,
+					branding: {
+						...appearance.branding,
+						brandColor: appearance.branding?.brandColor || fallbacks.brandColor,
+						logo: {
+							type: appearance.branding?.logo?.type,
+							dark: appearance.branding?.logo?.dark,
+							darkSvg: appearance.branding?.logo?.darkSvg,
+							light: appearance.branding?.logo?.light,
+							lightSvg: appearance.branding?.logo?.lightSvg,
+						},
+						icon: appearance.branding?.icon,
+					},
+					backgroundColor: {
+						...fallbacks.backgroundColor,
+						...removeInvalid(appearance.backgroundColor),
+					},
+				} as WiredAppearance;
+			},
+		},
+	);
+}

package/src/collections/areas.ts

@@ -0,0 +1,29 @@
+import type { Context } from '../context';
+import type { Area, Page } from '../payload-types';
+import type { Locale } from '../locales';
+import { createCollectionLoader } from '../loader';
+
+export interface WiredArea extends Omit<Area, 'page'> {
+	page?: Page | null;
+}
+
+export default function (ctx: Context, locale: Locale) {
+	const areas = createCollectionLoader(
+		() =>
+			ctx.api.fetchCmsCollection<Area>('areas', {
+				sort: '_order',
+				locale,
+			}),
+		{
+			transform: (areas): WiredArea[] =>
+				areas.map((area) => ({
+					...area,
+					page: typeof area.page === 'object' ? area.page : null,
+				})),
+		},
+	);
+
+	return {
+		all: areas,
+	};
+}

package/src/collections/authors.ts

@@ -0,0 +1,27 @@
+import type { Context } from '../context';
+import type { Author } from '../payload-types';
+import type { Locale } from '../locales';
+import { createCollectionLoader } from '../loader';
+
+export interface WiredAuthor extends Omit<Author, 'slug'> {
+	slug: string;
+}
+
+export default function (ctx: Context, locale: Locale) {
+	const authors = createCollectionLoader(
+		async () => ctx.api.fetchCmsCollection<Author>('authors', { locale }),
+		{
+			transform: (authors) => {
+				const validAuthors = authors.filter((author) => author.slug);
+				return validAuthors as WiredAuthor[];
+			},
+		},
+	);
+
+	return {
+		all: authors,
+		findBySlug: async (slug: string) => {
+			return authors.find((author) => author.slug === slug);
+		},
+	};
+}

package/src/collections/banners.ts

@@ -0,0 +1,14 @@
+import type { Context } from '../context';
+import type { Banner } from '../payload-types';
+import type { Locale } from '../locales';
+import { createCollectionLoader } from '../loader';
+
+export default function (ctx: Context, locale: Locale) {
+	const banners = createCollectionLoader(async () =>
+		ctx.api.fetchCmsCollection<Banner>('banners', { locale }),
+	);
+
+	return {
+		all: banners,
+	};
+}

package/src/collections/categories.ts

@@ -0,0 +1,111 @@
+import type { Context } from '../context';
+import type { Category } from '../payload-types';
+import type { Locale } from '../locales';
+import { decodeHtml } from '../decode-html';
+import type { Locales } from '../locales';
+import { createCollectionLoader } from '../loader';
+
+export type CategoryBreadcrumb = { label: string; url: string };
+
+export interface WiredCategory extends Omit<Category, 'parent' | 'slug'> {
+	slug: string;
+	parent?: WiredCategory;
+	children: WiredCategory[];
+	path: string;
+	breadcrumbs: CategoryBreadcrumb[];
+}
+
+/**
+ * A category plus how many posts are filed under it. The count follows the same
+ * rule as `cms.posts.findByCategory`, counting a post under its primary and its
+ * secondary categories alike, so the number a listing prints is the number of
+ * entries the category page then shows.
+ */
+export interface CountedCategory extends WiredCategory {
+	postCount: number;
+}
+
+function getCategoryPath(category: WiredCategory): string {
+	if (!category.parent) {
+		return category.slug;
+	}
+	return `${getCategoryPath(category.parent)}/${category.slug}`;
+}
+
+function getCategoryBreadcrumbs(
+	category: WiredCategory,
+	locale: Locale,
+	prefixPath: Locales['prefixPath'],
+): CategoryBreadcrumb[] {
+	const ancestors = category.parent
+		? getCategoryBreadcrumbs(category.parent, locale, prefixPath)
+		: [];
+	const path = getCategoryPath(category);
+	return [
+		...ancestors,
+		{
+			label: category.title,
+			url: prefixPath(`/blog/category/${path}`, locale),
+		},
+	];
+}
+
+export default function (ctx: Context, locale: Locale) {
+	const categories = createCollectionLoader(
+		async () => ctx.api.fetchCmsCollection<Category>('categories', { locale }),
+		{
+			transform: (categories) => {
+				const catMap = new Map<string, WiredCategory>(
+					categories
+						.filter((category) => category.slug)
+						.map((category) => [
+							category.id,
+							{
+								...category,
+								title: decodeHtml(category.title),
+								children: [],
+								path: category.slug as string,
+								breadcrumbs: [],
+							} as WiredCategory,
+						]),
+				);
+
+				const wireRelationships = (category: WiredCategory) => {
+					if (typeof category.parent === 'string') {
+						const parent = catMap.get(category.parent);
+						if (parent) {
+							category.parent = parent;
+							parent.children.push(category);
+						}
+					}
+				};
+
+				catMap.forEach((category) => wireRelationships(category));
+
+				catMap.forEach((category) => {
+					category.path = getCategoryPath(category);
+					category.breadcrumbs = getCategoryBreadcrumbs(
+						category,
+						locale,
+						ctx.locales.prefixPath,
+					);
+				});
+
+				return Array.from(catMap.values());
+			},
+		},
+	);
+
+	return {
+		all: categories,
+		wire: async (category: Category | string | null | undefined) => {
+			if (!category) {
+				return null;
+			}
+
+			const id = typeof category === 'string' ? category : category.id;
+
+			return (await categories()).find((cat) => cat.id === id);
+		},
+	};
+}

package/src/collections/forms.ts

@@ -0,0 +1,29 @@
+import type { Context } from '../context';
+import type { Form } from '../payload-types';
+import type { Locale } from '../locales';
+import { createCollectionLoader } from '../loader';
+
+export default function (ctx: Context, locale: Locale) {
+	// Forms are fetched on their own instead of relying on the copy populated
+	// inside page/global blocks: those requests disable locale fallback, so an
+	// untranslated label would come back null and render an unusable field.
+	// A default-locale label beats a blank one.
+	const forms = createCollectionLoader(() =>
+		ctx.api.fetchCmsCollection<Form>('forms', { locale, fallback: 'default' }),
+	);
+
+	const findById = async (id: string): Promise<Form | null> =>
+		(await forms.find((form: Form) => form.id === id)) ?? null;
+
+	return {
+		all: forms,
+		findById,
+		// Swaps a form reference coming from a block for its localized document
+		resolve: async (form: Form | string): Promise<Form | null> => {
+			if (typeof form === 'string') {
+				return await findById(form);
+			}
+			return (await findById(form.id)) ?? form;
+		},
+	};
+}

package/src/collections/header-footer.ts

@@ -0,0 +1,19 @@
+import type { Context } from '../context';
+import type { HeaderFooter } from '../payload-types';
+import type { Locale } from '../locales';
+import { createGlobalLoader } from '../loader';
+
+export type CmsHeader = NonNullable<NonNullable<HeaderFooter>['header']>;
+export type CmsFooter = NonNullable<NonNullable<HeaderFooter>['footer']>;
+
+export type CmsMainMenu = NonNullable<CmsHeader['mainMenu']>;
+export type CmsMenuItem = NonNullable<CmsMainMenu[0]['menuItem']>;
+export type CmsLink = NonNullable<CmsMenuItem['mainLink']>;
+export type CmsSocialLinks = NonNullable<CmsHeader['socialLinks']>;
+export type CmsCallToActionLinks = NonNullable<CmsHeader['callToActionLinks']>;
+
+export default function (ctx: Context, locale: Locale) {
+	return createGlobalLoader(async () =>
+		ctx.api.fetchCmsGlobalCollection<HeaderFooter>('header-footer', { locale }),
+	);
+}

package/src/collections/image-links.ts

@@ -0,0 +1,14 @@
+import type { Context } from '../context';
+import type { ImageLink } from '../payload-types';
+import type { Locale } from '../locales';
+import { createCollectionLoader } from '../loader';
+
+export default function (ctx: Context, locale: Locale) {
+	const imageLinks = createCollectionLoader(async () =>
+		ctx.api.fetchCmsCollection<ImageLink>('image-links', { locale }),
+	);
+
+	return {
+		all: imageLinks,
+	};
+}

package/src/collections/media.ts

@@ -0,0 +1,18 @@
+import type { Context } from '../context';
+import type { Media } from '../payload-types';
+import type { Locale } from '../locales';
+import { createCollectionLoader } from '../loader';
+
+export default function (ctx: Context, locale: Locale) {
+	// depth: 0 — an upload's only relationship is `project`, which the CMS's
+	// multi-tenant plugin pins at maxDepth 0, so the response is identical to
+	// the default depth=2 one. Populating it costs roughly 3x per page, and
+	// this is the biggest collection a build reads.
+	const media = createCollectionLoader(async () =>
+		ctx.api.fetchCmsCollection<Media>('media', { locale, depth: 0 }),
+	);
+
+	return {
+		all: media,
+	};
+}

package/src/collections/options.ts

@@ -0,0 +1,10 @@
+import type { Context } from '../context';
+import type { Options } from '../payload-types';
+import type { Locale } from '../locales';
+import { createGlobalLoader } from '../loader';
+
+export default function (ctx: Context, locale: Locale) {
+	return createGlobalLoader(async () =>
+		ctx.api.fetchCmsGlobalCollection<Options>('options', { locale }),
+	);
+}

package/src/collections/pages.ts

@@ -0,0 +1,83 @@
+import type { Context } from '../context';
+import type { Page } from '../payload-types';
+import type { Locale } from '../locales';
+import { createCollectionLoader } from '../loader';
+
+export interface WiredPage extends Omit<Page, 'parent'> {
+	parent?: WiredPage;
+	children: WiredPage[];
+	path: string;
+}
+
+export default function (ctx: Context, locale: Locale) {
+	const pages = createCollectionLoader(
+		async () =>
+			ctx.api.fetchCmsCollection<Page>('pages', {
+				status: 'published',
+				locale,
+			}),
+		{
+			transform: (rawPages): WiredPage[] => {
+				// Pass 1: build map with path derived from Payload's breadcrumbs plugin
+				const pageMap = new Map<string, WiredPage>(
+					rawPages
+						.filter((page) => page.slug)
+						.map((page) => {
+							const path = (page.breadcrumbs?.at(-1)?.url ?? page.slug).replace(
+								/^\//,
+								'',
+							);
+							return [page.id, { ...page, children: [], path } as WiredPage];
+						}),
+				);
+
+				// Pass 2: wire parent references and populate children[]
+				// parent may be a string ID (depth=0) or a populated object (depth>0)
+				pageMap.forEach((page) => {
+					const rawParent = page.parent as
+						| WiredPage
+						| string
+						| null
+						| undefined;
+					const parentId =
+						typeof rawParent === 'string' ? rawParent : rawParent?.id;
+					if (parentId) {
+						const parent = pageMap.get(parentId);
+						if (parent) {
+							page.parent = parent;
+							parent.children.push(page);
+						} else {
+							page.parent = undefined;
+						}
+					}
+				});
+
+				// Pass 3: sort each parent's children by order (nulls sort last)
+				pageMap.forEach((page) => {
+					page.children.sort((a, b) => {
+						if (a.order == null && b.order == null) {
+							return 0;
+						}
+						if (a.order == null) {
+							return 1;
+						}
+						if (b.order == null) {
+							return -1;
+						}
+						return a.order - b.order;
+					});
+				});
+
+				return Array.from(pageMap.values());
+			},
+		},
+	);
+
+	return {
+		all: pages,
+		findByPath: async (path: string) =>
+			(await pages()).find((p) => p.path === path),
+		findById: async (id: string) =>
+			(await pages()).find((p) => p.id === id) ?? null,
+	};
+}