@bison-lab/payload-core 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# `@bison-lab/payload-core`
+
+Site-agnostic Payload CMS configuration for Bison Lab sites. Today: the SEO
+tab on a collection and the metadata reader for the pages it describes. The
+rest of the shared CMS layer (access matrix, collection factories, slug field)
+joins it here as it is extracted.
+
+```bash
+pnpm add @bison-lab/payload-core @payloadcms/plugin-seo
+```
+
+Peers: `payload` and `@payloadcms/plugin-seo`. Pin the plugin to the same
+version as `payload`; Payload releases them in lockstep.
+
+## Two entry points, and why
+
+| Import                             | Contents                                                                       | Runs where                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| `@bison-lab/payload-core`          | `seoPlugin`, `noIndexField`, `SHARE_IMAGE_SIZE`, title and text helpers, types | Node. What `payload.config.ts` imports; it loads the plugin.    |
+| `@bison-lab/payload-core/metadata` | `pageMetadata`, the title helpers, the same types                              | Server. What a page route imports; it does not load the plugin. |
+
+## What editors get
+
+An **SEO** tab beside the page's **Content** tab, never below the block
+editor: an overview with character counts, meta title and description with
+Generate buttons, a share image from the media collection with its own
+Generate button when the site can name an image already on the page, a
+search-result preview, and a **Hide this page from search engines** switch,
+off by default.
+
+## Wiring a site
+
+**1. Configure the plugin.** Every string it generates comes from here, so
+the site spells its name and its URL scheme once.
+
+```ts
+// payload.config.ts
+import { firstImageIn, seoPlugin } from "@bison-lab/payload-core";
+import type { Page } from "@/payload-types";
+
+export default buildConfig({
+  plugins: [
+    seoPlugin<Page>({
+      siteName: "Acme Clinics",
+      urlFor: (doc) => (doc.slug ? absoluteUrl(pagePath(doc.slug)) : undefined),
+      describeFrom: (doc) => doc.hero?.[0]?.body,
+      imageFor: (doc) =>
+        firstImageIn([...(doc.hero ?? []), ...(doc.layout ?? [])]),
+    }),
+  ],
+});
+```
+
+`collections` defaults to `['pages']` and `uploadsCollection` to `'media'`.
+`urlFor` answering `undefined` leaves the preview empty rather than pointing
+it at the home page while the slug is still blank. `describeFrom` and
+`imageFor` are optional; without them those Generate buttons fill in nothing
+(the image button does not appear at all).
+
+**2. Cut the share rendition.** Add `SHARE_IMAGE_SIZE` to the upload
+collection so every image gets a 1200x630 card:
+
+```ts
+import { SHARE_IMAGE_SIZE } from "@bison-lab/payload-core";
+
+export const Media: CollectionConfig = {
+  slug: "media",
+  upload: { imageSizes: [SHARE_IMAGE_SIZE] },
+  fields: [{ name: "alt", type: "text", required: true }],
+};
+```
+
+Then `payload generate:types`, `payload generate:importmap` (the plugin's
+admin components resolve by string key from the site's import map) and
+`payload migrate:create`.
+
+**3. Build the site's title template from the same helper.** Next applies
+`title.template` to `<title>` alone, and `pageMetadata` needs the completed
+title for Open Graph, so both read one spelling:
+
+```ts
+// app/layout.tsx
+import { titleTemplate } from "@bison-lab/payload-core/metadata";
+
+export const metadata: Metadata = {
+  title: { default: SITE_NAME, template: titleTemplate(SITE_NAME) },
+};
+```
+
+**4. Read the tab in the page route.**
+
+```ts
+// app/[...slug]/page.tsx
+import { pageMetadata } from "@bison-lab/payload-core/metadata";
+
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const page = await getPage(params);
+  if (!page) return {};
+  return pageMetadata(page, {
+    siteName: SITE_NAME,
+    canonical: absoluteUrl(pagePath(page.slug)),
+    absoluteUrl,
+  });
+}
+```
+
+`pageMetadata` returns `<title>`, description, canonical, Open Graph and
+Twitter with the share image (falling back to the original file when the
+rendition is missing), and `noindex, nofollow` when the page is hidden. A
+written meta title is `absolute`, so the layout's template does not append
+the site name twice. Fields the editor left empty are omitted rather than
+set to `undefined`, so the layout's own description and default share image
+carry through Next's metadata merge.
+
+The sitemap is the site's: filter `meta.noIndex` out of it.
+
+## No generated types
+
+The package cannot import a site's `payload-types`, so the shapes it reads
+(`SeoMeta`, `SeoImageDoc`, `SeoPage`) are hand-written and structural. A
+generated `Page` and `Media` are assignable to them; nothing carries an index
+signature, since an interface will not assign to a type that has one.
+
+## Changing a field
+
+`noIndexField` and the plugin's own fields are columns in every consuming
+site. A change to them is a schema change: say "run `payload migrate:create`"
+in the changeset.

package/dist/index.d.mts

@@ -0,0 +1,106 @@
+import { a as SeoImageSize, i as SeoImageDoc, n as titleTemplate, o as SeoImageValue, r as MediaId, s as SeoMeta, t as documentTitle } from "./title-Wut0nzJQ.mjs";
+import { CheckboxField, CollectionSlug, Plugin, UploadCollectionSlug } from "payload";
+
+//#region src/seo/plugin.d.ts
+/**
+ * What the plugin reads off a document: its title, for the generated meta
+ * title. The site's generated `Page` is assignable to this; the `urlFor`,
+ * `describeFrom` and `imageFor` callbacks read the rest, typed as the site
+ * chooses through `TDoc`.
+ */
+interface SeoDoc {
+  title?: string | null;
+}
+interface SeoPluginOptions<TDoc extends SeoDoc = SeoDoc> {
+  /** Appended to every generated title: `<page title> | <siteName>`. */
+  siteName: string;
+  /**
+   * The absolute public URL of a document from the form's data, for the
+   * search-result preview and the Generate button beside it. `undefined`
+   * when the document has no address yet (a slug not typed), which leaves
+   * the preview empty rather than pointing at the home page.
+   */
+  urlFor: (doc: TDoc) => string | undefined;
+  /**
+   * Prose to cut a generated description from, the first plain-text field a
+   * page always has near the top (a hero's body, say). Cut at a word near
+   * 155 characters. Without it the Generate button fills in nothing.
+   */
+  describeFrom?: (doc: TDoc) => string | null | undefined;
+  /**
+   * An image already on the page, for the Meta Image Generate button, so an
+   * editor need not upload a second copy of the hero picture. `firstImageIn`
+   * walks block rows for one. The upload chooser stays, so any other media
+   * row can still be picked.
+   */
+  imageFor?: (doc: TDoc) => MediaId | null | undefined;
+  /** Collections that get the SEO tab. Default `['pages']`. */
+  collections?: CollectionSlug[];
+  /** The upload collection the meta image comes from. Default `'media'`. */
+  uploadsCollection?: UploadCollectionSlug;
+}
+/**
+ * `@payloadcms/plugin-seo` configured the Bison Lab way: an SEO tab beside a
+ * Content tab (never below the block editor), holding the overview with its
+ * character counts, meta title, description and image with Generate buttons,
+ * the search-result preview, and the `noIndex` switch.
+ *
+ * Every string the tab generates comes from the options, so a site spells
+ * its name and its URL scheme once. Pin `@payloadcms/plugin-seo` to the same
+ * version as `payload` in the site; the plugin's admin components are
+ * resolved from the site's import map, so run `payload generate:importmap`
+ * after adding it.
+ */
+declare function seoPlugin<TDoc extends SeoDoc = SeoDoc>({
+  siteName,
+  urlFor,
+  describeFrom,
+  imageFor,
+  collections,
+  uploadsCollection
+}: SeoPluginOptions<TDoc>): Plugin;
+/**
+ * The first image among some block rows, as a media id, for `imageFor`. Each
+ * row is checked for `field` holding either a bare id or a populated upload
+ * document; rows without one are skipped. Pass the page's hero and layout
+ * together (`[...doc.hero, ...doc.layout]`) to search in reading order.
+ */
+declare function firstImageIn(blocks: unknown, field?: string): MediaId | undefined;
+//#endregion
+//#region src/seo/fields.d.ts
+/**
+ * The index switch, last in the SEO tab. Off by default: a page is public
+ * unless an editor says otherwise. `pageMetadata` turns it into
+ * `noindex, nofollow`; a site's sitemap should filter on it too.
+ */
+declare const noIndexField: CheckboxField;
+//#endregion
+//#region src/seo/share-image.d.ts
+/**
+ * The rendition a media collection cuts for social share cards: 1.91:1 at the
+ * size Open Graph consumers ask for, cropped to shape rather than letterboxed
+ * so a portrait upload still fills the card. Add it to the upload
+ * collection's `imageSizes`; `pageMetadata` reads `sizes.share` off a page's
+ * meta image and falls back to the original for a file uploaded before the
+ * size existed, or one too small to cut (Payload does not upscale).
+ */
+declare const SHARE_IMAGE_SIZE: {
+  name: string;
+  width: number;
+  height: number;
+  position: string;
+};
+//#endregion
+//#region src/seo/text.d.ts
+/** The length a search result shows of a description before it is cut. */
+declare const DESCRIPTION_LENGTH = 155;
+/**
+ * Prose cut to `max` characters at a word, with an ellipsis, so a generated
+ * description does not end mid-syllable. Text that fits is returned trimmed
+ * and whole. A first word longer than `max` is cut mid-word, since there is
+ * no boundary to cut at.
+ */
+declare function truncateAtWord(text: string, max?: number): string;
+//#endregion
+export { DESCRIPTION_LENGTH, type MediaId, SHARE_IMAGE_SIZE, type SeoDoc, type SeoImageDoc, type SeoImageSize, type SeoImageValue, type SeoMeta, type SeoPluginOptions, documentTitle, firstImageIn, noIndexField, seoPlugin, titleTemplate, truncateAtWord };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/seo/plugin.ts","../src/seo/fields.ts","../src/seo/share-image.ts","../src/seo/text.ts"],"mappings":";;;;;;AAoBA;;;;UAAiB,MAAA;EACf,KAAA;AAAA;AAAA,UAGe,gBAAA,cAA8B,MAAA,GAAS,MAAA;EAAT;EAE7C,QAAA;EAOc;;;;;;EAAd,MAAA,GAAS,GAAA,EAAK,IAAA;EAiB0B;;;;;EAXxC,YAAA,IAAgB,GAAA,EAAK,IAAA;EANP;;;;;;EAad,QAAA,IAAY,GAAA,EAAK,IAAA,KAAS,OAAA;EAAd;EAEZ,WAAA,GAAc,cAAA;EAAd;EAEA,iBAAA,GAAoB,oBAAA;AAAA;;;;AAetB;;;;;;;;;iBAAgB,SAAA,cAAuB,MAAA,GAAS,MAAA,CAAA,CAAA;EAC9C,QAAA;EACA,MAAA;EACA,YAAA;EACA,QAAA;EACA,WAAA;EACA;AAAA,GACC,gBAAA,CAAiB,IAAA,IAAQ,MAAA;;;;;;;iBA6BZ,YAAA,CACd,MAAA,WACA,KAAA,YACC,OAAA;;;;;;AApFH;;cCba,YAAA,EAAc,aAAA;;;;;;;ADa3B;;;;cEVa,gBAAA;;;;;;;;;cCTA,kBAAA;;;AHmBb;;;;iBGXgB,cAAA,CAAe,IAAA,UAAc,GAAA"}

package/dist/index.mjs

@@ -0,0 +1,81 @@
+import { n as documentTitle, r as titleTemplate, t as SHARE_IMAGE_SIZE } from "./share-image-C4ILz4p2.mjs";
+import { seoPlugin as seoPlugin$1 } from "@payloadcms/plugin-seo";
+//#region src/seo/fields.ts
+/**
+* The index switch, last in the SEO tab. Off by default: a page is public
+* unless an editor says otherwise. `pageMetadata` turns it into
+* `noindex, nofollow`; a site's sitemap should filter on it too.
+*/
+const noIndexField = {
+	name: "noIndex",
+	type: "checkbox",
+	label: "Hide this page from search engines",
+	defaultValue: false,
+	admin: { description: "Search engines will not list this page and the sitemap will leave it out. Anyone with the link can still open it." }
+};
+//#endregion
+//#region src/seo/text.ts
+/** The length a search result shows of a description before it is cut. */
+const DESCRIPTION_LENGTH = 155;
+/**
+* Prose cut to `max` characters at a word, with an ellipsis, so a generated
+* description does not end mid-syllable. Text that fits is returned trimmed
+* and whole. A first word longer than `max` is cut mid-word, since there is
+* no boundary to cut at.
+*/
+function truncateAtWord(text, max = 155) {
+	const trimmed = text.trim();
+	if (trimmed.length <= max) return trimmed;
+	const cut = trimmed.slice(0, max);
+	const lastSpace = cut.lastIndexOf(" ");
+	return `${lastSpace > 0 ? cut.slice(0, lastSpace) : cut}…`;
+}
+//#endregion
+//#region src/seo/plugin.ts
+/**
+* `@payloadcms/plugin-seo` configured the Bison Lab way: an SEO tab beside a
+* Content tab (never below the block editor), holding the overview with its
+* character counts, meta title, description and image with Generate buttons,
+* the search-result preview, and the `noIndex` switch.
+*
+* Every string the tab generates comes from the options, so a site spells
+* its name and its URL scheme once. Pin `@payloadcms/plugin-seo` to the same
+* version as `payload` in the site; the plugin's admin components are
+* resolved from the site's import map, so run `payload generate:importmap`
+* after adding it.
+*/
+function seoPlugin({ siteName, urlFor, describeFrom, imageFor, collections = ["pages"], uploadsCollection = "media" }) {
+	const generateTitle = ({ doc }) => doc?.title ? documentTitle(siteName, doc.title) : "";
+	const generateDescription = ({ doc }) => truncateAtWord(describeFrom?.(doc) ?? "");
+	const generateURL = ({ doc }) => urlFor(doc) ?? "";
+	const generateImage = imageFor ? ({ doc }) => imageFor(doc) ?? "" : void 0;
+	return seoPlugin$1({
+		collections,
+		uploadsCollection,
+		tabbedUI: true,
+		generateTitle,
+		generateDescription,
+		generateURL,
+		...generateImage ? { generateImage } : {},
+		fields: ({ defaultFields }) => [...defaultFields, noIndexField]
+	});
+}
+/**
+* The first image among some block rows, as a media id, for `imageFor`. Each
+* row is checked for `field` holding either a bare id or a populated upload
+* document; rows without one are skipped. Pass the page's hero and layout
+* together (`[...doc.hero, ...doc.layout]`) to search in reading order.
+*/
+function firstImageIn(blocks, field = "image") {
+	if (!Array.isArray(blocks)) return void 0;
+	for (const block of blocks) {
+		if (typeof block !== "object" || block === null) continue;
+		const value = block[field];
+		const id = typeof value === "object" && value !== null && "id" in value ? value.id : value;
+		if (typeof id === "number" || typeof id === "string" && id !== "") return id;
+	}
+}
+//#endregion
+export { DESCRIPTION_LENGTH, SHARE_IMAGE_SIZE, documentTitle, firstImageIn, noIndexField, seoPlugin, titleTemplate, truncateAtWord };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["payloadSeoPlugin"],"sources":["../src/seo/fields.ts","../src/seo/text.ts","../src/seo/plugin.ts"],"sourcesContent":["import type { CheckboxField } from \"payload\";\n\n/**\n * The index switch, last in the SEO tab. Off by default: a page is public\n * unless an editor says otherwise. `pageMetadata` turns it into\n * `noindex, nofollow`; a site's sitemap should filter on it too.\n */\nexport const noIndexField: CheckboxField = {\n  name: \"noIndex\",\n  type: \"checkbox\",\n  label: \"Hide this page from search engines\",\n  defaultValue: false,\n  admin: {\n    description:\n      \"Search engines will not list this page and the sitemap will leave it out. Anyone with the link can still open it.\",\n  },\n};\n","/** The length a search result shows of a description before it is cut. */\nexport const DESCRIPTION_LENGTH = 155;\n\n/**\n * Prose cut to `max` characters at a word, with an ellipsis, so a generated\n * description does not end mid-syllable. Text that fits is returned trimmed\n * and whole. A first word longer than `max` is cut mid-word, since there is\n * no boundary to cut at.\n */\nexport function truncateAtWord(text: string, max = DESCRIPTION_LENGTH): string {\n  const trimmed = text.trim();\n  if (trimmed.length <= max) return trimmed;\n  const cut = trimmed.slice(0, max);\n  const lastSpace = cut.lastIndexOf(\" \");\n  return `${lastSpace > 0 ? cut.slice(0, lastSpace) : cut}…`;\n}\n","import { seoPlugin as payloadSeoPlugin } from \"@payloadcms/plugin-seo\";\nimport type {\n  GenerateDescription,\n  GenerateImage,\n  GenerateTitle,\n  GenerateURL,\n} from \"@payloadcms/plugin-seo/types\";\nimport type { CollectionSlug, Plugin, UploadCollectionSlug } from \"payload\";\n\nimport { noIndexField } from \"./fields\";\nimport { truncateAtWord } from \"./text\";\nimport { documentTitle } from \"./title\";\nimport type { MediaId } from \"./types\";\n\n/**\n * What the plugin reads off a document: its title, for the generated meta\n * title. The site's generated `Page` is assignable to this; the `urlFor`,\n * `describeFrom` and `imageFor` callbacks read the rest, typed as the site\n * chooses through `TDoc`.\n */\nexport interface SeoDoc {\n  title?: string | null;\n}\n\nexport interface SeoPluginOptions<TDoc extends SeoDoc = SeoDoc> {\n  /** Appended to every generated title: `<page title> | <siteName>`. */\n  siteName: string;\n  /**\n   * The absolute public URL of a document from the form's data, for the\n   * search-result preview and the Generate button beside it. `undefined`\n   * when the document has no address yet (a slug not typed), which leaves\n   * the preview empty rather than pointing at the home page.\n   */\n  urlFor: (doc: TDoc) => string | undefined;\n  /**\n   * Prose to cut a generated description from, the first plain-text field a\n   * page always has near the top (a hero's body, say). Cut at a word near\n   * 155 characters. Without it the Generate button fills in nothing.\n   */\n  describeFrom?: (doc: TDoc) => string | null | undefined;\n  /**\n   * An image already on the page, for the Meta Image Generate button, so an\n   * editor need not upload a second copy of the hero picture. `firstImageIn`\n   * walks block rows for one. The upload chooser stays, so any other media\n   * row can still be picked.\n   */\n  imageFor?: (doc: TDoc) => MediaId | null | undefined;\n  /** Collections that get the SEO tab. Default `['pages']`. */\n  collections?: CollectionSlug[];\n  /** The upload collection the meta image comes from. Default `'media'`. */\n  uploadsCollection?: UploadCollectionSlug;\n}\n\n/**\n * `@payloadcms/plugin-seo` configured the Bison Lab way: an SEO tab beside a\n * Content tab (never below the block editor), holding the overview with its\n * character counts, meta title, description and image with Generate buttons,\n * the search-result preview, and the `noIndex` switch.\n *\n * Every string the tab generates comes from the options, so a site spells\n * its name and its URL scheme once. Pin `@payloadcms/plugin-seo` to the same\n * version as `payload` in the site; the plugin's admin components are\n * resolved from the site's import map, so run `payload generate:importmap`\n * after adding it.\n */\nexport function seoPlugin<TDoc extends SeoDoc = SeoDoc>({\n  siteName,\n  urlFor,\n  describeFrom,\n  imageFor,\n  collections = [\"pages\"],\n  uploadsCollection = \"media\",\n}: SeoPluginOptions<TDoc>): Plugin {\n  const generateTitle: GenerateTitle<TDoc> = ({ doc }) =>\n    doc?.title ? documentTitle(siteName, doc.title) : \"\";\n  const generateDescription: GenerateDescription<TDoc> = ({ doc }) =>\n    truncateAtWord(describeFrom?.(doc) ?? \"\");\n  const generateURL: GenerateURL<TDoc> = ({ doc }) => urlFor(doc) ?? \"\";\n  // Only when the site can name one: the button appears with the function.\n  const generateImage: GenerateImage<TDoc> | undefined = imageFor\n    ? ({ doc }) => imageFor(doc) ?? \"\"\n    : undefined;\n\n  return payloadSeoPlugin({\n    collections,\n    uploadsCollection,\n    tabbedUI: true,\n    generateTitle,\n    generateDescription,\n    generateURL,\n    ...(generateImage ? { generateImage } : {}),\n    fields: ({ defaultFields }) => [...defaultFields, noIndexField],\n  });\n}\n\n/**\n * The first image among some block rows, as a media id, for `imageFor`. Each\n * row is checked for `field` holding either a bare id or a populated upload\n * document; rows without one are skipped. Pass the page's hero and layout\n * together (`[...doc.hero, ...doc.layout]`) to search in reading order.\n */\nexport function firstImageIn(\n  blocks: unknown,\n  field = \"image\",\n): MediaId | undefined {\n  if (!Array.isArray(blocks)) return undefined;\n  for (const block of blocks) {\n    if (typeof block !== \"object\" || block === null) continue;\n    const value = (block as Record<string, unknown>)[field];\n    const id =\n      typeof value === \"object\" && value !== null && \"id\" in value\n        ? (value as { id: unknown }).id\n        : value;\n    if (typeof id === \"number\" || (typeof id === \"string\" && id !== \"\"))\n      return id;\n  }\n  return undefined;\n}\n"],"mappings":";;;;;;;;AAOA,MAAa,eAA8B;CACzC,MAAM;CACN,MAAM;CACN,OAAO;CACP,cAAc;CACd,OAAO,EACL,aACE,qHACH;CACF;;;;ACfD,MAAa,qBAAqB;;;;;;;AAQlC,SAAgB,eAAe,MAAc,MAAA,KAAkC;CAC7E,MAAM,UAAU,KAAK,MAAM;AAC3B,KAAI,QAAQ,UAAU,IAAK,QAAO;CAClC,MAAM,MAAM,QAAQ,MAAM,GAAG,IAAI;CACjC,MAAM,YAAY,IAAI,YAAY,IAAI;AACtC,QAAO,GAAG,YAAY,IAAI,IAAI,MAAM,GAAG,UAAU,GAAG,IAAI;;;;;;;;;;;;;;;;ACmD1D,SAAgB,UAAwC,EACtD,UACA,QACA,cACA,UACA,cAAc,CAAC,QAAQ,EACvB,oBAAoB,WACa;CACjC,MAAM,iBAAsC,EAAE,UAC5C,KAAK,QAAQ,cAAc,UAAU,IAAI,MAAM,GAAG;CACpD,MAAM,uBAAkD,EAAE,UACxD,eAAe,eAAe,IAAI,IAAI,GAAG;CAC3C,MAAM,eAAkC,EAAE,UAAU,OAAO,IAAI,IAAI;CAEnE,MAAM,gBAAiD,YAClD,EAAE,UAAU,SAAS,IAAI,IAAI,KAC9B,KAAA;AAEJ,QAAOA,YAAiB;EACtB;EACA;EACA,UAAU;EACV;EACA;EACA;EACA,GAAI,gBAAgB,EAAE,eAAe,GAAG,EAAE;EAC1C,SAAS,EAAE,oBAAoB,CAAC,GAAG,eAAe,aAAa;EAChE,CAAC;;;;;;;;AASJ,SAAgB,aACd,QACA,QAAQ,SACa;AACrB,KAAI,CAAC,MAAM,QAAQ,OAAO,CAAE,QAAO,KAAA;AACnC,MAAK,MAAM,SAAS,QAAQ;AAC1B,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM;EACjD,MAAM,QAAS,MAAkC;EACjD,MAAM,KACJ,OAAO,UAAU,YAAY,UAAU,QAAQ,QAAQ,QAClD,MAA0B,KAC3B;AACN,MAAI,OAAO,OAAO,YAAa,OAAO,OAAO,YAAY,OAAO,GAC9D,QAAO"}

