sanity-plugin-seofields 1.2.2 → 1.2.4

package/dist/next.d.mts

@@ -0,0 +1,334 @@
+import {default as React_2} from 'react'
+
+/**
+ * Convert a Sanity SEO object into a structured metadata object.
+ *
+ * The return value is structurally compatible with Next.js App Router's
+ * `Metadata` type, so you can return it directly from `generateMetadata()`.
+ *
+ * @example Next.js App Router
+ * ```ts
+ * import { buildSeoMeta } from 'sanity-plugin-seofields'
+ * import { urlFor } from '@/sanity/lib/image'
+ *
+ * export async function generateMetadata(): Promise<Metadata> {
+ *   const { seo } = await sanityFetch({ query: PAGE_SEO_QUERY })
+ *   return buildSeoMeta({
+ *     seo,
+ *     baseUrl: process.env.NEXT_PUBLIC_SITE_URL,
+ *     path: '/about',
+ *     defaults: { title: 'My Site', siteName: 'My Site' },
+ *     imageUrlResolver: (img) => urlFor(img).width(1200).url(),
+ *   })
+ * }
+ * ```
+ */
+export declare function buildSeoMeta(options: BuildSeoMetaOptions): SeoMetadata
+
+/** Options accepted by buildSeoMeta(). */
+export declare interface BuildSeoMetaOptions {
+  /**
+   * The raw SEO object from Sanity (_type excluded or included — both work).
+   * Pass `null` or `undefined` to fall back entirely to `defaults`.
+   *
+   * Accepts both the strict plugin `SeoFields` type and Sanity's code-generated
+   * type (which has all nested fields optional) without any `as any` cast.
+   */
+  seo?: SeoFieldsInput | null
+  /**
+   * The base URL of your site, e.g. "https://example.com".
+   * Used for canonical URL and OpenGraph URL construction.
+   */
+  baseUrl?: string
+  /**
+   * The path for the current page, e.g. "/about".
+   * Combined with baseUrl to produce the canonical + OG url.
+   * Defaults to "".
+   */
+  path?: string
+  /**
+   * Default values used when the Sanity SEO fields are empty / missing.
+   */
+  defaults?: SeoMetaDefaults
+  /**
+   * Resolve a Sanity image asset to a plain URL string.
+   *
+   * @example (using @sanity/image-url)
+   * imageUrlResolver: (img) => urlFor(img).width(1200).url()
+   */
+  imageUrlResolver?: (image: SanityImage | SanityImageWithAlt) => string | null | undefined
+}
+
+declare interface MetaAttribute {
+  _type: 'metaAttribute'
+  key?: string
+  type?: 'string' | 'image'
+  value?: string
+  image?: SanityImage
+}
+
+declare type OGType = (typeof VALID_OG_TYPES)[number]
+
+declare interface OpenGraphSettings {
+  _type: 'openGraph'
+  /** The canonical URL for OpenGraph (og:url). Maps to the `url` field in Sanity. */
+  url?: string
+  title?: string
+  description?: string
+  siteName?: string
+  type?: 'website' | 'article' | 'profile' | 'book' | 'music' | 'video' | 'product'
+  imageType?: 'upload' | 'url'
+  image?: SanityImageWithAlt
+  imageUrl?: string
+}
+
+declare interface RobotsSettings {
+  noIndex?: boolean
+  noFollow?: boolean
+}
+
+/**
+ * Coerce an arbitrary string to a valid OpenGraph type.
+ * Falls back to "website" when the value is invalid.
+ */
+export declare function sanitizeOGType(value?: string): OGType
+
+/**
+ * Coerce an arbitrary string to a valid Twitter card type.
+ * Falls back to "summary_large_image" when the value is invalid.
+ */
+export declare function sanitizeTwitterCard(value?: string): TwitterCard
+
+declare interface SanityImage {
+  _type: 'image'
+  asset: {
+    _ref: string
+    _type: 'reference'
+  }
+  hotspot?: {
+    x: number
+    y: number
+    height: number
+    width: number
+  }
+  crop?: {
+    top: number
+    bottom: number
+    left: number
+    right: number
+  }
+  alt?: string
+}
+
+declare interface SanityImageWithAlt extends SanityImage {
+  alt: string
+}
+
+declare interface SeoFields {
+  _type: 'seoFields'
+  robots?: RobotsSettings
+  preview?: string
+  title?: string
+  description?: string
+  metaImage?: SanityImage
+  metaAttributes?: MetaAttribute[]
+  keywords?: string[]
+  canonicalUrl?: string
+  openGraph?: OpenGraphSettings
+  twitter?: TwitterCardSettings
+}
+
+/**
+ * Input-compatible variant of SeoFields. Structurally matches Sanity's
+ * code-generated types (where `asset`, `alt`, `key`, and `type` are all
+ * optional), so you can pass `data.seo` from a sanityFetch result directly
+ * without any `as any` or manual casting.
+ */
+declare interface SeoFieldsInput {
+  _type?: string
+  robots?: {
+    noIndex?: boolean | null
+    noFollow?: boolean | null
+  } | null
+  title?: string | null
+  description?: string | null
+  metaImage?: SeoImageInput | null
+  metaAttributes?: Array<{
+    _key?: string
+    key?: string
+    value?: string
+    type?: string
+  }> | null
+  keywords?: string[] | null
+  canonicalUrl?: string | null
+  openGraph?: {
+    _type?: string
+    url?: string | null
+    title?: string | null
+    description?: string | null
+    siteName?: string | null
+    type?: string | null
+    imageType?: string | null
+    image?: SeoImageInput | null
+    imageUrl?: string | null
+  } | null
+  twitter?: {
+    _type?: string
+    card?: string | null
+    site?: string | null
+    creator?: string | null
+    title?: string | null
+    description?: string | null
+    imageType?: string | null
+    image?: SeoImageInput | null
+    imageUrl?: string | null
+  } | null
+}
+
+/**
+ * Permissive image shape accepted by buildSeoMeta — compatible with both the
+ * plugin's SanityImage and Sanity's code-generated image type (where `asset`
+ * and `alt` are optional).
+ */
+declare interface SeoImageInput {
+  _type?: string
+  asset?: {
+    _ref: string
+    _type: string
+    _weak?: boolean
+    [key: string]: unknown
+  }
+  hotspot?: unknown
+  crop?: unknown
+  alt?: string
+}
+
+/** Structured metadata returned by buildSeoMeta(). Compatible with Next.js Metadata (App Router). */
+export declare interface SeoMetadata {
+  title?: string | null
+  description?: string | null
+  keywords?: string[]
+  robots?: {
+    index?: boolean
+    follow?: boolean
+    googleBot?: {
+      index?: boolean
+      follow?: boolean
+    }
+  }
+  openGraph?: {
+    type?: string
+    url?: string
+    title?: string
+    description?: string
+    siteName?: string
+    images?: Array<{
+      url: string
+      width?: number
+      height?: number
+      alt?: string
+    }>
+  }
+  twitter?: {
+    card?: string
+    site?: string
+    creator?: string
+    title?: string
+    description?: string
+    images?: string[]
+  }
+  alternates?: {
+    canonical?: string
+  }
+  /** Any custom meta attributes from seo.metaAttributes */
+  other?: Record<string, string>
+}
+
+/** Default values used when SEO fields are missing. */
+export declare interface SeoMetaDefaults {
+  title?: string
+  description?: string
+  siteName?: string
+  twitterSite?: string
+  twitterCreator?: string
+  /** Fallback image URL when no OG / Twitter image is set. */
+  ogImage?: string
+}
+
+/**
+ * Renders all SEO meta tags for a page as plain React elements.
+ * Intended to be placed inside your framework's <Head> / <head> component.
+ *
+ * Renders:
+ * - `<title>`
+ * - `<meta name="description">`
+ * - `<meta name="keywords">`
+ * - `<meta name="robots">`
+ * - OpenGraph meta tags (`og:*`)
+ * - Twitter Card meta tags (`twitter:*`)
+ * - Any custom `seo.metaAttributes` as `<meta name="..." content="...">`
+ */
+export declare function SeoMetaTags({
+  data,
+  baseUrl,
+  path,
+  defaults,
+  imageUrlResolver,
+}: SeoMetaTagsProps): React_2.JSX.Element
+
+export declare interface SeoMetaTagsProps {
+  /**
+   * The raw SEO object from Sanity.
+   * Pass `null` / `undefined` to render only the defaults.
+   */
+  data?: Partial<SeoFields> | null
+  /**
+   * Base URL of your site, e.g. "https://example.com".
+   * Used for canonical link, og:url fallback.
+   */
+  baseUrl?: string
+  /**
+   * Current page path, e.g. "/about".
+   * Defaults to "".
+   */
+  path?: string
+  /**
+   * Default values used when SEO fields are missing.
+   */
+  defaults?: BuildSeoMetaOptions['defaults']
+  /**
+   * Resolve a Sanity image asset reference to a full URL string.
+   *
+   * @example
+   * imageUrlResolver={(img) => urlFor(img).width(1200).url()}
+   */
+  imageUrlResolver?: (image: SanityImage | SanityImageWithAlt) => string | null | undefined
+}
+
+declare type TwitterCard = (typeof VALID_TWITTER_CARDS)[number]
+
+declare interface TwitterCardSettings {
+  _type: 'twitter'
+  card?: 'summary' | 'summary_large_image' | 'app' | 'player'
+  site?: string
+  creator?: string
+  title?: string
+  description?: string
+  imageType?: 'upload' | 'url'
+  image?: SanityImageWithAlt
+  imageUrl?: string
+}
+
+declare const VALID_OG_TYPES: readonly [
+  'website',
+  'article',
+  'profile',
+  'book',
+  'music',
+  'video',
+  'product',
+]
+
+declare const VALID_TWITTER_CARDS: readonly ['summary', 'summary_large_image', 'app', 'player']
+
+export {}

