@justanarthur/payload-www 0.1.1

package/dist/render-utils.d.ts

@@ -0,0 +1,158 @@
+type CreatePreviewHandlerOptions = {
+	/** Resolves the host's site URL (used to construct preview links if
+	* the host navigates back to the canonical site). */
+	getServerSideURL: () => string;
+	/**
+	* Secret token the host configures in `process.env.PREVIEW_SECRET`.
+	* The handler validates `?previewSecret=...` against this value and
+	* 401s on mismatch.
+	*/
+	secret: string;
+	/**
+	* Whether to enable draft mode on a valid preview. Hosts that use
+	* their own preview mechanism can pass `false`.
+	* Default: `true`.
+	*/
+	enableDraftMode?: boolean;
+};
+/**
+* Build a Next.js `GET` route handler for the host's
+* `app/(payload)/next/preview/route.ts`. Validates the preview secret
+* from the query string, enables draft mode if configured, and
+* redirects to the `?path=...` value.
+*
+* Usage:
+*
+*   // app/(payload)/next/preview/route.ts
+*   import { createPreviewHandler } from '@justanarthur/payload-www/render-utils'
+*   import { getServerSideURL } from '@/utilities/getURL'
+*   const GET = createPreviewHandler({
+*     getServerSideURL,
+*     secret: process.env.PREVIEW_SECRET || ''
+*   })
+*/
+declare function createPreviewHandler(options: CreatePreviewHandlerOptions): (req: Request) => Promise<Response>;
+import { MetadataRoute } from "next";
+type CreateSitemapFileOptions = {
+	/**
+	* Collection slugs whose docs should appear in the sitemap. Each
+	* collection must have a `slug` field on its documents. The lib
+	* emits a single unified sitemap at `/sitemap.xml` listing every
+	* doc from every configured collection across every active locale.
+	*/
+	collections: string[];
+	/**
+	* The Payload config promise. The factory resolves it at request
+	* time.
+	*/
+	config: Promise<any>;
+	/**
+	* The host's site URL — used to build absolute URLs.
+	*/
+	getServerSideURL: () => string;
+	/**
+	* Locale prefix mode. Mirrors next-intl's `localePrefix` so the
+	* sitemap URLs match the host's actual route shape:
+	*
+	* - `'always'`: every URL is prefixed with `/{locale}/…`
+	*   (e.g. `/en/about`, `/uk/about`). The default.
+	* - `'as-needed'`: the default locale renders without a prefix
+	*   (e.g. `/about`), other locales are prefixed (`/uk/about`).
+	* - `'never'`: no locale prefix (only useful for single-locale
+	*   sites or hosts that don't expose locales in the URL).
+	*
+	* The default locale is read from `config.localization.defaultLocale`
+	* — the same single source of truth that next-intl and the rest of
+	* the lib use.
+	*/
+	localePrefix?: "always" | "as-needed" | "never";
+	/**
+	* Optional filter for which locales to include in the sitemap.
+	* Defaults to every locale declared in `config.localization.locales`.
+	*/
+	locales?: string[];
+	/**
+	* Optional URL path prefix per collection. The Pages collection
+	* lives at the root (`/about`) so it doesn't need a prefix, but
+	* collections mounted under a sub-route (e.g. a posts collection
+	* under `/posts/[...slug]`) need their URLs prefixed with `/posts`
+	* so the sitemap entries match the actual route.
+	*
+	* Defaults to `''` (no prefix). Pass a value like `'/posts'`
+	* (leading slash, no trailing slash) for a sub-routed collection.
+	*/
+	urlPrefixes?: Record<string, string>;
+	/**
+	* Optional priority / changeFrequency overrides per collection.
+	*/
+	perCollection?: Record<string, {
+		priority?: number;
+		changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+	}>;
+};
+/**
+* A Next.js sitemap function for the host's
+* `app/(frontend)/sitemap.ts`. Returns the typed
+* `MetadataRoute.Sitemap` array — Next.js handles XML serialization.
+*
+* Usage — single unified sitemap:
+*
+*   // app/(frontend)/sitemap.ts
+*   import { createSitemapFile } from '@justanarthur/payload-www/render-utils'
+*   import configPromise from '@payload-config'
+*   import { getServerSideURL } from '@/utilities/getURL'
+*
+*   createSitemapFile({
+*     collections: ['pages', 'posts'],
+*     config: configPromise,
+*     getServerSideURL,
+*     localePrefix: 'as-needed',
+*     urlPrefixes: { posts: '/posts' }
+*   })
+*
+* The lib resolves the sitemap at request time, queries every
+* configured collection across every active locale, and emits one
+* unified `<urlset>` with full `alternates.languages` hreflang blocks
+* per URL. Google accepts up to 50,000 URLs per file.
+*/
+type SitemapFunction = () => Promise<MetadataRoute.Sitemap>;
+declare function createSitemapFile(options: CreateSitemapFileOptions): SitemapFunction;
+import { ReactElement } from "react";
+/**
+* Hreflang alternate URLs as a `lang → url` map. Always includes an
+* `'x-default'` entry pointing at the default locale's URL.
+*/
+type HreflangAlternates = Record<string, string>;
+type LocaleSwitcherProps = {
+	/**
+	* The currently-active locale (the one being rendered). The
+	* switcher marks the corresponding link with `aria-current="true"`.
+	*/
+	currentLocale: string;
+	/**
+	* The hreflang alternates map as returned by the lib's metadata
+	* pipeline. Keys are locale codes; values are absolute URLs. An
+	* `'x-default'` entry is also expected.
+	*/
+	hreflangAlternates: HreflangAlternates;
+	/**
+	* Optional human-readable labels per locale. When missing, the
+	* switcher falls back to uppercased locale codes.
+	*/
+	labels?: Record<string, string>;
+};
+/**
+* Render a list of links to the same page in every other locale.
+* The component is server-renderable (no `'use client'`) and emits
+* a single `<nav>` element with one `<a>` per locale plus an
+* `x-default` fallback. The lib's `<PageShowcase>` mounts it as a
+* child of the sidebar; hosts can also drop it elsewhere on the
+* page.
+*/
+declare function LocaleSwitcher({ currentLocale, hreflangAlternates, labels }: LocaleSwitcherProps): ReactElement;
+declare const _default: {
+	createPreviewHandler: typeof createPreviewHandler;
+	createSitemapFile: typeof createSitemapFile;
+	LocaleSwitcher: typeof LocaleSwitcher;
+};
+export { _default as default, createSitemapFile, createPreviewHandler, SitemapFunction, LocaleSwitcherProps, LocaleSwitcher, CreateSitemapFileOptions, CreatePreviewHandlerOptions };