package/dist/metadata.d.mts

@@ -0,0 +1,70 @@
+import { a as SeoImageSize, i as SeoImageDoc, n as titleTemplate, o as SeoImageValue, r as MediaId, s as SeoMeta, t as documentTitle } from "./title-Wut0nzJQ.mjs";
+
+//#region src/seo/metadata.d.ts
+/** A page as the reader needs it; a site's generated `Page` is assignable. */
+interface SeoPage {
+  title: string;
+  meta?: SeoMeta | null;
+}
+interface PageMetadataOptions {
+  /** The suffix a page without a written meta title gets. */
+  siteName: string;
+  /** This page's absolute URL at the site's own origin. */
+  canonical: string;
+  /** Turns a media file path into an absolute URL; crawlers take no other kind. */
+  absoluteUrl: (path: string) => string;
+  /** The rendition to read off the meta image. Default `SHARE_IMAGE_SIZE.name`. */
+  shareSize?: string;
+}
+interface PageMetadataImage {
+  url: string;
+  width?: number;
+  height?: number;
+  alt?: string;
+}
+/**
+ * The shape `pageMetadata` returns, assignable to Next's `Metadata` without
+ * this package depending on `next`. A written meta title is `absolute` so
+ * the layout's title template does not append the site name a second time;
+ * an unwritten one is the bare page title, which the template completes.
+ * Optional keys are absent rather than `undefined`: Next's merge lets an
+ * `undefined` key override the layout's value instead of inheriting it.
+ */
+interface PageMetadata {
+  title: string | {
+    absolute: string;
+  };
+  description?: string;
+  alternates: {
+    canonical: string;
+  };
+  openGraph: {
+    title: string;
+    description?: string;
+    url: string;
+    images?: PageMetadataImage[];
+  };
+  twitter: {
+    card: "summary_large_image";
+    title: string;
+    description?: string;
+    images?: PageMetadataImage[];
+  };
+  robots?: {
+    index: false;
+    follow: false;
+  };
+}
+/**
+ * Next metadata for a page with the SEO tab: `<title>`, description,
+ * canonical, Open Graph and Twitter with the share image, and
+ * `noindex, nofollow` when the page is hidden. Fields the editor left empty
+ * are left out, so the layout's defaults (a site-wide description, a default
+ * share image) carry through Next's merge. The canonical is always this
+ * site's origin; a page that must canonicalise elsewhere is a redirect, not
+ * a field.
+ */
+declare function pageMetadata(page: SeoPage, options: PageMetadataOptions): PageMetadata;
+//#endregion
+export { type MediaId, type PageMetadata, type PageMetadataImage, type PageMetadataOptions, type SeoImageDoc, type SeoImageSize, type SeoImageValue, type SeoMeta, type SeoPage, documentTitle, pageMetadata, titleTemplate };
+//# sourceMappingURL=metadata.d.mts.map

