@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/legacy/seo.ts

@@ -0,0 +1,327 @@
+import type { OpeningHoursDay, OpeningHoursRow, PageSeo, SiteSeo } from './content'
+
+/**
+ * Titles, metadata and JSON-LD: the one implementation, shared by this kit, v1 (`../seo/*`, which
+ * wraps it) and the platform's SEO screen, so each resolves a page the same way. It lives here
+ * rather than in `../seo` because this folder is packed on its own as the kit every launched site
+ * vendors (`stageLegacyKit`), so nothing here may import from outside it.
+ *
+ * Pure and free of Next at runtime. Every rule this kit's `metadataFor` applies is one line in
+ * `verify:seo-metadata`.
+ *
+ * **Empty is not an override.** A string that is blank or only whitespace falls back, so a client
+ * who clears a field gets the site default rather than an empty title.
+ */
+
+/**
+ * A page's metadata in the subset of Next's `Metadata` this kit sets. It is structurally
+ * assignable to `Metadata` (v1's `metadataFor`, `../seo/metadata.ts`, returns one as the other, so
+ * the compiler checks it). A legacy site writes
+ * `export const generateMetadata = async (): Promise<Metadata> => metadataFor({...})` and the
+ * types line up without a cast, whatever version of Next it runs.
+ */
+export type SeoMetadata = {
+  alternates?: { canonical?: string; languages?: Record<string, string> }
+  description?: string
+  openGraph?: {
+    description?: string
+    images?: { alt?: string; url: string }[]
+    locale?: string
+    siteName?: string
+    title?: string
+    type?: 'website'
+  }
+  other?: Record<string, string>
+  robots?: { follow: boolean; index: boolean }
+  title?: string
+  twitter?: {
+    card?: 'summary' | 'summary_large_image'
+    description?: string
+    images?: string[]
+    site?: string
+    title?: string
+  }
+}
+
+/** A value trimmed, or null when it is blank: an empty field falls back rather than overriding. */
+const filled = (value: null | string | undefined): null | string => {
+  const trimmed = (value ?? '').trim()
+  return trimmed === '' ? null : trimmed
+}
+
+/** The separators title templates use between the page and the site name. */
+const SEPARATOR_CLASS = '[—|·:-]'
+
+/**
+ * The page title a site renders: the template with `%page%`/`%site%` (the platform's spelling) or
+ * `%s` (the manifest's) replaced by the page's title and the site name, else the page title alone.
+ *
+ * A template with no page token in it is honoured rather than corrected: the SEO screen flags it,
+ * because a person who typed it may have meant it. A blank template means no template. With no
+ * page title the site name stands alone. With no site name, `%site%` goes together with the
+ * separator beside it, so `%page% — %site%` gives `About Us`, not `About Us —`.
+ */
+export const applyTitleTemplate = ({
+  pageTitle,
+  siteName,
+  template,
+}: {
+  pageTitle: null | string
+  siteName: null | string
+  template: null | string
+}): string => {
+  const page = filled(pageTitle)
+  const site = filled(siteName)
+  const shape = filled(template)
+
+  if (!shape) return page ?? site ?? ''
+  if (!page) return site ?? ''
+
+  const withSite = site
+    ? shape
+    : shape
+        .replace(new RegExp(`\\s*${SEPARATOR_CLASS}\\s*%site%`), '')
+        .replace(new RegExp(`%site%\\s*${SEPARATOR_CLASS}\\s*`), '')
+        .replace('%site%', '')
+
+  // One pass, so a token inside the page title or the site name is not substituted again, and a
+  // function replacer, so a `$&` in either is inserted as written.
+  return withSite.replace(/%page%|%site%|%s/g, (token) => (token === '%site%' ? (site ?? '') : page)).trim()
+}
+
+/** Join an origin and a path without doubling or dropping the slash between them. */
+export const joinUrl = (origin: string, path: string): string => {
+  const base = origin.replace(/\/$/, '')
+  if (path === '' || path === '/') return base || '/'
+  return `${base}/${path.replace(/^\//, '')}`
+}
+
+/** A page's SEO with its share image resolved to a URL: what the merge reads. v1's `PageSeoInput` is this. */
+export type SeoPageInput = {
+  title: null | string
+  description: null | string
+  ogTitle: null | string
+  ogDescription: null | string
+  ogImage: { url: string; alt?: string } | null
+  canonical: null | string
+  noindex: boolean
+}
+
+export type SeoMergeInput = {
+  /** The platform's site-wide SEO settings; null for a site with no platform, or when they could not be read. */
+  site: null | SiteSeo
+  /** The site code's own `seo` defaults, used field by field where the platform has set nothing. Null for this kit's sites. */
+  manifest: { titleTemplate?: string; defaultImage?: string; organisation?: { name?: string } } | null
+  page: SeoPageInput | null
+  /** The page's own title. The template is applied to it. */
+  pageTitle: string
+  /** The site's origin. Without one, and with no canonical of the page's own, no canonical is set. */
+  origin?: string
+  /** The path this page answers at, e.g. `/about-us` or `/`. */
+  path: string
+  /** How `origin` and `path` make the canonical URL, so it matches the caller's sitemap. `joinUrl` (no slash after the home) when absent. */
+  urlFor?: (origin: string, path: string) => string
+}
+
+/**
+ * The merge, and the only place precedence is decided: the page's SEO over the platform's site-wide
+ * SEO over the manifest's defaults. `robots` is left to the caller's rule: v1's `metadataFor`
+ * (`../seo/metadata.ts`) and this kit's `metadataFor` below each have their own.
+ *
+ * The page's SEO title is the whole title, as the platform's SEO screen shows it. Without one, the
+ * template (the platform's, else the manifest's) is applied to the page's own title, and `%site%`
+ * is the platform's site name, else the manifest's organisation name. Each falls back on its own,
+ * so a platform template with no platform site name still names the site.
+ *
+ * Every string counts only when it holds more than whitespace, so a person who clears a field gets
+ * the fallback rather than an empty title.
+ */
+export const seoMetadataFor = (i: SeoMergeInput, robots: SeoMetadata['robots']): SeoMetadata => {
+  const { site, manifest, page } = i
+  const siteName = filled(site?.siteName) ?? filled(manifest?.organisation?.name)
+  const title =
+    filled(page?.title) ??
+    filled(applyTitleTemplate({ pageTitle: i.pageTitle, siteName, template: filled(site?.titleTemplate) ?? filled(manifest?.titleTemplate) }))
+
+  const description = filled(page?.description) ?? filled(site?.description)
+
+  // Social fields fall back to the RESOLVED title and description, never the raw template.
+  const ogTitle = filled(page?.ogTitle) ?? title
+  const ogDescription = filled(page?.ogDescription) ?? description
+  const siteImage = site?.ogImage?.url ? { url: site.ogImage.url, alt: site.ogImage.alt } : null
+  const defaultImage = filled(manifest?.defaultImage)
+  const image = page?.ogImage ?? siteImage ?? (defaultImage ? { url: defaultImage } : null)
+
+  const verification: Record<string, string> = {}
+  const google = filled(site?.googleVerification)
+  const bing = filled(site?.bingVerification)
+  if (google) verification['google-site-verification'] = google
+  if (bing) verification['msvalidate.01'] = bing
+
+  const handle = filled(site?.twitterHandle)
+  const locale = filled(site?.locale)
+  const canonical = filled(page?.canonical) ?? (i.origin !== undefined ? (i.urlFor ?? joinUrl)(i.origin, i.path) : null)
+
+  return {
+    ...(canonical ? { alternates: { canonical } } : {}),
+    ...(description ? { description } : {}),
+    openGraph: {
+      ...(ogDescription ? { description: ogDescription } : {}),
+      ...(image?.url ? { images: [{ ...(image.alt !== undefined ? { alt: image.alt } : {}), url: image.url }] } : {}),
+      ...(locale ? { locale } : {}),
+      ...(siteName ? { siteName } : {}),
+      ...(ogTitle ? { title: ogTitle } : {}),
+      type: 'website',
+    },
+    ...(Object.keys(verification).length > 0 ? { other: verification } : {}),
+    ...(robots ? { robots } : {}),
+    ...(title ? { title } : {}),
+    twitter: {
+      card: site?.twitterCard ?? 'summary_large_image',
+      ...(ogDescription ? { description: ogDescription } : {}),
+      ...(image?.url ? { images: [image.url] } : {}),
+      ...(handle ? { site: handle.startsWith('@') ? handle : `@${handle}` } : {}),
+      ...(ogTitle ? { title: ogTitle } : {}),
+    },
+  }
+}
+
+/**
+ * This kit's `metadataFor`: the merge with no manifest defaults, and with this kit's own indexing
+ * rule. A page is indexed only while the platform says indexing is on and the page does not say
+ * noindex, so a null site (a failed read) is not indexed. `follow` tracks `index`.
+ */
+export const metadataFor = ({
+  origin,
+  page,
+  path,
+  site,
+}: {
+  origin: string
+  /** This page's stored SEO, and its own title. Null seo means the platform said nothing. */
+  page: { seo: null | PageSeo; title: null | string }
+  /** The path this page answers at, e.g. `about-us` or `/`. */
+  path: string
+  site: null | SiteSeo
+}): SeoMetadata => {
+  const seo = page.seo
+  const indexable = site?.allowIndexing === true && seo?.noindex !== true
+  return seoMetadataFor(
+    {
+      site,
+      manifest: null,
+      page: seo ? { ...seo, ogImage: seo.ogImage?.url ? { url: seo.ogImage.url, alt: seo.ogImage.alt } : null } : null,
+      pageTitle: page.title ?? '',
+      origin,
+      path,
+    },
+    { follow: indexable, index: indexable },
+  )
+}
+
+type OpeningHoursSpec = {
+  '@type': 'OpeningHoursSpecification'
+  closes: string
+  dayOfWeek: OpeningHoursDay[]
+  opens: string
+}
+
+/**
+ * `organisation.openingHours`, as schema.org `OpeningHoursSpecification` entries.
+ *
+ * A closed day, or a day with no `opens`/`closes` pair, has nothing schema.org can use and is
+ * dropped rather than emitted with a null time: Google reports a spec entry with a missing time as
+ * an error, which is worse than saying nothing about that day.
+ *
+ * Days sharing an identical `{opens, closes}` collapse into one entry listing every `dayOfWeek`
+ * that applies, which schema.org allows.
+ */
+const openingHoursSpecification = (rows: readonly OpeningHoursRow[]): OpeningHoursSpec[] => {
+  const groups = new Map<string, OpeningHoursSpec>()
+  for (const row of rows) {
+    if (row.closed || row.opens === null || row.closes === null) continue
+    const key = `${row.opens}|${row.closes}`
+    const existing = groups.get(key)
+    if (existing) existing.dayOfWeek.push(row.day)
+    else groups.set(key, { '@type': 'OpeningHoursSpecification', closes: row.closes, dayOfWeek: [row.day], opens: row.opens })
+  }
+  return [...groups.values()]
+}
+
+/**
+ * The organisation, as schema.org JSON-LD, or null.
+ *
+ * The name is the organisation's `legalName`, else the site name. Without either, or without an
+ * organisation, there is none: a business panel with no name is malformed structured data, and
+ * Google reports it as an error against the site.
+ */
+export const organisationJsonLd = ({ origin, site }: { origin: string; site: null | SiteSeo }): Record<string, unknown> | null => {
+  const organisation = site?.organisation
+  const name = filled(organisation?.legalName) ?? filled(site?.siteName)
+  if (!organisation || !name) return null
+
+  const openingHoursSpec = openingHoursSpecification(organisation.openingHours)
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Organization',
+    name,
+    url: origin.replace(/\/$/, ''),
+    ...(organisation.logo?.url ? { logo: organisation.logo.url } : {}),
+    ...(filled(organisation.phone) ? { telephone: organisation.phone } : {}),
+    ...(filled(organisation.email) ? { email: organisation.email } : {}),
+    ...(filled(organisation.address) ? { address: organisation.address } : {}),
+    // Structured hours win when there are any. The free-text field is the fallback for a tenant
+    // who has not used the structured editor, emitted the old way, as a string.
+    ...(openingHoursSpec.length > 0
+      ? { openingHoursSpecification: openingHoursSpec }
+      : filled(organisation.legacyOpeningHours)
+        ? { openingHours: organisation.legacyOpeningHours }
+        : {}),
+    ...(organisation.sameAs.length > 0 ? { sameAs: organisation.sameAs } : {}),
+  }
+}
+
+/**
+ * `sitemap.xml`, from the platform's published pages.
+ *
+ * Empty while `allowIndexing` is off. A sitemap is a request to be crawled, and serving one
+ * from a site whose robots.txt disallows everything is a contradiction — the same
+ * contradiction, one level up, that dropping `noindex` pages avoids per-page.
+ */
+export const sitemapFrom = ({
+  entries,
+  origin,
+  site,
+}: {
+  entries: readonly { lastModified: null | string; slug: string }[]
+  origin: string
+  site: null | SiteSeo
+}): { lastModified?: string; url: string }[] => {
+  if (site?.allowIndexing !== true) return []
+
+  return entries.map((entry) => ({
+    ...(entry.lastModified ? { lastModified: entry.lastModified } : {}),
+    // `home` is the site root, not `/home` — the same convention `pages.slug` describes.
+    url: joinUrl(origin, entry.slug === 'home' ? '/' : entry.slug),
+  }))
+}
+
+export const robotsFrom = ({
+  origin,
+  site,
+}: {
+  origin: string
+  site: null | SiteSeo
+}): { rules: { allow?: string; disallow?: string; userAgent: string }; sitemap?: string } =>
+  site?.allowIndexing === true
+    ? {
+        rules: { allow: '/', userAgent: '*' },
+        sitemap: joinUrl(origin, 'sitemap.xml'),
+      }
+    : /*
+       * Disallow everything and advertise no sitemap. This is the default, because
+       * `allowIndexing` defaults to false — a prospect site must stay out of Google until
+       * somebody decides otherwise.
+       */
+      { rules: { disallow: '/', userAgent: '*' } }