@postedin/cms-client 0.1.0

package/src/home-page.ts

@@ -0,0 +1,83 @@
+import type { WiredPage } from './collections/pages';
+import type { Context } from './context';
+import type { Locale } from './locales';
+import type { Page } from './payload-types';
+import type { HomePageRef } from './routes';
+
+async function fetchHomePage(
+	ctx: Context,
+	locale: Locale,
+): Promise<WiredPage | null> {
+	const options = await ctx.cms(locale).options();
+	const configured = options.homepage?.page;
+	const id =
+		typeof configured === 'string' ? configured : (configured?.id ?? null);
+
+	if (!id) {
+		return null;
+	}
+
+	// Read the standalone document rather than the copy embedded in the options
+	// global: globals are fetched without locale fallback, so an untranslated
+	// homepage would come back with null title and null block copy and render as
+	// a blank page. It is also the one page with no other route to reach it, so
+	// default-locale content beats nothing at all.
+	const [doc] = await ctx.api.fetchCmsCollection<Page>('pages', {
+		locale,
+		fallback: 'default',
+		status: 'published',
+		limit: 1,
+		query: { where: { id: { equals: id } } },
+	});
+
+	if (!doc) {
+		return null;
+	}
+
+	const path = (doc.breadcrumbs?.at(-1)?.url ?? doc.slug ?? '').replace(
+		/^\//,
+		'',
+	);
+
+	// `children` stays empty: the homepage is rendered on its own, not as part of
+	// the page tree `cms.pages` builds.
+	return { ...doc, children: [], parent: undefined, path } as WiredPage;
+}
+
+export function createHomePage(ctx: Context) {
+	const cache = new Map<Locale, Promise<WiredPage | null>>();
+
+	/**
+	 * The page configured as the site homepage, or `null` when the blog index is
+	 * used instead. This is the single source of truth for "there is a homepage":
+	 * `/` renders whatever it returns and `[...slug]` skips exactly the same
+	 * document, so the route that serves the page and the route that steps aside
+	 * for it can never disagree.
+	 *
+	 * Server-only. The result is cached per locale, so calling it from every
+	 * component costs one fetch per locale per build.
+	 */
+	function getHomePage(locale: Locale): Promise<WiredPage | null> {
+		let pending = cache.get(locale);
+
+		if (!pending) {
+			pending = fetchHomePage(ctx, locale);
+			cache.set(locale, pending);
+		}
+
+		return pending;
+	}
+
+	/**
+	 * The homepage reduced to what URL building needs. Hand it to `createRoutes` or
+	 * `cmsToHref` — or down to a hydrated island as a prop — so links pointing at
+	 * that page resolve to `/` (or `/en/`) instead of its own slug route.
+	 */
+	async function getHomePageRef(locale: Locale): Promise<HomePageRef> {
+		const page = await getHomePage(locale);
+
+		return page ? { id: page.id, path: page.path } : null;
+	}
+
+	return { getHomePage, getHomePageRef };
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+export type {
+	Api,
+	Collection,
+	FallbackMode,
+	FetchCmsCollectionOptions,
+	FetchCmsGlobalOptions,
+	ResolveUploadUrl,
+	UploadUse,
+} from './api';
+export { mapWithConcurrency } from './api';
+export type { BlogListing } from './blog-listing';
+export {
+	type Client,
+	type ClientOptions,
+	type CmsWith,
+	createClient,
+	type Extension,
+	type ExtensionContext,
+	type Extensions,
+} from './client';
+export type { Cms } from './cms';
+export type { CmsToHref } from './cms-to-href';
+export type {
+	AppearanceFallbacks,
+	WiredAppearance,
+} from './collections/appearance';
+export { DEFAULT_APPEARANCE_FALLBACKS } from './collections/appearance';
+export type { WiredArea } from './collections/areas';
+export type { WiredAuthor } from './collections/authors';
+export type {
+	CategoryBreadcrumb,
+	CountedCategory,
+	WiredCategory,
+} from './collections/categories';
+export type {
+	CmsCallToActionLinks,
+	CmsFooter,
+	CmsHeader,
+	CmsLink,
+	CmsMainMenu,
+	CmsMenuItem,
+	CmsSocialLinks,
+} from './collections/header-footer';
+export type { WiredPage } from './collections/pages';
+export type { WiredPost } from './collections/posts';
+export type { WiredQuestion } from './collections/questions';
+export type { WiredTag } from './collections/tags';
+export type { WiredTeamMember } from './collections/team-members';
+export * from './form-proxy';
+export { createCollectionLoader, createGlobalLoader, type Doc } from './loader';
+export {
+	defineLocales,
+	type Locale,
+	type LocaleOptions,
+	type Locales,
+} from './locales';
+export {
+	type MenuCollectionData,
+	type MenuLabels,
+	resolveMenuItems,
+} from './resolve-menu-items';
+export {
+	type CreateRoutes,
+	defineRoutes,
+	type HomePageRef,
+	type Routes,
+} from './routes';
+export { defineCmsToHref } from './cms-to-href';

package/src/loader.ts

@@ -0,0 +1,83 @@
+export function createGlobalLoader<TInput, TOutput = TInput>(
+	fetchFn: () => Promise<TInput>,
+	options?: {
+		transform?: (data: TInput) => Promise<TOutput> | TOutput;
+	},
+) {
+	let cache: Promise<TOutput> | TOutput | undefined;
+
+	return async () => {
+		if (!cache) {
+			cache = fetchFn().then(async (data) => {
+				if (options?.transform) {
+					return await options.transform(data);
+				}
+
+				return data as unknown as TOutput;
+			});
+		}
+
+		return await cache;
+	};
+}
+
+export interface Doc {
+	id: string;
+	slug?: string;
+	path?: string;
+	title?: string;
+	name?: string | null;
+}
+
+export function createCollectionLoader<
+	TInput extends Array<any>,
+	TOutput extends Array<any> = TInput,
+>(
+	fetchFn: () => Promise<TInput>,
+	options?: {
+		transform?: (data: TInput) => Promise<TOutput> | TOutput;
+	},
+) {
+	let cache: Promise<TOutput> | TOutput | undefined;
+
+	const load = async () => {
+		if (!cache) {
+			cache = fetchFn().then(async (data) => {
+				if (options?.transform) {
+					return await options.transform(data);
+				}
+
+				return data as unknown as TOutput;
+			});
+		}
+
+		return await cache;
+	};
+
+	return Object.assign(load, {
+		page: async (
+			page: number,
+			limit: number,
+			options: { excluded: Doc[] } = { excluded: [] },
+		) => {
+			const data = (await load()).filter((doc) => {
+				if (!options.excluded.length) {
+					return true;
+				}
+
+				return !options.excluded.find((ex) => ex.id === doc.id);
+			});
+
+			const first = (page - 1) * limit;
+			const last = first + limit;
+
+			return data.slice(first, last) as TOutput;
+		},
+		find: async (predicate: Parameters<any[]['find']>[0]) => {
+			return ((await load()) as TOutput).find(predicate);
+		},
+		filter: async (predicate: Parameters<any[]['filter']>[0]) => {
+			return ((await load()) as TOutput).filter(predicate);
+		},
+	});
+}

package/src/locales.ts

@@ -0,0 +1,80 @@
+import type { Config } from './payload-types';
+
+/** Every locale the CMS schema knows. A site builds a subset of them. */
+export type Locale = Config['locale'];
+
+export interface LocaleOptions {
+	/** The locales this site builds, default first or not. */
+	locales: readonly Locale[];
+	/** The unprefixed locale. */
+	defaultLocale: Locale;
+	/** URL prefix per locale: `''` for the default, `'/en'` for English. */
+	localePrefix: Readonly<Record<Locale, string>>;
+}
+
+export type Locales = ReturnType<typeof defineLocales>;
+
+/**
+ * The locale helpers every URL in a site is built with. Pure, so a hydrated
+ * island can use them as well as the server.
+ */
+export function defineLocales({
+	locales,
+	defaultLocale,
+	localePrefix,
+}: LocaleOptions) {
+	function isLocale(value: unknown): value is Locale {
+		return (
+			typeof value === 'string' &&
+			(locales as readonly string[]).includes(value)
+		);
+	}
+
+	function resolveLocale(value: unknown): Locale {
+		return isLocale(value) ? value : defaultLocale;
+	}
+
+	function prefixPath(path: string, locale: Locale): string {
+		const prefix = localePrefix[locale];
+		if (!prefix) {
+			return path;
+		}
+		// The site is built with `trailingSlash: 'always'`, so the prefix alone is a
+		// 404: `/en` is not a route, `/en/` is. Layout falls back to this for any
+		// locale a page does not name an alternate for, which made the homepage's
+		// own language switcher — and the `hreflang` beside it — a dead link.
+		if (path === '/') {
+			return `${prefix}/`;
+		}
+		return `${prefix}${path}`;
+	}
+
+	function stripLocalePrefix(path: string): {
+		locale: Locale;
+		path: string;
+	} {
+		for (const locale of locales) {
+			const prefix = localePrefix[locale];
+			if (!prefix) {
+				continue;
+			}
+			if (path === prefix) {
+				return { locale, path: '/' };
+			}
+			if (path.startsWith(`${prefix}/`)) {
+				return { locale, path: path.slice(prefix.length) };
+			}
+		}
+		return { locale: defaultLocale, path };
+	}
+
+	return {
+		locales,
+		defaultLocale,
+		localePrefix,
+		isLocale,
+		resolveLocale,
+		prefixPath,
+		stripLocalePrefix,
+	};
+}