package/dist/metadata.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.mts","names":[],"sources":["../src/seo/metadata.ts"],"mappings":";;;;UAKiB,OAAA;EACf,KAAA;EACA,IAAA,GAAO,OAAA;AAAA;AAAA,UAGQ,mBAAA;EAJf;EAMA,QAAA;EALO;EAOP,SAAA;EAPc;EASd,WAAA,GAAc,IAAA;EANoB;EAQlC,SAAA;AAAA;AAAA,UAGe,iBAAA;EACf,GAAA;EACA,KAAA;EACA,MAAA;EACA,GAAA;AAAA;;AAJF;;;;;;;UAeiB,YAAA;EACf,KAAA;IAAkB,QAAA;EAAA;EAClB,WAAA;EACA,UAAA;IAAc,SAAA;EAAA;EACd,SAAA;IACE,KAAA;IACA,WAAA;IACA,GAAA;IACA,MAAA,GAAS,iBAAA;EAAA;EAEX,OAAA;IACE,IAAA;IACA,KAAA;IACA,WAAA;IACA,MAAA,GAAS,iBAAA;EAAA;EAEX,MAAA;IAAW,KAAA;IAAc,MAAA;EAAA;AAAA;;;;;AAkC3B;;;;;iBAAgB,YAAA,CACd,IAAA,EAAM,OAAA,EACN,OAAA,EAAS,mBAAA,GACR,YAAA"}