package/dist/render-utils.js

@@ -0,0 +1,341 @@
+
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/render/components/LocaleSwitcher.tsx
+var exports_LocaleSwitcher = {};
+__export(exports_LocaleSwitcher, {
+  LocaleSwitcher: () => LocaleSwitcher
+});
+import { jsx, jsxs } from "react/jsx-runtime";
+function LocaleSwitcher({
+  currentLocale,
+  hreflangAlternates,
+  labels
+}) {
+  const locales = Object.keys(hreflangAlternates).filter((k) => k !== "x-default");
+  return /* @__PURE__ */ jsx("nav", {
+    "aria-label": "Language",
+    className: "locale-switcher",
+    children: /* @__PURE__ */ jsxs("ul", {
+      className: "flex flex-wrap gap-2 list-none p-0 m-0",
+      children: [
+        locales.map((locale) => {
+          const href = hreflangAlternates[locale];
+          if (!href)
+            return null;
+          const isCurrent = locale === currentLocale;
+          return /* @__PURE__ */ jsx("li", {
+            children: /* @__PURE__ */ jsx("a", {
+              href,
+              "aria-current": isCurrent ? "true" : undefined,
+              hrefLang: locale,
+              className: "locale-switcher__link",
+              "data-locale": locale,
+              children: labels?.[locale] ?? locale.toUpperCase()
+            })
+          }, locale);
+        }),
+        hreflangAlternates["x-default"] ? /* @__PURE__ */ jsx("li", {
+          children: /* @__PURE__ */ jsx("a", {
+            href: hreflangAlternates["x-default"],
+            hrefLang: "x-default",
+            className: "locale-switcher__link",
+            "data-locale": "x-default",
+            children: labels?.["x-default"] ?? "Default"
+          })
+        }, "x-default") : null
+      ]
+    })
+  });
+}
+var init_LocaleSwitcher = () => {};
+
+// src/render/preview/createPreviewHandler.ts
+function createPreviewHandler(options) {
+  const { getServerSideURL: _getServerSideURL, secret, enableDraftMode = true } = options;
+  return async function GET(req) {
+    const { draftMode } = await import("next/headers");
+    const { redirect } = await import("next/navigation");
+    const url = new URL(req.url);
+    const path = url.searchParams.get("path") ?? "/";
+    const previewSecret = url.searchParams.get("previewSecret");
+    if (!previewSecret || previewSecret !== secret) {
+      return new Response("Invalid preview secret", { status: 401 });
+    }
+    if (enableDraftMode) {
+      (await draftMode()).enable();
+    }
+    redirect(path);
+    return new Response(null, { status: 204 });
+  };
+}
+
+// src/render/_locale.ts
+function prefixFor(locale, defaultLocale, mode) {
+  if (mode === "never")
+    return "";
+  if (mode === "as-needed" && locale === defaultLocale)
+    return "";
+  return `/${locale}`;
+}
+function resolveLocale(req) {
+  if (!req || typeof req !== "object")
+    return "";
+  const r = req;
+  if (typeof r.locale === "string" && r.locale.length > 0)
+    return r.locale;
+  const fallback = r.payload?.config?.localization?.defaultLocale;
+  if (typeof fallback === "string" && fallback.length > 0)
+    return fallback;
+  return "";
+}
+function allLocales(req) {
+  if (!req || typeof req !== "object")
+    return [];
+  const r = req;
+  const list = r.payload?.config?.localization?.locales;
+  if (!Array.isArray(list) || list.length === 0)
+    return [];
+  const out = [];
+  for (const entry of list) {
+    if (typeof entry === "string" && entry.length > 0) {
+      out.push(entry);
+    } else if (entry && typeof entry === "object" && "code" in entry) {
+      const code = entry.code;
+      if (typeof code === "string" && code.length > 0)
+        out.push(code);
+    }
+  }
+  return out;
+}
+
+// src/render/metadata/hreflang.ts
+async function buildHreflangAlternates({
+  siteUrl,
+  locale,
+  urlPrefix,
+  storedSlug,
+  queryAllLocaleSlugs,
+  nested,
+  homeSlug,
+  defaultLocale,
+  locales,
+  localePrefix = "always"
+}) {
+  const allLocaleSlugs = await queryAllLocaleSlugs(storedSlug, locale);
+  const languages = {};
+  const urlFor = (l, slug) => {
+    const trimmedPrefix = urlPrefix.replace(/^\/|\/$/g, "");
+    const prefixSegment = trimmedPrefix ? `/${trimmedPrefix}` : "";
+    const urlPath = slug === homeSlug ? "/" : nested ? "/" + slug.replaceAll("_", "/") : "/" + slug;
+    const localeSegment = localePrefix === "never" ? "" : localePrefix === "as-needed" && l === defaultLocale ? "" : `/${l}`;
+    return `${siteUrl}${localeSegment}${prefixSegment}${urlPath}`;
+  };
+  for (const l of locales) {
+    const slugForLocale = allLocaleSlugs?.[l];
+    if (!slugForLocale)
+      continue;
+    languages[l] = urlFor(l, slugForLocale);
+  }
+  if (allLocaleSlugs?.[defaultLocale]) {
+    languages["x-default"] = urlFor(defaultLocale, allLocaleSlugs[defaultLocale]);
+  }
+  return languages;
+}
+
+// src/render/metadata/query.ts
+import { getPayload } from "payload";
+import { cache } from "react";
+
+// src/core/utils/getFromImportMap.ts
+function getFromImportMap(key, importMap) {
+  return importMap[key.includes("#") ? key : key + "#default"];
+}
+
+// src/render/metadata/query.ts
+var queryDocBySlug = cache(async function queryDocBySlug2({
+  collectionSlug,
+  slug,
+  slugField = "slug",
+  locale,
+  draft = false,
+  config
+}) {
+  const payload = await getPayload({ config });
+  const result = await payload.find({
+    collection: collectionSlug,
+    draft,
+    limit: 1,
+    pagination: false,
+    overrideAccess: draft,
+    where: { [slugField]: { equals: slug } },
+    locale
+  });
+  return result.docs?.[0] ?? null;
+});
+var queryAllDocs = cache(async function queryAllDocs2({
+  collectionSlug,
+  slugField = "slug",
+  locale,
+  config
+}) {
+  const payload = await getPayload({ config });
+  const result = await payload.find({
+    collection: collectionSlug,
+    draft: false,
+    limit: 1000,
+    pagination: false,
+    overrideAccess: false,
+    select: { [slugField]: true },
+    locale
+  });
+  return result.docs ?? [];
+});
+var queryAllLocaleSlugs = cache(async function queryAllLocaleSlugs2({
+  collectionSlug,
+  slug,
+  slugField = "slug",
+  locale,
+  config
+}) {
+  const payload = await getPayload({ config });
+  const result = await payload.find({
+    collection: collectionSlug,
+    draft: false,
+    limit: 1,
+    pagination: false,
+    overrideAccess: false,
+    locale,
+    where: { [slugField]: { equals: slug } },
+    select: { [slugField]: true }
+  });
+  const doc = result.docs?.[0];
+  if (!doc)
+    return;
+  const fieldValue = doc?.[slugField];
+  if (fieldValue && typeof fieldValue === "object") {
+    return fieldValue;
+  }
+  const resolved = await config;
+  const rawLocales = Array.isArray(resolved?.localization?.localeCodes) ? resolved.localization.localeCodes : resolved?.localization?.locales?.map((l) => l.code) ?? [];
+  const out = {};
+  for (const l of rawLocales)
+    out[l] = String(fieldValue ?? slug);
+  return out;
+});
+var queryGlobal = cache(async function queryGlobal2({
+  globalSlug,
+  locale,
+  depth = 0,
+  draft = false,
+  config
+}) {
+  const payload = await getPayload({ config });
+  try {
+    const global = await payload.findGlobal({
+      slug: globalSlug,
+      depth,
+      draft,
+      locale
+    });
+    return global;
+  } catch {
+    return null;
+  }
+});
+function getRenderModuleExports(exportName, collection, importMap) {
+  const path = collection?.custom?.path;
+  if (!path)
+    return;
+  const mod = getFromImportMap(path, importMap);
+  return mod?.[exportName];
+}
+
+// src/render/sitemap/createSitemapFile.ts
+function createSitemapFile(options) {
+  const { collections } = options;
+  return async function sitemap() {
+    const cfg = await options.config;
+    const allLocales2 = Array.isArray(cfg.localization?.locales) ? cfg.localization.locales.map((l) => typeof l === "string" ? l : l.code) : [cfg.localization?.defaultLocale ?? "en"];
+    const defaultLocale = cfg.localization?.defaultLocale ?? allLocales2[0];
+    const activeLocales = Array.isArray(options.locales) && options.locales.length > 0 ? options.locales.filter((l) => allLocales2.includes(l)) : allLocales2;
+    const entries = [];
+    const seen = new Set;
+    for (const collectionSlug of collections) {
+      const collectionDefaults = options.perCollection?.[collectionSlug] ?? {};
+      const urlPrefix = (options.urlPrefixes?.[collectionSlug] ?? "").replace(/\/$/, "");
+      const siteUrl = options.getServerSideURL().replace(/\/$/, "");
+      for (const locale of activeLocales) {
+        const docs = await queryAllDocs({
+          collectionSlug,
+          slugField: "slug",
+          locale,
+          config: options.config
+        });
+        for (const doc of docs) {
+          const storedSlug = doc.slug;
+          if (typeof storedSlug !== "string" || storedSlug === "")
+            continue;
+          const dedupeKey = `${collectionSlug}:${locale}:${storedSlug}`;
+          if (seen.has(dedupeKey))
+            continue;
+          seen.add(dedupeKey);
+          const url = `${siteUrl}${prefixFor(locale, defaultLocale, options.localePrefix ?? "always")}${urlPrefix}/${storedSlug}`;
+          const languages = await buildHreflangAlternates({
+            siteUrl,
+            locale,
+            urlPrefix,
+            storedSlug,
+            nested: false,
+            homeSlug: "",
+            defaultLocale,
+            locales: activeLocales,
+            localePrefix: options.localePrefix,
+            queryAllLocaleSlugs: async (s, l) => {
+              const result = await queryAllLocaleSlugs({
+                collectionSlug,
+                slug: s,
+                slugField: "slug",
+                locale: l,
+                config: options.config
+              });
+              return result ?? undefined;
+            }
+          });
+          entries.push({
+            url,
+            lastModified: doc.updatedAt ? new Date(doc.updatedAt) : undefined,
+            changeFrequency: collectionDefaults.changefreq ?? "weekly",
+            priority: collectionDefaults.priority ?? 0.5,
+            alternates: { languages }
+          });
+        }
+      }
+    }
+    return entries;
+  };
+}
+
+// src/exports/render-utils.ts
+init_LocaleSwitcher();
+var render_utils_default = { createPreviewHandler, createSitemapFile, LocaleSwitcher };
+export {
+  render_utils_default as default,
+  createSitemapFile,
+  createPreviewHandler,
+  LocaleSwitcher
+};

