@djangocfg/nextjs 2.1.437 → 2.1.439

package/src/og-image/metadata-factory.ts

@@ -0,0 +1,146 @@
+import type { Metadata } from 'next'
+import type { OgSpec } from './types'
+import { resolveOgImage } from './metadata'
+
+/**
+ * Site-wide identity the metadata factory needs. Config-agnostic on purpose —
+ * the package doesn't know about any app's `settings` object, so the consumer
+ * passes these once (typically derived from their own settings module).
+ */
+export interface SiteMetaConfig {
+  /** Brand / app name, e.g. "CMDOP". Used in titles, siteName, alt text. */
+  name: string
+  /** Default description used when a page doesn't supply its own. */
+  description: string
+  /** Absolute site origin, e.g. "https://cmdop.com". Used for canonical/og url. */
+  siteUrl: string
+  /** Ready-made static brand OG image URL (absolute or root-relative). */
+  ogImage: string
+  /** Optional favicon / apple-touch icons forwarded to Metadata.icons. */
+  icons?: Metadata['icons']
+  /** Locales for hreflang alternates. Omit for single-locale sites. */
+  locales?: readonly string[]
+  /** Locale used for x-default hreflang (defaults to "en" or first locale). */
+  defaultLocale?: string
+}
+
+/**
+ * Per-page inputs. Only `title` is really worth setting per page; everything
+ * else falls back to the site config.
+ */
+export interface PageMeta {
+  /** Page title (without the brand suffix). Falls back to the site name. */
+  title?: string
+  /** Page description; falls back to the site description. */
+  description?: string
+  keywords?: string[]
+  /** Current locale, used for canonical + openGraph.locale + alternates. */
+  locale?: string
+  /** Path without locale prefix, e.g. "/skills". '' for home. */
+  path?: string
+  /**
+   * What the OG image should be. Defaults to `'static'` (the brand image).
+   * - `'static'`          brand image from config (default)
+   * - `'dynamic'`         render the page title onto the card
+   * - `{ render: {...} }` render with explicit preset/layout/colors
+   * - `{ image, alt? }`   an exact image URL (e.g. a content screenshot)
+   */
+  og?: OgSpec
+  /** Escape hatch: extra Metadata fields merged last (robots, authors, etc.). */
+  extra?: Metadata
+}
+
+function buildAlternates(
+  config: SiteMetaConfig,
+  path: string,
+  locale: string
+): Metadata['alternates'] {
+  if (!config.locales?.length) {
+    return { canonical: `${config.siteUrl}/${path}`.replace(/\/+$/, '') || config.siteUrl }
+  }
+  const languages: Record<string, string> = {}
+  for (const loc of config.locales) {
+    languages[loc] = `${config.siteUrl}/${loc}${path}`
+  }
+  const xDefault =
+    config.defaultLocale ?? (config.locales.includes('en') ? 'en' : config.locales[0])
+  languages['x-default'] = `${config.siteUrl}/${xDefault}${path}`
+  return { canonical: `${config.siteUrl}/${locale}${path}`, languages }
+}
+
+/**
+ * Builds a complete Next.js `Metadata` from a one-time site config plus per-page
+ * inputs — title-template, description, openGraph, twitter, canonical + hreflang,
+ * icons, and the OG image — so pages only declare what's unique.
+ *
+ * The OG image is chosen by the single `og` field (defaults to the static brand
+ * image). There is exactly one way to do each thing.
+ *
+ *   // app/_core/metadata.ts
+ *   export const createMetadata = makeMetadataFactory({
+ *     name: settings.app.name,
+ *     description: settings.app.description,
+ *     siteUrl: settings.app.siteUrl,
+ *     ogImage: settings.app.media.ogimage,
+ *     icons: { icon: settings.app.media.favicon },
+ *     locales: LOCALES,
+ *   })
+ *
+ *   // landing page — static brand image (default)
+ *   export const metadata = createMetadata({ title: 'Pricing', path: '/pricing' })
+ *   // content page — title rendered onto the card
+ *   export const metadata = createMetadata({ title: post.title, path, og: 'dynamic' })
+ *   // content page with its own image
+ *   export const metadata = createMetadata({ title: p.name, og: { image: p.image } })
+ */
+export function createMetadata(config: SiteMetaConfig, page: PageMeta = {}): Metadata {
+  const title = page.title ?? config.name
+  const description = page.description ?? config.description
+  const locale = page.locale ?? config.defaultLocale ?? 'en'
+  const path = page.path ?? ''
+  const ogUrl = config.locales?.length
+    ? `${config.siteUrl}/${locale}${path}`
+    : `${config.siteUrl}${path}`
+
+  const ogImage = resolveOgImage(page.og ?? 'static', config.ogImage, title)
+
+  const metadata: Metadata = {
+    title,
+    description,
+    keywords: page.keywords,
+    alternates: buildAlternates(config, path, locale),
+    openGraph: {
+      type: 'website',
+      locale,
+      url: ogUrl,
+      siteName: config.name,
+      title,
+      description,
+      ...ogImage.openGraph,
+    },
+    twitter: {
+      title,
+      description,
+      ...ogImage.twitter,
+    },
+    icons: config.icons,
+  }
+
+  if (!page.extra) return metadata
+  // Shallow-merge the escape hatch, but deep-merge the nested og/twitter so the
+  // image we just set isn't clobbered by a partial `extra.openGraph`.
+  return {
+    ...metadata,
+    ...page.extra,
+    openGraph: { ...metadata.openGraph, ...page.extra.openGraph },
+    twitter: { ...metadata.twitter, ...page.extra.twitter },
+  }
+}
+
+/**
+ * Curries `createMetadata` with a fixed site config so pages call a zero-config
+ * factory. This is the single recommended entry point for app metadata.
+ */
+export function makeMetadataFactory(config: SiteMetaConfig) {
+  return (page: PageMeta = {}): Metadata => createMetadata(config, page)
+}