package/dist/metadata.mjs

@@ -0,0 +1,61 @@
+import { n as documentTitle, r as titleTemplate, t as SHARE_IMAGE_SIZE } from "./share-image-C4ILz4p2.mjs";
+//#region src/seo/metadata.ts
+/**
+* The share image as a crawler wants it, or `undefined` when the page has
+* none or the relation came back unpopulated (`depth: 0` upstream). The
+* named rendition is preferred; a file uploaded before that size existed, or
+* too small to cut, has only its original, which is used as is.
+*/
+function shareImage(image, { absoluteUrl, shareSize = SHARE_IMAGE_SIZE.name }) {
+	if (!image || typeof image !== "object") return void 0;
+	const rendition = image.sizes?.[shareSize];
+	const file = rendition?.url ? rendition : image;
+	if (!file.url) return void 0;
+	return {
+		url: absoluteUrl(file.url),
+		...file.width ? { width: file.width } : {},
+		...file.height ? { height: file.height } : {},
+		...image.alt ? { alt: image.alt } : {}
+	};
+}
+/**
+* Next metadata for a page with the SEO tab: `<title>`, description,
+* canonical, Open Graph and Twitter with the share image, and
+* `noindex, nofollow` when the page is hidden. Fields the editor left empty
+* are left out, so the layout's defaults (a site-wide description, a default
+* share image) carry through Next's merge. The canonical is always this
+* site's origin; a page that must canonicalise elsewhere is a redirect, not
+* a field.
+*/
+function pageMetadata(page, options) {
+	const meta = page.meta ?? {};
+	const title = meta.title || documentTitle(options.siteName, page.title);
+	const description = meta.description ? { description: meta.description } : {};
+	const image = shareImage(meta.image, options);
+	const images = image ? { images: [image] } : {};
+	return {
+		title: meta.title ? { absolute: meta.title } : page.title,
+		...description,
+		alternates: { canonical: options.canonical },
+		openGraph: {
+			title,
+			...description,
+			url: options.canonical,
+			...images
+		},
+		twitter: {
+			card: "summary_large_image",
+			title,
+			...description,
+			...images
+		},
+		...meta.noIndex ? { robots: {
+			index: false,
+			follow: false
+		} } : {}
+	};
+}
+//#endregion
+export { documentTitle, pageMetadata, titleTemplate };
+
+//# sourceMappingURL=metadata.mjs.map

