@justanarthur/payload-www 0.1.1

package/dist/render-pages.d.ts

@@ -0,0 +1,574 @@
+import { Metadata, MetadataRoute } from "next";
+import { DataFromCollectionSlug, ImportMap, SanitizedConfig } from "payload";
+import { ReactElement, ReactNode } from "react";
+type BreadcrumbItem = {
+	label: string;
+	url: string;
+};
+type ArticleJsonLdEntry = {
+	type: "article";
+	id?: string;
+	schemaType?: "BlogPosting" | "Article" | "NewsArticle" | "TechArticle";
+	publisherName?: string;
+	publisherLogo?: string | null;
+};
+type WebSiteJsonLdEntry = {
+	type: "website";
+	id?: string;
+	name?: string;
+	alternateName?: string;
+};
+type OrganizationJsonLdEntry = {
+	type: "organization";
+	id?: string;
+	name?: string;
+	logo?: string;
+	sameAs?: string[];
+};
+type BreadcrumbsJsonLdEntry = {
+	type: "breadcrumbs";
+	id?: string;
+	items?: BreadcrumbItem[];
+	buildItems?: (doc: DataFromCollectionSlug<string>, url: string) => BreadcrumbItem[];
+};
+type CustomJsonLdEntry = {
+	type: "custom";
+	id?: string;
+	build: (ctx: {
+		doc: DataFromCollectionSlug<string>;
+		url: string;
+		locale: string;
+		siteUrl: string;
+	}) => Record<string, unknown>;
+};
+type JsonLdEntry = ArticleJsonLdEntry | WebSiteJsonLdEntry | OrganizationJsonLdEntry | BreadcrumbsJsonLdEntry | CustomJsonLdEntry;
+type JsonLdOutput = {
+	id: string;
+	schema: Record<string, unknown>;
+};
+/**
+* Minimal next-intl routing contract the lib reads. Hosts pass
+* their `defineRouting({...})` result directly; the lib only needs
+* the shape below.
+*
+* `localePrefix` accepts either the simple string form
+* (`'always' | 'as-needed' | 'never'`) or next-intl's verbose
+* `LocalePrefixConfigVerbose` shape (`{ mode, prefixes? }`). The lib
+* normalizes both to a string `mode` internally.
+*/
+type LocalePrefixValue = "always" | "as-needed" | "never" | {
+	mode?: "always" | "as-needed" | "never";
+};
+type PageRouting = {
+	locales: readonly string[];
+	defaultLocale: string;
+	localePrefix?: LocalePrefixValue;
+	/** Optional human-readable labels per locale (used by the
+	* `<LocaleSwitcher>`). Falls back to the locale code when missing.
+	* Not part of next-intl's `defineRouting` shape — the host extends
+	* its routing object to include it (e.g. via a type assertion). */
+	labels?: Record<string, string>;
+};
+type MetadataOptions = {
+	urlPrefix?: string;
+	/** When true (default), the lib generates a `{type:'website'}` JSON-LD
+	* entry per page. Pass an array to specify entries; pass `false` to
+	* skip. */
+	jsonLd?: boolean | JsonLdEntry[];
+	changefreq?: MetadataRoute.Sitemap[number]["changeFrequency"];
+	priority?: number;
+	/**
+	* Override the default `'website'` JSON-LD's `name` field. Only
+	* relevant when `jsonLd !== false` and no `name` is set on the
+	* auto-generated entry.
+	*/
+	websiteName?: string;
+};
+type ShowcaseOptions = {
+	/**
+	* Wrap the rendered page in a two-column layout with a sidebar
+	* that surfaces the page's metadata, JSON-LD, and a language
+	* switcher. Hosts that want a clean render (no sidebar) leave
+	* this `false` (the default). The demo's home page enables it
+	* so visitors can see every artifact the lib generates in one
+	* place.
+	*/
+	enabled?: boolean;
+	/** Heading shown above the metadata block. Default: `'Page metadata'`. */
+	metadataHeading?: string;
+	/** Heading shown above the JSON-LD block. Default: `'JSON-LD'`. */
+	jsonLdHeading?: string;
+};
+type CreateCollectionPageExportsArgs<S extends string = "pages"> = {
+	config: Promise<SanitizedConfig>;
+	/**
+	* Defaults to `'pages'`. The collection slug whose documents the
+	* page route renders.
+	*/
+	slug?: S;
+	/**
+	* The next-intl `defineRouting({...})` result from the host's
+	* `i18n/routing.ts`. Drives locale validation, URL building,
+	* hreflang alternates, and the language switcher.
+	*/
+	routing: PageRouting;
+	/**
+	* The host's Payload importMap. The lib uses this to resolve
+	* the collection's `custom.path` (the page renderer module) and
+	* the live-preview listener. Pass `import { importMap } from
+	* '@/app/(payload)/admin/importMap.js'` from the host's page
+	* file. Default: `{}` — the page renders without a live-preview
+	* listener and uses the lib's registered `custom.path` for the
+	* collection renderer (which requires its key to be in the
+	* supplied importMap).
+	*/
+	importMap?: ImportMap;
+	/**
+	* Optional custom path pointing at the host's render module for
+	* the collection. Overrides the lib's registered `custom.path`
+	* (which defaults to `PAGES_RENDER_PATH`). Use this when you've
+	* defined your own Server Component for the collection.
+	*/
+	renderPath?: string;
+};
+type CreateCollectionPageExportsDeps<S extends string> = {
+	/**
+	* Host's `getServerSideURL()` (returns the absolute site URL).
+	*/
+	getServerSideURL: () => string;
+	/**
+	* Host's `generateMeta({ doc, url, type, locale })` (returns Next.js
+	* `Metadata`). The `doc` is the host's typed collection document
+	* (e.g. `Post` for the posts collection, `Page` for pages) with
+	* localized fields already resolved for the active locale. Read
+	* `doc.title` directly as a string — no locale-lookup needed.
+	*/
+	generateMeta: (args: {
+		doc: DataFromCollectionSlug<S> | null;
+		url: string;
+		type: "website" | "article";
+		locale: string;
+	}) => Promise<Metadata>;
+	/**
+	* Override the metadata type passed to `generateMeta` and the
+	* JSON-LD entry default. Defaults to `'article'` for the
+	* `posts` collection, `'website'` everywhere else. Hosts that
+	* want to opt out (e.g. treat a Post like a WebPage) pass
+	* `'website'` explicitly here.
+	*/
+	metadataType?: "website" | "article";
+	/**
+	* Optional showcase configuration. When `enabled: true`, the
+	* default page renders inside a `<PageShowcase>` sidebar that
+	* surfaces the page's metadata, JSON-LD, and a language
+	* switcher — useful for demos and CMS previews. Default: off.
+	*/
+	showcase?: ShowcaseOptions;
+	/**
+	* Optional content injected after the rendered doc body when the
+	* page is the home route (slug = `''`). The lib calls the
+	* function with the resolved locale and the current doc (or
+	* `null` if no home doc exists). Hosts that want the home to
+	* surface additional content — recent pages, recent posts,
+	* navigation — pass a function here. The return value is
+	* rendered as a sibling of the lib's doc body inside the page
+	* (and inside the showcase's main column when showcase is on).
+	*/
+	homeExtras?: (args: {
+		locale: string;
+		doc: DataFromCollectionSlug<S> | null;
+	}) => ReactNode | Promise<ReactNode>;
+};
+/**
+* Build a Pages (or any collection) page route's exports:
+* `default` (the Page Server Component), `generateMetadata`,
+* `generateStaticParams`, and `generateSitemap`.
+*
+* Designed for a next-intl layout: the page lives at
+* `app/(frontend)/[locale]/[...slug]/page.tsx`. The catch-all slug
+* handles both the home route (slug=[]) and any other doc. The lib
+* reads `params.locale` and `params.slug` (string[]), validates
+* the locale against `routing.locales`, fetches the doc, generates
+* metadata + JSON-LD + hreflang alternates, and renders the
+* resolved output.
+*
+* The host's `next-intl/routing` config is the single source of
+* truth for the locale list and URL shape.
+*
+*   // app/(frontend)/[locale]/[...slug]/page.tsx
+*   import { routing } from '@/i18n/routing'
+*   import { createCollectionPageExports } from '@justanarthur/payload-www/render-pages'
+*
+*   const { default: Page, generateMetadata, generateStaticParams } =
+*     createCollectionPageExports(
+*       { config: configPromise, routing },
+*       { getServerSideURL, generateMeta, showcase: { enabled: true } }
+*     )
+*
+*   { generateMetadata, generateStaticParams }
+*   Page
+*/
+declare function createCollectionPageExports<S extends string = "pages">({ slug, config: configPromise, routing, importMap: importMapArg, renderPath }: CreateCollectionPageExportsArgs<S>, deps: CreateCollectionPageExportsDeps<S>, options?: MetadataOptions): {
+	default: (props: {
+		params: Promise<{
+			locale?: string;
+			slug?: string[];
+		}>;
+		searchParams?: Promise<Record<string, string | string[] | undefined>>;
+	}) => Promise<ReactElement>;
+	generateMetadata: (props: {
+		params: Promise<{
+			locale?: string;
+			slug?: string[];
+		}>;
+	}) => Promise<Metadata>;
+	generateStaticParams: () => Promise<Array<{
+		slug?: string[];
+		locale: string;
+	}>>;
+	generateSitemap: () => Promise<MetadataRoute.Sitemap>;
+	generateJsonLd: (slugSegments: string[], doc: DataFromCollectionSlug<S>, locale: string) => Promise<JsonLdOutput[]>;
+};
+declare function addCollectionsToSitemap(exports: Array<{
+	default: () => Promise<MetadataRoute.Sitemap>;
+	generateSitemap: () => Promise<MetadataRoute.Sitemap>;
+}>): {
+	default: () => Promise<MetadataRoute.Sitemap>;
+	generateSitemap: () => Promise<MetadataRoute.Sitemap>;
+};
+import { ImportMap as ImportMap2, SanitizedConfig as SanitizedConfig2 } from "payload";
+import { HTMLAttributes, ReactElement as ReactElement2, ReactNode as ReactNode2 } from "react";
+type CreateRootLayoutProvidersArgs = {
+	children: ReactNode2;
+	locale: string;
+	/** Messages for the active locale — hosts pass these into
+	* `NextIntlClientProvider`. The lib fetches them once per request
+	* and exposes them here so the host doesn't have to. */
+	messages: Record<string, any>;
+	/** Whether Next.js draft mode is currently active. Hosts typically
+	* pass this to `<AdminBar preview={draftMode} />`. */
+	draftMode: boolean;
+};
+type CreateRootLayoutExportsArgs = {
+	/** Payload config promise — same shape `createCollectionPageExports` uses. */
+	config: Promise<SanitizedConfig2>;
+	/** next-intl routing config (locales + defaultLocale + localePrefix).
+	* Same `PageRouting` shape the rest of the lib uses. */
+	routing: PageRouting;
+	/**
+	* The host's Payload importMap. The lib uses this to resolve
+	* header / footer globals' `custom.path` entries through
+	* `renderGlobalModule`. Pass `import { importMap } from
+	* '@/app/(payload)/admin/importMap.js'` (or equivalent path) from
+	* the host's layout file. Default: `{}` — header/footer globals
+	* with `custom.path` set won't render unless the matching entry
+	* is in the supplied importMap.
+	*/
+	importMap?: ImportMap2;
+	/**
+	* Single composition point for the entire provider tree —
+	* AdminBar, NextIntlClientProvider, theme, analytics, etc.
+	* Receives `draftMode` so the host can render `<AdminBar>` here
+	* without re-reading from `next/headers` themselves.
+	*
+	* Default: identity (`({ children }) => children`) — wraps nothing.
+	*/
+	providers?: (args: CreateRootLayoutProvidersArgs) => ReactNode2;
+	/**
+	* Optional content rendered inside `<head>`. Hosts drop favicons,
+	* `<link rel>` tags, theme initialization, etc.
+	*
+	* Default: no extra head content (lib doesn't ship favicons —
+	* that's host content).
+	*/
+	head?: () => ReactNode2;
+	/**
+	* Optional `<html>` attribute overrides. The lib already applies
+	* `lang={locale}` and `suppressHydrationWarning` — host additions
+	* are merged on top.
+	*/
+	htmlAttrs?: (locale: string) => HTMLAttributes<HTMLHtmlElement>;
+};
+type CreateRootLayoutExportsReturn = {
+	/** Default for `app/(frontend)/[locale]/layout.tsx`. */
+	default: (props: {
+		children: ReactNode2;
+		params: Promise<{
+			locale: string;
+		}>;
+	}) => Promise<ReactElement2>;
+	/** Pre-render every locale at build time. */
+	generateStaticParams: () => Array<{
+		locale: string;
+	}>;
+};
+/**
+* Build the lib's root layout exports. Renders:
+*
+*   <html {htmlAttrs}>
+*     <head>
+*       {head?.()}
+*     </head>
+*     <body>
+*       {providers({ children: (
+*         <Header data={...} locale={...} />
+*         {children}
+*         <Footer data={...} locale={...} />
+*       ), locale, messages, draftMode })}
+*     </body>
+*   </html>
+*
+* Header and Footer are fetched per-locale via the lib's
+* `queryGlobal` and rendered through their globals' `custom.path`
+* — the same mechanism pages/posts use. Hosts override visuals by
+* setting a different `renderPath` on the global via
+* `createHeaderGlobal({ renderPath })` / `createFooterGlobal({ ... })`.
+*
+* Usage — minimal:
+*
+*   // app/(frontend)/[locale]/layout.tsx
+*   import { createRootLayoutExports } from '@justanarthur/payload-www/render-pages'
+*   import { NextIntlClientProvider } from 'next-intl'
+*   import { AdminBar } from '@justanarthur/payload-www/render-components'
+*   import { routing } from '@/i18n/routing'
+*   import configPromise from '@payload-config'
+*
+*   const { default: RootLayout, generateStaticParams } = createRootLayoutExports({
+*     config: configPromise,
+*     routing,
+*     providers: ({ children, locale, messages, draftMode }) => (
+*       <>
+*         <AdminBar preview={draftMode} />
+*         <NextIntlClientProvider locale={locale} messages={messages}>
+*           {children}
+*         </NextIntlClientProvider>
+*       </>
+*     ),
+*     head: () => <link href="/favicon.ico" rel="icon" sizes="32x32" />
+*   })
+*
+*   { generateStaticParams }
+*   RootLayout
+*/
+declare function createRootLayoutExports(args: CreateRootLayoutExportsArgs): CreateRootLayoutExportsReturn;
+import { ImportMap as ImportMap3, SanitizedConfig as SanitizedConfig3 } from "payload";
+import { ReactElement as ReactElement3 } from "react";
+type CreateStaticPageExportsArgs = {
+	/**
+	* The `kind` discriminator to fetch from the `staticPages`
+	* collection. Default: `'not-found'`. The factory fetches the
+	* row where `kind === {kind}` and renders its `blocks` via
+	* `PagesPage` (the same component the catch-all dynamic route
+	* uses).
+	*/
+	kind?: string;
+	/**
+	* Payload config promise (same shape as `createCollectionPageExports`).
+	*/
+	config: Promise<SanitizedConfig3>;
+	/**
+	* Host's Payload importMap. Same purpose as the Pages factory.
+	* Default: `{}`.
+	*/
+	importMap?: ImportMap3;
+};
+/**
+* Build a static page's default — designed for Next.js
+* `not-found.tsx` / `error.tsx` (and similar) route files. Static
+* pages are addressed by a `kind` discriminator, not a slug, so
+* they don't need metadata, sitemap, or static-params plumbing.
+*
+* Per Next.js docs, not-found/error components receive **no
+* props**. The active locale is read via `getLocale()` from
+* `next-intl/server`, which reads from the request config
+* populated by middleware from the `[locale]` URL segment (the
+* host's `i18n/request.ts` handles invalid-locale fallback
+* before this returns).
+*
+*   // app/(frontend)/[locale]/not-found.tsx
+*   import configPromise from '@payload-config'
+*   import { createStaticPageExports } from '@justanarthur/payload-www/render-pages'
+*   import { importMap } from '@/app/(payload)/admin/importMap.js'
+*
+*   const { default: NotFound } = createStaticPageExports({
+*     config: configPromise,
+*     importMap,
+*   })
+*   NotFound
+*
+*   // app/(frontend)/[locale]/server-error.tsx
+*   const { default: ServerError } = createStaticPageExports({
+*     kind: 'server-error',
+*     config: configPromise,
+*     importMap,
+*   })
+*   ServerError
+*/
+declare function createStaticPageExports({ kind, config: configPromise, importMap: importMapArg }: CreateStaticPageExportsArgs): {
+	default: () => Promise<ReactElement3>;
+};
+import { Metadata as Metadata2 } from "next";
+import { ReactElement as ReactElement4, ReactNode as ReactNode3 } from "react";
+type PageShowcaseProps = {
+	/** The lib-rendered page body (RenderBlocks output + JSON-LD scripts). */
+	children: ReactNode3;
+	/**
+	* The Next.js `Metadata` object resolved by `createCollectionPageExports`'s
+	* `generateMetadata`. The showcase renders the title, description,
+	* Open Graph, and Twitter Card entries as a labeled list.
+	*/
+	metadata: Metadata2;
+	/**
+	* The JSON-LD entries resolved by the lib. Rendered as `<pre>`
+	* blocks inside a `<details>` element so visitors can see the
+	* schema.org payload without it being a wall of JSON.
+	*/
+	jsonLd: Array<{
+		id: string;
+		schema: Record<string, unknown>;
+	}>;
+	/**
+	* The `<LocaleSwitcher>` element the lib built from the page's
+	* hreflang alternates. Mounted at the top of the sidebar.
+	*/
+	localeSwitcher: ReactNode3;
+	/** Heading above the metadata block. Default: `'Page metadata'`. */
+	metadataHeading?: string;
+	/** Heading above the JSON-LD block. Default: `'JSON-LD'`. */
+	jsonLdHeading?: string;
+};
+/**
+* Two-column showcase layout that surfaces the page's metadata,
+* JSON-LD, and language switcher alongside the rendered body. Used
+* by the lib's `createCollectionPageExports` when the host passes
+* `showcase: { enabled: true }`. The default render is the bare
+* doc body + JSON-LD scripts (no sidebar).
+*
+* The layout is intentionally minimal — a `<div class="page-showcase">`
+* with `main` + `aside` columns, no styles. Hosts that want a fancier
+* layout override via their own CSS.
+*/
+declare function PageShowcase({ children, metadata, jsonLd, localeSwitcher, metadataHeading, jsonLdHeading }: PageShowcaseProps): ReactElement4;
+import { ReactElement as ReactElement5 } from "react";
+import { SanitizedConfig as SanitizedConfig4 } from "payload";
+type PagesPageProps = {
+	/**
+	* The resolved page document. The host's `[slug]/page.tsx` route
+	* handler is responsible for fetching the doc (via Payload's
+	* `getPayload` or via the lib's `createCollectionPageExports`'s
+	* `generateMetadata` helper). This component just renders the
+	* visual body.
+	*/
+	doc: Record<string, any> | null;
+	/**
+	* Resolved locale string (already validated upstream by the host's
+	* `[locale]` route segment).
+	*/
+	locale: string;
+	/**
+	* Block components keyed by `blockType`. The host passes the same
+	* `importMap` it uses everywhere else; the lib's `RenderBlocks`
+	* resolves each block against the map.
+	*/
+	importMap: Record<string, unknown>;
+	config: SanitizedConfig4;
+};
+/**
+* Default visual body for the Pages collection. Renders the doc's
+* `blocks` field via the lib's `RenderBlocks`. Hosts can replace
+* this by setting a different `custom.path` on their own Pages
+* collection (via the lib's `createPagesCollection` factory) and
+* pointing it at their own Server Component.
+*/
+declare function PagesPage({ doc,...props }: PagesPageProps): Promise<ReactElement5>;
+import { ReactElement as ReactElement6 } from "react";
+type PostsPageProps = {
+	/**
+	* The resolved post document. The host's `/blog/[...slug]/page.tsx`
+	* route handler is responsible for fetching the doc (via Payload's
+	* `getPayload` or via the lib's `createCollectionPageExports`'s
+	* `generateMetadata` helper). This component just renders the
+	* visual body.
+	*/
+	doc: Record<string, any> | null;
+	/**
+	* Resolved locale string (already validated upstream by the host's
+	* `[locale]` route segment). Unused by this default render — kept
+	* on the signature so hosts can swap in their own component
+	* without changing the importMap entry.
+	*/
+	locale: string;
+	/**
+	* Payload's generated importMap. Reserved for hosts that want to
+	* extend this component with custom Lexical converters via the
+	* `RichText` `converters` prop. Not consumed by the default render.
+	*/
+	importMap: Record<string, unknown>;
+};
+/**
+* Default visual body for the Posts collection. Renders the doc's
+* `title`, optional `excerpt`, and `content` (Lexical richText)
+* via Payload's official `<RichText>` component.
+*
+* Hosts can replace this by setting a different `custom.path` on
+* their own Posts collection (via the lib's `createPostsCollection`
+* factory) and pointing it at their own Server Component.
+*
+* The lib's `<RichText>` import is the client-safe React renderer
+* from `@payloadcms/richtext-lexical/react` — no client component
+* here. The component serializes on the server.
+*/
+declare function PostsPage({ doc, locale, importMap: _importMap }: PostsPageProps): Promise<ReactElement6>;
+import { ReactElement as ReactElement7 } from "react";
+type HeaderPageProps = {
+	/** The resolved Header global document. `null` if the host hasn't
+	* created a Header yet. */
+	data: Record<string, any> | null;
+	/**
+	* Resolved locale string. The default header visual uses this for
+	* per-locale labels via next-intl (if the host has it wired). The
+	* default ships without a label dictionary — the host can override
+	* by setting a different `custom.path` on the header global.
+	*/
+	locale: string;
+};
+/**
+* Default visual for the `header` global. Renders the header's
+* `nav` blocks (a flat list of `navItem` and `navColumn` blocks) as
+* a simple `<nav>` element.
+*
+* Hosts can replace this visual by setting a different `custom.path`
+* on their own header global (via the lib's `createHeaderGlobal`
+* factory).
+*/
+declare function HeaderPage({ data, locale: _locale }: HeaderPageProps): ReactElement7;
+import { ReactElement as ReactElement8 } from "react";
+type FooterPageProps = {
+	/** The resolved Footer global document. `null` if the host hasn't
+	* created a Footer yet. */
+	data: Record<string, any> | null;
+	locale: string;
+};
+/**
+* Default visual for the `footer` global. Renders the footer's
+* `nav` blocks (a flat list of `navItem` and `navColumn` blocks)
+* as a simple `<footer>` element.
+*
+* Hosts can replace this visual by setting a different `custom.path`
+* on their own footer global (via the lib's `createFooterGlobal`
+* factory).
+*/
+declare function FooterPage({ data, locale: _locale }: FooterPageProps): ReactElement8;
+declare const PageShowcase2: typeof PageShowcase;
+declare const _default: {
+	addCollectionsToSitemap: typeof addCollectionsToSitemap;
+	createCollectionPageExports: typeof createCollectionPageExports;
+	createRootLayoutExports: typeof createRootLayoutExports;
+	createStaticPageExports: typeof createStaticPageExports;
+	HeaderPage: typeof HeaderPage;
+	FooterPage: typeof FooterPage;
+	PagesPage: typeof PagesPage;
+	PostsPage: typeof PostsPage;
+	PageShowcase2: typeof PageShowcase;
+};
+export { _default as default, createStaticPageExports, createRootLayoutExports, createCollectionPageExports, addCollectionsToSitemap, ShowcaseOptions, PostsPage, PagesPage, PageShowcaseProps, PageShowcase2 as PageShowcase, PageRouting, MetadataOptions, JsonLdOutput, JsonLdEntry, HeaderPage, FooterPage, CreateStaticPageExportsArgs, CreateRootLayoutProvidersArgs, CreateRootLayoutExportsReturn, CreateRootLayoutExportsArgs, CreateCollectionPageExportsDeps, CreateCollectionPageExportsArgs };