package/dist/seed.d.ts

@@ -0,0 +1,76 @@
+import { Payload } from "payload";
+type SeedPageInput = {
+	slug: string;
+	title: Record<string, string>;
+	meta?: Record<string, {
+		title?: string;
+		description?: string;
+	}>;
+	blocks?: Array<Record<string, unknown>>;
+	status?: "draft" | "published";
+	publishedAt?: string;
+};
+type SeedPostInput = {
+	slug: string;
+	title: Record<string, string>;
+	excerpt?: Record<string, string>;
+	content?: Record<string, unknown>;
+	status?: "draft" | "published";
+	publishedAt?: string;
+};
+type SeedUserInput = {
+	email: string;
+	password?: string;
+	name?: string;
+};
+type SeedCategoryInput = {
+	title: string;
+	slug?: string;
+};
+type CreateBaseSeedOptions = {
+	defaultLocale?: string;
+	locales?: string[];
+	users?: SeedUserInput[];
+	categories?: SeedCategoryInput[];
+	pages?: SeedPageInput[];
+	posts?: SeedPostInput[];
+	dryRun?: boolean;
+};
+type CreateBaseSeedResult = {
+	users: Array<{
+		id: string | number;
+		email: string;
+	}>;
+	categories: Array<{
+		id: string | number;
+		title: string;
+		slug: string;
+	}>;
+	pages: Array<{
+		id: string | number;
+		slug: string;
+		locale: string;
+	}>;
+	posts: Array<{
+		id: string | number;
+		slug: string;
+		locale: string;
+	}>;
+};
+/**
+* Idempotent seeder for the lib's collections. Re-running on the
+* same database is a no-op for users (matched by email) and
+* categories (matched by title); pages and posts are matched by
+* slug and re-created if missing.
+*
+* Pages and posts are created once per slug — localized values are
+* stored in a single doc per slug. Tests assert the alternate
+* resolution by querying `locale: 'all'`.
+*
+* Throws on:
+*   - any block slug in a Page's `layout` that doesn't exist on the
+*     Pages collection's `blocks` field
+*   - a block without a `blockType`
+*/
+declare function createBaseSeed(payload: Payload, options?: CreateBaseSeedOptions): Promise<CreateBaseSeedResult>;
+export { createBaseSeed as default, createBaseSeed, SeedUserInput, SeedPostInput, SeedPageInput, SeedCategoryInput, CreateBaseSeedResult, CreateBaseSeedOptions };