package/dist/metadata.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.mjs","names":[],"sources":["../src/seo/metadata.ts"],"sourcesContent":["import { SHARE_IMAGE_SIZE } from \"./share-image\";\nimport { documentTitle } from \"./title\";\nimport type { SeoImageValue, SeoMeta } from \"./types\";\n\n/** A page as the reader needs it; a site's generated `Page` is assignable. */\nexport interface SeoPage {\n  title: string;\n  meta?: SeoMeta | null;\n}\n\nexport interface PageMetadataOptions {\n  /** The suffix a page without a written meta title gets. */\n  siteName: string;\n  /** This page's absolute URL at the site's own origin. */\n  canonical: string;\n  /** Turns a media file path into an absolute URL; crawlers take no other kind. */\n  absoluteUrl: (path: string) => string;\n  /** The rendition to read off the meta image. Default `SHARE_IMAGE_SIZE.name`. */\n  shareSize?: string;\n}\n\nexport interface PageMetadataImage {\n  url: string;\n  width?: number;\n  height?: number;\n  alt?: string;\n}\n\n/**\n * The shape `pageMetadata` returns, assignable to Next's `Metadata` without\n * this package depending on `next`. A written meta title is `absolute` so\n * the layout's title template does not append the site name a second time;\n * an unwritten one is the bare page title, which the template completes.\n * Optional keys are absent rather than `undefined`: Next's merge lets an\n * `undefined` key override the layout's value instead of inheriting it.\n */\nexport interface PageMetadata {\n  title: string | { absolute: string };\n  description?: string;\n  alternates: { canonical: string };\n  openGraph: {\n    title: string;\n    description?: string;\n    url: string;\n    images?: PageMetadataImage[];\n  };\n  twitter: {\n    card: \"summary_large_image\";\n    title: string;\n    description?: string;\n    images?: PageMetadataImage[];\n  };\n  robots?: { index: false; follow: false };\n}\n\n/**\n * The share image as a crawler wants it, or `undefined` when the page has\n * none or the relation came back unpopulated (`depth: 0` upstream). The\n * named rendition is preferred; a file uploaded before that size existed, or\n * too small to cut, has only its original, which is used as is.\n */\nfunction shareImage(\n  image: SeoImageValue,\n  { absoluteUrl, shareSize = SHARE_IMAGE_SIZE.name }: PageMetadataOptions,\n): PageMetadataImage | undefined {\n  if (!image || typeof image !== \"object\") return undefined;\n  const rendition = image.sizes?.[shareSize];\n  const file = rendition?.url ? rendition : image;\n  if (!file.url) return undefined;\n  return {\n    url: absoluteUrl(file.url),\n    ...(file.width ? { width: file.width } : {}),\n    ...(file.height ? { height: file.height } : {}),\n    ...(image.alt ? { alt: image.alt } : {}),\n  };\n}\n\n/**\n * Next metadata for a page with the SEO tab: `<title>`, description,\n * canonical, Open Graph and Twitter with the share image, and\n * `noindex, nofollow` when the page is hidden. Fields the editor left empty\n * are left out, so the layout's defaults (a site-wide description, a default\n * share image) carry through Next's merge. The canonical is always this\n * site's origin; a page that must canonicalise elsewhere is a redirect, not\n * a field.\n */\nexport function pageMetadata(\n  page: SeoPage,\n  options: PageMetadataOptions,\n): PageMetadata {\n  const meta = page.meta ?? {};\n  const title = meta.title || documentTitle(options.siteName, page.title);\n  const description = meta.description ? { description: meta.description } : {};\n  const image = shareImage(meta.image, options);\n  const images = image ? { images: [image] } : {};\n\n  return {\n    title: meta.title ? { absolute: meta.title } : page.title,\n    ...description,\n    alternates: { canonical: options.canonical },\n    openGraph: { title, ...description, url: options.canonical, ...images },\n    twitter: { card: \"summary_large_image\", title, ...description, ...images },\n    // Both off: a page hidden from search should not lend its links weight either.\n    ...(meta.noIndex ? { robots: { index: false, follow: false } } : {}),\n  };\n}\n"],"mappings":";;;;;;;;AA6DA,SAAS,WACP,OACA,EAAE,aAAa,YAAY,iBAAiB,QACb;AAC/B,KAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO,KAAA;CAChD,MAAM,YAAY,MAAM,QAAQ;CAChC,MAAM,OAAO,WAAW,MAAM,YAAY;AAC1C,KAAI,CAAC,KAAK,IAAK,QAAO,KAAA;AACtB,QAAO;EACL,KAAK,YAAY,KAAK,IAAI;EAC1B,GAAI,KAAK,QAAQ,EAAE,OAAO,KAAK,OAAO,GAAG,EAAE;EAC3C,GAAI,KAAK,SAAS,EAAE,QAAQ,KAAK,QAAQ,GAAG,EAAE;EAC9C,GAAI,MAAM,MAAM,EAAE,KAAK,MAAM,KAAK,GAAG,EAAE;EACxC;;;;;;;;;;;AAYH,SAAgB,aACd,MACA,SACc;CACd,MAAM,OAAO,KAAK,QAAQ,EAAE;CAC5B,MAAM,QAAQ,KAAK,SAAS,cAAc,QAAQ,UAAU,KAAK,MAAM;CACvE,MAAM,cAAc,KAAK,cAAc,EAAE,aAAa,KAAK,aAAa,GAAG,EAAE;CAC7E,MAAM,QAAQ,WAAW,KAAK,OAAO,QAAQ;CAC7C,MAAM,SAAS,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE;AAE/C,QAAO;EACL,OAAO,KAAK,QAAQ,EAAE,UAAU,KAAK,OAAO,GAAG,KAAK;EACpD,GAAG;EACH,YAAY,EAAE,WAAW,QAAQ,WAAW;EAC5C,WAAW;GAAE;GAAO,GAAG;GAAa,KAAK,QAAQ;GAAW,GAAG;GAAQ;EACvE,SAAS;GAAE,MAAM;GAAuB;GAAO,GAAG;GAAa,GAAG;GAAQ;EAE1E,GAAI,KAAK,UAAU,EAAE,QAAQ;GAAE,OAAO;GAAO,QAAQ;GAAO,EAAE,GAAG,EAAE;EACpE"}