package/dist/next.d.ts

@@ -0,0 +1,334 @@
+import {default as React_2} from 'react'
+
+/**
+ * Convert a Sanity SEO object into a structured metadata object.
+ *
+ * The return value is structurally compatible with Next.js App Router's
+ * `Metadata` type, so you can return it directly from `generateMetadata()`.
+ *
+ * @example Next.js App Router
+ * ```ts
+ * import { buildSeoMeta } from 'sanity-plugin-seofields'
+ * import { urlFor } from '@/sanity/lib/image'
+ *
+ * export async function generateMetadata(): Promise<Metadata> {
+ *   const { seo } = await sanityFetch({ query: PAGE_SEO_QUERY })
+ *   return buildSeoMeta({
+ *     seo,
+ *     baseUrl: process.env.NEXT_PUBLIC_SITE_URL,
+ *     path: '/about',
+ *     defaults: { title: 'My Site', siteName: 'My Site' },
+ *     imageUrlResolver: (img) => urlFor(img).width(1200).url(),
+ *   })
+ * }
+ * ```
+ */
+export declare function buildSeoMeta(options: BuildSeoMetaOptions): SeoMetadata
+
+/** Options accepted by buildSeoMeta(). */
+export declare interface BuildSeoMetaOptions {
+  /**
+   * The raw SEO object from Sanity (_type excluded or included — both work).
+   * Pass `null` or `undefined` to fall back entirely to `defaults`.
+   *
+   * Accepts both the strict plugin `SeoFields` type and Sanity's code-generated
+   * type (which has all nested fields optional) without any `as any` cast.
+   */
+  seo?: SeoFieldsInput | null
+  /**
+   * The base URL of your site, e.g. "https://example.com".
+   * Used for canonical URL and OpenGraph URL construction.
+   */
+  baseUrl?: string
+  /**
+   * The path for the current page, e.g. "/about".
+   * Combined with baseUrl to produce the canonical + OG url.
+   * Defaults to "".
+   */
+  path?: string
+  /**
+   * Default values used when the Sanity SEO fields are empty / missing.
+   */
+  defaults?: SeoMetaDefaults
+  /**
+   * Resolve a Sanity image asset to a plain URL string.
+   *
+   * @example (using @sanity/image-url)
+   * imageUrlResolver: (img) => urlFor(img).width(1200).url()
+   */
+  imageUrlResolver?: (image: SanityImage | SanityImageWithAlt) => string | null | undefined
+}
+
+declare interface MetaAttribute {
+  _type: 'metaAttribute'
+  key?: string
+  type?: 'string' | 'image'
+  value?: string
+  image?: SanityImage
+}
+
+declare type OGType = (typeof VALID_OG_TYPES)[number]
+
+declare interface OpenGraphSettings {
+  _type: 'openGraph'
+  /** The canonical URL for OpenGraph (og:url). Maps to the `url` field in Sanity. */
+  url?: string
+  title?: string
+  description?: string
+  siteName?: string
+  type?: 'website' | 'article' | 'profile' | 'book' | 'music' | 'video' | 'product'
+  imageType?: 'upload' | 'url'
+  image?: SanityImageWithAlt
+  imageUrl?: string
+}
+
+declare interface RobotsSettings {
+  noIndex?: boolean
+  noFollow?: boolean
+}
+
+/**
+ * Coerce an arbitrary string to a valid OpenGraph type.
+ * Falls back to "website" when the value is invalid.
+ */
+export declare function sanitizeOGType(value?: string): OGType
+
+/**
+ * Coerce an arbitrary string to a valid Twitter card type.
+ * Falls back to "summary_large_image" when the value is invalid.
+ */
+export declare function sanitizeTwitterCard(value?: string): TwitterCard
+
+declare interface SanityImage {
+  _type: 'image'
+  asset: {
+    _ref: string
+    _type: 'reference'
+  }
+  hotspot?: {
+    x: number
+    y: number
+    height: number
+    width: number
+  }
+  crop?: {
+    top: number
+    bottom: number
+    left: number
+    right: number
+  }
+  alt?: string
+}
+
+declare interface SanityImageWithAlt extends SanityImage {
+  alt: string
+}
+
+declare interface SeoFields {
+  _type: 'seoFields'
+  robots?: RobotsSettings
+  preview?: string
+  title?: string
+  description?: string
+  metaImage?: SanityImage
+  metaAttributes?: MetaAttribute[]
+  keywords?: string[]
+  canonicalUrl?: string
+  openGraph?: OpenGraphSettings
+  twitter?: TwitterCardSettings
+}
+
+/**
+ * Input-compatible variant of SeoFields. Structurally matches Sanity's
+ * code-generated types (where `asset`, `alt`, `key`, and `type` are all
+ * optional), so you can pass `data.seo` from a sanityFetch result directly
+ * without any `as any` or manual casting.
+ */
+declare interface SeoFieldsInput {
+  _type?: string
+  robots?: {
+    noIndex?: boolean | null
+    noFollow?: boolean | null
+  } | null
+  title?: string | null
+  description?: string | null
+  metaImage?: SeoImageInput | null
+  metaAttributes?: Array<{
+    _key?: string
+    key?: string
+    value?: string
+    type?: string
+  }> | null
+  keywords?: string[] | null
+  canonicalUrl?: string | null
+  openGraph?: {
+    _type?: string
+    url?: string | null
+    title?: string | null
+    description?: string | null
+    siteName?: string | null
+    type?: string | null
+    imageType?: string | null
+    image?: SeoImageInput | null
+    imageUrl?: string | null
+  } | null
+  twitter?: {
+    _type?: string
+    card?: string | null
+    site?: string | null
+    creator?: string | null
+    title?: string | null
+    description?: string | null
+    imageType?: string | null
+    image?: SeoImageInput | null
+    imageUrl?: string | null
+  } | null
+}
+
+/**
+ * Permissive image shape accepted by buildSeoMeta — compatible with both the
+ * plugin's SanityImage and Sanity's code-generated image type (where `asset`
+ * and `alt` are optional).
+ */
+declare interface SeoImageInput {
+  _type?: string
+  asset?: {
+    _ref: string
+    _type: string
+    _weak?: boolean
+    [key: string]: unknown
+  }
+  hotspot?: unknown
+  crop?: unknown
+  alt?: string
+}
+
+/** Structured metadata returned by buildSeoMeta(). Compatible with Next.js Metadata (App Router). */
+export declare interface SeoMetadata {
+  title?: string | null
+  description?: string | null
+  keywords?: string[]
+  robots?: {
+    index?: boolean
+    follow?: boolean
+    googleBot?: {
+      index?: boolean
+      follow?: boolean
+    }
+  }
+  openGraph?: {
+    type?: string
+    url?: string
+    title?: string
+    description?: string
+    siteName?: string
+    images?: Array<{
+      url: string
+      width?: number
+      height?: number
+      alt?: string
+    }>
+  }
+  twitter?: {
+    card?: string
+    site?: string
+    creator?: string
+    title?: string
+    description?: string
+    images?: string[]
+  }
+  alternates?: {
+    canonical?: string
+  }
+  /** Any custom meta attributes from seo.metaAttributes */
+  other?: Record<string, string>
+}
+
+/** Default values used when SEO fields are missing. */
+export declare interface SeoMetaDefaults {
+  title?: string
+  description?: string
+  siteName?: string
+  twitterSite?: string
+  twitterCreator?: string
+  /** Fallback image URL when no OG / Twitter image is set. */
+  ogImage?: string
+}
+
+/**
+ * Renders all SEO meta tags for a page as plain React elements.
+ * Intended to be placed inside your framework's <Head> / <head> component.
+ *
+ * Renders:
+ * - `<title>`
+ * - `<meta name="description">`
+ * - `<meta name="keywords">`
+ * - `<meta name="robots">`
+ * - OpenGraph meta tags (`og:*`)
+ * - Twitter Card meta tags (`twitter:*`)
+ * - Any custom `seo.metaAttributes` as `<meta name="..." content="...">`
+ */
+export declare function SeoMetaTags({
+  data,
+  baseUrl,
+  path,
+  defaults,
+  imageUrlResolver,
+}: SeoMetaTagsProps): React_2.JSX.Element
+
+export declare interface SeoMetaTagsProps {
+  /**
+   * The raw SEO object from Sanity.
+   * Pass `null` / `undefined` to render only the defaults.
+   */
+  data?: Partial<SeoFields> | null
+  /**
+   * Base URL of your site, e.g. "https://example.com".
+   * Used for canonical link, og:url fallback.
+   */
+  baseUrl?: string
+  /**
+   * Current page path, e.g. "/about".
+   * Defaults to "".
+   */
+  path?: string
+  /**
+   * Default values used when SEO fields are missing.
+   */
+  defaults?: BuildSeoMetaOptions['defaults']
+  /**
+   * Resolve a Sanity image asset reference to a full URL string.
+   *
+   * @example
+   * imageUrlResolver={(img) => urlFor(img).width(1200).url()}
+   */
+  imageUrlResolver?: (image: SanityImage | SanityImageWithAlt) => string | null | undefined
+}
+
+declare type TwitterCard = (typeof VALID_TWITTER_CARDS)[number]
+
+declare interface TwitterCardSettings {
+  _type: 'twitter'
+  card?: 'summary' | 'summary_large_image' | 'app' | 'player'
+  site?: string
+  creator?: string
+  title?: string
+  description?: string
+  imageType?: 'upload' | 'url'
+  image?: SanityImageWithAlt
+  imageUrl?: string
+}
+
+declare const VALID_OG_TYPES: readonly [
+  'website',
+  'article',
+  'profile',
+  'book',
+  'music',
+  'video',
+  'product',
+]
+
+declare const VALID_TWITTER_CARDS: readonly ['summary', 'summary_large_image', 'app', 'player']
+
+export {}