package/src/og-image/metadata.ts

@@ -1,63 +1,38 @@
 import type { Metadata } from 'next'
-import type { OGImageParams } from './types'
+import type { OGImageParams, OgSpec } from './types'
 import { buildOgUrl } from './url'
 
+const OG_WIDTH = 1200
+const OG_HEIGHT = 630
+
+/** A Next.js OG image entry. */
+function imageEntry(url: string, alt: string) {
+  return { url, width: OG_WIDTH, height: OG_HEIGHT, alt }
+}
+
 /**
- * Creates Next.js Metadata fragment with og:image and twitter:image
- * pointing to Django's django_ogimage renderer.
- *
- * Usage in generateMetadata():
- *   return createOgMetadata({ title: 'Page', preset: 'DARK_BLUE' })
+ * Builds the og/twitter image fragment for a given image URL — the one place
+ * that knows the shape Next.js expects. Both static URLs and the dynamic
+ * renderer funnel through here, so there's a single source of truth.
  */
-export function createOgMetadata(params: OGImageParams): Metadata {
-  const url = buildOgUrl(params)
-  const image = { url, width: 1200, height: 630, alt: params.title }
+function ogImageFragment(url: string, alt: string): Pick<Metadata, 'openGraph' | 'twitter'> {
   return {
-    openGraph: {
-      images: [image],
-    },
-    twitter: {
-      card: 'summary_large_image',
-      images: [url],
-    },
+    openGraph: { images: [imageEntry(url, alt)] },
+    twitter: { card: 'summary_large_image', images: [url] },
   }
 }
 
 /**
- * Merges og:image metadata into an existing Metadata object.
- *
- * Usage:
- *   return withOgImage(
- *     { title: 'Page', description: '...' },
- *     { preset: 'DARK_BLUE', layout: 'HERO' }
- *   )
+ * Metadata fragment whose OG image is rendered by Django's django_ogimage
+ * endpoint (/cfg/og/). Low-level — most callers use `createMetadata`'s `og`
+ * field instead.
  */
-export function withOgImage(
-  metadata: Metadata,
-  params: Omit<OGImageParams, 'title'> & { title?: string }
-): Metadata {
-  // Auto-extract title from metadata; params.title overrides if explicitly provided
-  const resolvedParams: OGImageParams = {
-    title: extractTitle(metadata),
-    ...params,
-  }
-
-  const ogMeta = createOgMetadata(resolvedParams)
-
-  return {
-    ...metadata,
-    openGraph: {
-      ...metadata.openGraph,
-      ...ogMeta.openGraph,
-    },
-    twitter: {
-      ...metadata.twitter,
-      ...ogMeta.twitter,
-    },
-  }
+export function createOgMetadata(params: OGImageParams): Metadata {
+  return ogImageFragment(buildOgUrl(params), params.title)
 }
 
-function extractTitle(metadata: Metadata): string {
+/** Extract a plain title string from Next.js's title shapes. */
+export function extractTitle(metadata: Metadata): string {
   const t = metadata.title
   if (!t) return ''
   if (typeof t === 'string') return t
@@ -65,3 +40,49 @@ function extractTitle(metadata: Metadata): string {
   if (typeof t === 'object' && 'default' in t) return (t as { default: string }).default
   return ''
 }
+
+/**
+ * Resolves an `OgSpec` against a base Metadata into a concrete og/twitter image
+ * fragment. `staticUrl` is the site's brand image, used for the `'static'` case.
+ * Returns `null` only if there's genuinely nothing to set.
+ *
+ * This is the single decision point for "what is the OG image" — no other code
+ * branches on the spec.
+ */
+export function resolveOgImage(
+  spec: OgSpec,
+  staticUrl: string,
+  fallbackTitle: string
+): Pick<Metadata, 'openGraph' | 'twitter'> {
+  if (spec === 'static') {
+    return ogImageFragment(staticUrl, fallbackTitle)
+  }
+  if (spec === 'dynamic') {
+    return ogImageFragment(buildOgUrl({ title: fallbackTitle }), fallbackTitle)
+  }
+  if ('image' in spec) {
+    return ogImageFragment(spec.image, spec.alt ?? fallbackTitle)
+  }
+  // { render: {...} } — dynamic with explicit params; title defaults to page title.
+  const title = spec.render.title ?? fallbackTitle
+  return ogImageFragment(buildOgUrl({ ...spec.render, title }), title)
+}
+
+/**
+ * Merges OG image metadata (dynamic render) into existing Metadata. Kept for
+ * low-level/manual use; `createMetadata` is the recommended entry point.
+ *
+ *   return withOgImage({ title: 'Page' }, { preset: 'DARK_BLUE' })
+ */
+export function withOgImage(
+  metadata: Metadata,
+  params: Omit<OGImageParams, 'title'> & { title?: string } = {}
+): Metadata {
+  const title = params.title ?? extractTitle(metadata)
+  const frag = createOgMetadata({ ...params, title })
+  return {
+    ...metadata,
+    openGraph: { ...metadata.openGraph, ...frag.openGraph },
+    twitter: { ...metadata.twitter, ...frag.twitter },
+  }
+}

package/src/og-image/types.ts

@@ -11,6 +11,21 @@ export type OGPreset =
 
 export type OGLayout = 'DEFAULT' | 'HERO' | 'ARTICLE' | 'MINIMAL'
 
+/**
+ * Per-page OG image intent — the single axis that decides what the OG image is.
+ * A discriminated union so every case is explicit and type-checked:
+ *
+ *   'static'              brand image from site config (the default)
+ *   'dynamic'             render the page title onto the OG card
+ *   { render: {...} }     render with explicit preset/layout/colors
+ *   { image, alt? }       an exact image URL (e.g. a content screenshot)
+ */
+export type OgSpec =
+  | 'static'
+  | 'dynamic'
+  | { render: Omit<OGImageParams, 'title'> & { title?: string } }
+  | { image: string; alt?: string }
+
 /** Mirrors Django OGImageParams exactly */
 export interface OGImageParams {
   title: string