package/dist/share-image-C4ILz4p2.mjs

@@ -0,0 +1,37 @@
+//#region src/seo/title.ts
+/**
+* A document title from a page title: the one place the `| Site Name` suffix
+* is spelled. The frontend layout's title template, the admin's Generate
+* button and a CMS page's Open Graph title are all built from it, since Next
+* applies a title template to `<title>` alone.
+*/
+function documentTitle(siteName, pageTitle) {
+	return `${pageTitle} | ${siteName}`;
+}
+/**
+* The same format as Next's `title.template` wants it, for the root layout:
+* `%s` is Next's placeholder for the page's own title.
+*/
+function titleTemplate(siteName) {
+	return documentTitle(siteName, "%s");
+}
+//#endregion
+//#region src/seo/share-image.ts
+/**
+* The rendition a media collection cuts for social share cards: 1.91:1 at the
+* size Open Graph consumers ask for, cropped to shape rather than letterboxed
+* so a portrait upload still fills the card. Add it to the upload
+* collection's `imageSizes`; `pageMetadata` reads `sizes.share` off a page's
+* meta image and falls back to the original for a file uploaded before the
+* size existed, or one too small to cut (Payload does not upscale).
+*/
+const SHARE_IMAGE_SIZE = {
+	name: "share",
+	width: 1200,
+	height: 630,
+	position: "centre"
+};
+//#endregion
+export { documentTitle as n, titleTemplate as r, SHARE_IMAGE_SIZE as t };
+
+//# sourceMappingURL=share-image-C4ILz4p2.mjs.map

package/dist/share-image-C4ILz4p2.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-image-C4ILz4p2.mjs","names":[],"sources":["../src/seo/title.ts","../src/seo/share-image.ts"],"sourcesContent":["/**\n * A document title from a page title: the one place the `| Site Name` suffix\n * is spelled. The frontend layout's title template, the admin's Generate\n * button and a CMS page's Open Graph title are all built from it, since Next\n * applies a title template to `<title>` alone.\n */\nexport function documentTitle(siteName: string, pageTitle: string): string {\n  return `${pageTitle} | ${siteName}`;\n}\n\n/**\n * The same format as Next's `title.template` wants it, for the root layout:\n * `%s` is Next's placeholder for the page's own title.\n */\nexport function titleTemplate(siteName: string): string {\n  return documentTitle(siteName, \"%s\");\n}\n","import type { ImageSize } from \"payload\";\n\n/**\n * The rendition a media collection cuts for social share cards: 1.91:1 at the\n * size Open Graph consumers ask for, cropped to shape rather than letterboxed\n * so a portrait upload still fills the card. Add it to the upload\n * collection's `imageSizes`; `pageMetadata` reads `sizes.share` off a page's\n * meta image and falls back to the original for a file uploaded before the\n * size existed, or one too small to cut (Payload does not upscale).\n */\nexport const SHARE_IMAGE_SIZE = {\n  name: \"share\",\n  width: 1200,\n  height: 630,\n  position: \"centre\",\n} satisfies ImageSize;\n"],"mappings":";;;;;;;AAMA,SAAgB,cAAc,UAAkB,WAA2B;AACzE,QAAO,GAAG,UAAU,KAAK;;;;;;AAO3B,SAAgB,cAAc,UAA0B;AACtD,QAAO,cAAc,UAAU,KAAK;;;;;;;;;;;;ACLtC,MAAa,mBAAmB;CAC9B,MAAM;CACN,OAAO;CACP,QAAQ;CACR,UAAU;CACX"}

package/dist/title-Wut0nzJQ.d.mts

@@ -0,0 +1,55 @@
+//#region src/seo/types.d.ts
+/** A media row id as Payload stores it: a number on Postgres, a string on Mongo. */
+type MediaId = number | string;
+/** One rendition under an upload document's `sizes`. */
+interface SeoImageSize {
+  url?: string | null;
+  width?: number | null;
+  height?: number | null;
+}
+/**
+ * The subset of an upload document the metadata reader touches. A site's
+ * generated `Media` is assignable to this whatever else it carries. No index
+ * signature at the top level, for the reason `@bison-lab/payload-blocks`
+ * gives its `MediaDoc` none: an interface will not assign to a type that has
+ * one, and a generated `Media` is always an interface. `sizes` is generated
+ * as an anonymous object type, which does assign to an indexed one.
+ */
+interface SeoImageDoc {
+  url?: string | null;
+  alt?: string | null;
+  width?: number | null;
+  height?: number | null;
+  sizes?: {
+    [name: string]: SeoImageSize | undefined;
+  } | null;
+}
+/** What the `image` field holds before and after `depth` populates it. */
+type SeoImageValue = MediaId | SeoImageDoc | null | undefined;
+/**
+ * The `meta` group the plugin adds to a collection, as a site's generated
+ * `Page['meta']` reads once `payload generate:types` has run.
+ */
+interface SeoMeta {
+  title?: string | null;
+  description?: string | null;
+  image?: SeoImageValue;
+  noIndex?: boolean | null;
+}
+//#endregion
+//#region src/seo/title.d.ts
+/**
+ * A document title from a page title: the one place the `| Site Name` suffix
+ * is spelled. The frontend layout's title template, the admin's Generate
+ * button and a CMS page's Open Graph title are all built from it, since Next
+ * applies a title template to `<title>` alone.
+ */
+declare function documentTitle(siteName: string, pageTitle: string): string;
+/**
+ * The same format as Next's `title.template` wants it, for the root layout:
+ * `%s` is Next's placeholder for the page's own title.
+ */
+declare function titleTemplate(siteName: string): string;
+//#endregion
+export { SeoImageSize as a, SeoImageDoc as i, titleTemplate as n, SeoImageValue as o, MediaId as r, SeoMeta as s, documentTitle as t };
+//# sourceMappingURL=title-Wut0nzJQ.d.mts.map

package/dist/title-Wut0nzJQ.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"title-Wut0nzJQ.d.mts","names":[],"sources":["../src/seo/types.ts","../src/seo/title.ts"],"mappings":";;KACY,OAAA;;UAGK,YAAA;EACf,GAAA;EACA,KAAA;EACA,MAAA;AAAA;;;;;;;;AAWF;UAAiB,WAAA;EACf,GAAA;EACA,GAAA;EACA,KAAA;EACA,MAAA;EACA,KAAA;IAAA,CAAW,IAAA,WAAe,YAAA;EAAA;AAAA;;KAIhB,aAAA,GAAgB,OAAA,GAAU,WAAA;;AAAtC;;;UAMiB,OAAA;EACf,KAAA;EACA,WAAA;EACA,KAAA,GAAQ,aAAA;EACR,OAAA;AAAA;;;;AApCF;;;;;iBCKgB,aAAA,CAAc,QAAA,UAAkB,SAAA;;;;;iBAQhC,aAAA,CAAc,QAAA"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@bison-lab/payload-core",
+  "version": "0.1.0",
+  "description": "Site-agnostic Payload CMS configuration for Bison Lab sites: the SEO tab on a collection and the metadata reader for the pages it describes",
+  "homepage": "https://components.bisonlab.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bison-Lab-LLC/bisonlab-component-library.git",
+    "directory": "packages/payload-core"
+  },
+  "bugs": {
+    "url": "https://github.com/Bison-Lab-LLC/bisonlab-component-library/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    },
+    "./metadata": {
+      "import": "./dist/metadata.mjs",
+      "types": "./dist/metadata.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@payloadcms/plugin-seo": "^3.0.0",
+    "payload": "^3.0.0"
+  },
+  "devDependencies": {
+    "@payloadcms/plugin-seo": "^3.88.0",
+    "payload": "^3.88.0",
+    "tsdown": "^0.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}