@duffcloudservices/cms 0.3.12 → 0.3.14

package/src/composables/useSEO.ts

@@ -1,387 +1,387 @@
-/**
- * useSEO Composable
- *
- * Provides SEO configuration with build-time injection support from .dcs/seo.yaml.
- * Generates meta tags, Open Graph, Twitter Cards, and JSON-LD structured data.
- *
- * @example
- * ```vue
- * <script setup lang="ts">
- * import { useSEO } from '@duffcloudservices/cms'
- *
- * const { applyHead, getSchema, config } = useSEO('home')
- *
- * // Apply all meta tags
- * applyHead()
- *
- * // Or customize before applying
- * applyHead({
- *   title: 'Custom Override Title',
- *   schemas: [...getSchema(), customSchema]
- * })
- * </script>
- * ```
- */
-
-import { computed, type ComputedRef } from 'vue'
-import { useHead } from '@unhead/vue'
-import type {
-  SeoConfiguration,
-  GlobalSeoConfig,
-  SeoOpenGraphConfig,
-  SeoTwitterConfig,
-  SeoSchemaConfig,
-  ResolvedPageSeo,
-  UseSeoReturn,
-  HeadOverrides,
-} from '../types/seo'
-
-// Declare the global injected by dcsSeoPlugin
-declare const __DCS_SEO__: SeoConfiguration | undefined
-
-/**
- * Safely get build-time SEO configuration.
- * Returns undefined if not available (no seo.yaml or plugin not configured).
- */
-function getBuildTimeSeo(): SeoConfiguration | undefined {
-  try {
-    if (typeof __DCS_SEO__ !== 'undefined' && __DCS_SEO__ !== null) {
-      return __DCS_SEO__
-    }
-  } catch {
-    // __DCS_SEO__ not defined - that's fine, use defaults
-  }
-  return undefined
-}
-
-// =============================================================================
-// Meta Tag Generation Utilities
-// =============================================================================
-
-interface HeadInput {
-  title?: string
-  titleTemplate?: string | ((title: string) => string)
-  meta?: Array<{ name?: string; property?: string; content: string }>
-  link?: Array<{ rel: string; href: string; hreflang?: string }>
-  script?: Array<{ type: string; children: string }>
-}
-
-/**
- * Generate Open Graph meta tags from config
- */
-function generateOpenGraphMeta(
-  og: SeoOpenGraphConfig,
-  global: GlobalSeoConfig,
-  pageTitle: string,
-  pageDescription: string,
-  canonical: string
-): Array<{ property: string; content: string }> {
-  const tags: Array<{ property: string; content: string }> = []
-
-  tags.push({ property: 'og:title', content: og.title || pageTitle })
-  tags.push({ property: 'og:description', content: og.description || pageDescription })
-  tags.push({ property: 'og:url', content: og.url || canonical })
-  tags.push({ property: 'og:type', content: og.type || 'website' })
-
-  const image = og.image || global.images?.ogDefault
-  if (image) {
-    tags.push({ property: 'og:image', content: image })
-    if (og.imageAlt || pageTitle) {
-      tags.push({ property: 'og:image:alt', content: og.imageAlt || pageTitle })
-    }
-    if (og.imageWidth) {
-      tags.push({ property: 'og:image:width', content: String(og.imageWidth) })
-    }
-    if (og.imageHeight) {
-      tags.push({ property: 'og:image:height', content: String(og.imageHeight) })
-    }
-  }
-
-  if (global.siteName) {
-    tags.push({ property: 'og:site_name', content: global.siteName })
-  }
-
-  if (global.locale) {
-    tags.push({ property: 'og:locale', content: global.locale })
-  }
-
-  // Article-specific tags
-  if (og.type === 'article') {
-    if (og.publishedTime) {
-      tags.push({ property: 'article:published_time', content: og.publishedTime })
-    }
-    if (og.modifiedTime) {
-      tags.push({ property: 'article:modified_time', content: og.modifiedTime })
-    }
-    if (og.author) {
-      tags.push({ property: 'article:author', content: og.author })
-    }
-    if (og.section) {
-      tags.push({ property: 'article:section', content: og.section })
-    }
-    if (og.tags) {
-      og.tags.forEach((tag) => {
-        tags.push({ property: 'article:tag', content: tag })
-      })
-    }
-  }
-
-  return tags
-}
-
-/**
- * Generate Twitter Card meta tags from config
- */
-function generateTwitterMeta(
-  twitter: SeoTwitterConfig,
-  global: GlobalSeoConfig,
-  pageTitle: string,
-  pageDescription: string
-): Array<{ name: string; content: string }> {
-  const tags: Array<{ name: string; content: string }> = []
-
-  tags.push({ name: 'twitter:card', content: twitter.card || 'summary_large_image' })
-  tags.push({ name: 'twitter:title', content: twitter.title || pageTitle })
-  tags.push({ name: 'twitter:description', content: twitter.description || pageDescription })
-
-  const image = twitter.image || global.images?.twitterDefault
-  if (image) {
-    tags.push({ name: 'twitter:image', content: image })
-    if (twitter.imageAlt || pageTitle) {
-      tags.push({ name: 'twitter:image:alt', content: twitter.imageAlt || pageTitle })
-    }
-  }
-
-  const site = twitter.site || global.social?.twitter
-  if (site) {
-    tags.push({ name: 'twitter:site', content: site.startsWith('@') ? site : `@${site}` })
-  }
-
-  if (twitter.creator) {
-    tags.push({
-      name: 'twitter:creator',
-      content: twitter.creator.startsWith('@') ? twitter.creator : `@${twitter.creator}`,
-    })
-  }
-
-  return tags
-}
-
-/**
- * Generate JSON-LD script content from schemas
- */
-function generateJsonLd(schemas: SeoSchemaConfig[], global: GlobalSeoConfig): object[] {
-  return schemas.map((schema) => {
-    const base: Record<string, unknown> = {
-      '@context': 'https://schema.org',
-      '@type': schema.type,
-    }
-
-    // Merge properties
-    if (schema.properties) {
-      Object.assign(base, schema.properties)
-    }
-
-    // Auto-populate common properties from global config
-    if (schema.type === 'WebSite' && global.siteUrl && !base.url) {
-      base.url = global.siteUrl
-    }
-    if (schema.type === 'WebSite' && global.siteName && !base.name) {
-      base.name = global.siteName
-    }
-
-    return base
-  })
-}
-
-/**
- * Resolve page SEO by merging global defaults with page-specific config
- */
-function resolvePageSeo(
-  pageSlug: string,
-  pagePath: string | undefined,
-  seoConfig: SeoConfiguration | undefined
-): ResolvedPageSeo {
-  const global = seoConfig?.global ?? {}
-  const page = seoConfig?.pages?.[pageSlug] ?? {}
-
-  // Build canonical URL
-  let canonical = page.canonical || ''
-  if (!canonical && global.siteUrl) {
-    const path = pagePath ?? (pageSlug === 'home' ? '/' : `/${pageSlug}`)
-    canonical = `${global.siteUrl.replace(/\/$/, '')}${path}`
-  }
-
-  // Build title
-  let title = page.title || global.defaultTitle || pageSlug
-  if (!page.noTitleTemplate && global.titleTemplate) {
-    title = global.titleTemplate.replace('%s', title)
-  }
-
-  // Merge Open Graph
-  const openGraph: ResolvedPageSeo['openGraph'] = {
-    type: page.openGraph?.type || 'website',
-    title: page.openGraph?.title || page.title || global.defaultTitle || '',
-    description: page.openGraph?.description || page.description || global.defaultDescription || '',
-    ...page.openGraph,
-  }
-
-  // Merge Twitter
-  const twitter: ResolvedPageSeo['twitter'] = {
-    card: page.twitter?.card || 'summary_large_image',
-    ...page.twitter,
-  }
-
-  // Combine schemas (global + page)
-  const schemas = [...(global.schemas ?? []), ...(page.schemas ?? [])]
-
-  return {
-    title,
-    description: page.description || global.defaultDescription || '',
-    canonical,
-    robots: page.robots || global.robots || 'index, follow',
-    openGraph,
-    twitter,
-    schemas,
-    alternates: page.alternates ?? [],
-  }
-}
-
-/**
- * useSEO composable for DCS-managed SEO configuration.
- *
- * @param pageSlug - Page slug matching entry in seo.yaml
- * @param pagePath - Optional page path for canonical URL generation
- * @returns SEO helpers and state
- */
-export function useSEO(pageSlug: string, pagePath?: string): UseSeoReturn {
-  const seoConfig = getBuildTimeSeo()
-  const hasBuildTimeSeo = seoConfig !== undefined
-
-  // Computed resolved config
-  const config: ComputedRef<ResolvedPageSeo> = computed(() =>
-    resolvePageSeo(pageSlug, pagePath, seoConfig)
-  )
-
-  /**
-   * Get JSON-LD schema objects for the page
-   */
-  function getSchema(): object[] {
-    return generateJsonLd(config.value.schemas, seoConfig?.global ?? {})
-  }
-
-  /**
-   * Get canonical URL for the page
-   */
-  function getCanonical(): string {
-    return config.value.canonical
-  }
-
-  /**
-   * Apply all meta tags via useHead
-   */
-  function applyHead(overrides?: HeadOverrides): void {
-    const resolved = config.value
-    const global = seoConfig?.global ?? {}
-
-    const title = overrides?.title ?? resolved.title
-    const description = overrides?.description ?? resolved.description
-
-    // Build meta tags
-    const meta: HeadInput['meta'] = []
-
-    // Basic meta
-    meta.push({ name: 'description', content: description })
-    if (resolved.robots) {
-      meta.push({ name: 'robots', content: resolved.robots })
-    }
-
-    // Verification codes
-    if (global.verification?.google) {
-      meta.push({ name: 'google-site-verification', content: global.verification.google })
-    }
-    if (global.verification?.bing) {
-      meta.push({ name: 'msvalidate.01', content: global.verification.bing })
-    }
-
-    // Open Graph
-    const ogMeta = generateOpenGraphMeta(
-      resolved.openGraph,
-      global,
-      title,
-      description,
-      resolved.canonical
-    )
-    meta.push(...ogMeta.map((t) => ({ property: t.property, content: t.content })))
-
-    // Twitter
-    const twitterMeta = generateTwitterMeta(resolved.twitter, global, title, description)
-    meta.push(...twitterMeta.map((t) => ({ name: t.name, content: t.content })))
-
-    // Additional overrides
-    if (overrides?.meta) {
-      meta.push(...overrides.meta)
-    }
-
-    // Build links
-    const link: HeadInput['link'] = []
-
-    // Canonical
-    if (resolved.canonical) {
-      link.push({ rel: 'canonical', href: resolved.canonical })
-    }
-
-    // Alternate languages
-    resolved.alternates.forEach((alt) => {
-      link.push({ rel: 'alternate', href: alt.href, hreflang: alt.hreflang })
-    })
-
-    // Build scripts (JSON-LD)
-    const schemas = overrides?.schemas ?? getSchema()
-    const script: HeadInput['script'] = schemas.map((schema) => ({
-      type: 'application/ld+json',
-      children: JSON.stringify(schema),
-    }))
-
-    // Apply via useHead
-    useHead({
-      title,
-      meta,
-      link,
-      script,
-    })
-  }
-
-  return {
-    config,
-    applyHead,
-    getSchema,
-    getCanonical,
-    hasBuildTimeSeo,
-  }
-}
-
-/**
- * Create a typed useSEO function with site-specific defaults.
- * Useful for creating a site-wide wrapper.
- *
- * @example
- * ```ts
- * // composables/useSiteSeo.ts
- * import { createSiteSEO } from '@duffcloudservices/cms'
- *
- * export const useSiteSeo = createSiteSEO({
- *   siteName: 'My Site',
- *   siteUrl: 'https://example.com'
- * })
- * ```
- */
-export function createSiteSEO(
-  _siteDefaults: Partial<GlobalSeoConfig>
-): (pageSlug: string, pagePath?: string) => UseSeoReturn {
-  return function siteUseSEO(pageSlug: string, pagePath?: string): UseSeoReturn {
-    // Note: siteDefaults would be used if we needed to override at runtime
-    // but build-time injection handles this via dcsSeoPlugin
-    return useSEO(pageSlug, pagePath)
-  }
-}
+/**
+ * useSEO Composable
+ *
+ * Provides SEO configuration with build-time injection support from .dcs/seo.yaml.
+ * Generates meta tags, Open Graph, Twitter Cards, and JSON-LD structured data.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useSEO } from '@duffcloudservices/cms'
+ *
+ * const { applyHead, getSchema, config } = useSEO('home')
+ *
+ * // Apply all meta tags
+ * applyHead()
+ *
+ * // Or customize before applying
+ * applyHead({
+ *   title: 'Custom Override Title',
+ *   schemas: [...getSchema(), customSchema]
+ * })
+ * </script>
+ * ```
+ */
+
+import { computed, type ComputedRef } from 'vue'
+import { useHead } from '@unhead/vue'
+import type {
+  SeoConfiguration,
+  GlobalSeoConfig,
+  SeoOpenGraphConfig,
+  SeoTwitterConfig,
+  SeoSchemaConfig,
+  ResolvedPageSeo,
+  UseSeoReturn,
+  HeadOverrides,
+} from '../types/seo'
+
+// Declare the global injected by dcsSeoPlugin
+declare const __DCS_SEO__: SeoConfiguration | undefined
+
+/**
+ * Safely get build-time SEO configuration.
+ * Returns undefined if not available (no seo.yaml or plugin not configured).
+ */
+function getBuildTimeSeo(): SeoConfiguration | undefined {
+  try {
+    if (typeof __DCS_SEO__ !== 'undefined' && __DCS_SEO__ !== null) {
+      return __DCS_SEO__
+    }
+  } catch {
+    // __DCS_SEO__ not defined - that's fine, use defaults
+  }
+  return undefined
+}
+
+// =============================================================================
+// Meta Tag Generation Utilities
+// =============================================================================
+
+interface HeadInput {
+  title?: string
+  titleTemplate?: string | ((title: string) => string)
+  meta?: Array<{ name?: string; property?: string; content: string }>
+  link?: Array<{ rel: string; href: string; hreflang?: string }>
+  script?: Array<{ type: string; children: string }>
+}
+
+/**
+ * Generate Open Graph meta tags from config
+ */
+function generateOpenGraphMeta(
+  og: SeoOpenGraphConfig,
+  global: GlobalSeoConfig,
+  pageTitle: string,
+  pageDescription: string,
+  canonical: string
+): Array<{ property: string; content: string }> {
+  const tags: Array<{ property: string; content: string }> = []
+
+  tags.push({ property: 'og:title', content: og.title || pageTitle })
+  tags.push({ property: 'og:description', content: og.description || pageDescription })
+  tags.push({ property: 'og:url', content: og.url || canonical })
+  tags.push({ property: 'og:type', content: og.type || 'website' })
+
+  const image = og.image || global.images?.ogDefault
+  if (image) {
+    tags.push({ property: 'og:image', content: image })
+    if (og.imageAlt || pageTitle) {
+      tags.push({ property: 'og:image:alt', content: og.imageAlt || pageTitle })
+    }
+    if (og.imageWidth) {
+      tags.push({ property: 'og:image:width', content: String(og.imageWidth) })
+    }
+    if (og.imageHeight) {
+      tags.push({ property: 'og:image:height', content: String(og.imageHeight) })
+    }
+  }
+
+  if (global.siteName) {
+    tags.push({ property: 'og:site_name', content: global.siteName })
+  }
+
+  if (global.locale) {
+    tags.push({ property: 'og:locale', content: global.locale })
+  }
+
+  // Article-specific tags
+  if (og.type === 'article') {
+    if (og.publishedTime) {
+      tags.push({ property: 'article:published_time', content: og.publishedTime })
+    }
+    if (og.modifiedTime) {
+      tags.push({ property: 'article:modified_time', content: og.modifiedTime })
+    }
+    if (og.author) {
+      tags.push({ property: 'article:author', content: og.author })
+    }
+    if (og.section) {
+      tags.push({ property: 'article:section', content: og.section })
+    }
+    if (og.tags) {
+      og.tags.forEach((tag) => {
+        tags.push({ property: 'article:tag', content: tag })
+      })
+    }
+  }
+
+  return tags
+}
+
+/**
+ * Generate Twitter Card meta tags from config
+ */
+function generateTwitterMeta(
+  twitter: SeoTwitterConfig,
+  global: GlobalSeoConfig,
+  pageTitle: string,
+  pageDescription: string
+): Array<{ name: string; content: string }> {
+  const tags: Array<{ name: string; content: string }> = []
+
+  tags.push({ name: 'twitter:card', content: twitter.card || 'summary_large_image' })
+  tags.push({ name: 'twitter:title', content: twitter.title || pageTitle })
+  tags.push({ name: 'twitter:description', content: twitter.description || pageDescription })
+
+  const image = twitter.image || global.images?.twitterDefault
+  if (image) {
+    tags.push({ name: 'twitter:image', content: image })
+    if (twitter.imageAlt || pageTitle) {
+      tags.push({ name: 'twitter:image:alt', content: twitter.imageAlt || pageTitle })
+    }
+  }
+
+  const site = twitter.site || global.social?.twitter
+  if (site) {
+    tags.push({ name: 'twitter:site', content: site.startsWith('@') ? site : `@${site}` })
+  }
+
+  if (twitter.creator) {
+    tags.push({
+      name: 'twitter:creator',
+      content: twitter.creator.startsWith('@') ? twitter.creator : `@${twitter.creator}`,
+    })
+  }
+
+  return tags
+}
+
+/**
+ * Generate JSON-LD script content from schemas
+ */
+function generateJsonLd(schemas: SeoSchemaConfig[], global: GlobalSeoConfig): object[] {
+  return schemas.map((schema) => {
+    const base: Record<string, unknown> = {
+      '@context': 'https://schema.org',
+      '@type': schema.type,
+    }
+
+    // Merge properties
+    if (schema.properties) {
+      Object.assign(base, schema.properties)
+    }
+
+    // Auto-populate common properties from global config
+    if (schema.type === 'WebSite' && global.siteUrl && !base.url) {
+      base.url = global.siteUrl
+    }
+    if (schema.type === 'WebSite' && global.siteName && !base.name) {
+      base.name = global.siteName
+    }
+
+    return base
+  })
+}
+
+/**
+ * Resolve page SEO by merging global defaults with page-specific config
+ */
+function resolvePageSeo(
+  pageSlug: string,
+  pagePath: string | undefined,
+  seoConfig: SeoConfiguration | undefined
+): ResolvedPageSeo {
+  const global = seoConfig?.global ?? {}
+  const page = seoConfig?.pages?.[pageSlug] ?? {}
+
+  // Build canonical URL
+  let canonical = page.canonical || ''
+  if (!canonical && global.siteUrl) {
+    const path = pagePath ?? (pageSlug === 'home' ? '/' : `/${pageSlug}`)
+    canonical = `${global.siteUrl.replace(/\/$/, '')}${path}`
+  }
+
+  // Build title
+  let title = page.title || global.defaultTitle || pageSlug
+  if (!page.noTitleTemplate && global.titleTemplate) {
+    title = global.titleTemplate.replace('%s', title)
+  }
+
+  // Merge Open Graph
+  const openGraph: ResolvedPageSeo['openGraph'] = {
+    type: page.openGraph?.type || 'website',
+    title: page.openGraph?.title || page.title || global.defaultTitle || '',
+    description: page.openGraph?.description || page.description || global.defaultDescription || '',
+    ...page.openGraph,
+  }
+
+  // Merge Twitter
+  const twitter: ResolvedPageSeo['twitter'] = {
+    card: page.twitter?.card || 'summary_large_image',
+    ...page.twitter,
+  }
+
+  // Combine schemas (global + page)
+  const schemas = [...(global.schemas ?? []), ...(page.schemas ?? [])]
+
+  return {
+    title,
+    description: page.description || global.defaultDescription || '',
+    canonical,
+    robots: page.robots || global.robots || 'index, follow',
+    openGraph,
+    twitter,
+    schemas,
+    alternates: page.alternates ?? [],
+  }
+}
+
+/**
+ * useSEO composable for DCS-managed SEO configuration.
+ *
+ * @param pageSlug - Page slug matching entry in seo.yaml
+ * @param pagePath - Optional page path for canonical URL generation
+ * @returns SEO helpers and state
+ */
+export function useSEO(pageSlug: string, pagePath?: string): UseSeoReturn {
+  const seoConfig = getBuildTimeSeo()
+  const hasBuildTimeSeo = seoConfig !== undefined
+
+  // Computed resolved config
+  const config: ComputedRef<ResolvedPageSeo> = computed(() =>
+    resolvePageSeo(pageSlug, pagePath, seoConfig)
+  )
+
+  /**
+   * Get JSON-LD schema objects for the page
+   */
+  function getSchema(): object[] {
+    return generateJsonLd(config.value.schemas, seoConfig?.global ?? {})
+  }
+
+  /**
+   * Get canonical URL for the page
+   */
+  function getCanonical(): string {
+    return config.value.canonical
+  }
+
+  /**
+   * Apply all meta tags via useHead
+   */
+  function applyHead(overrides?: HeadOverrides): void {
+    const resolved = config.value
+    const global = seoConfig?.global ?? {}
+
+    const title = overrides?.title ?? resolved.title
+    const description = overrides?.description ?? resolved.description
+
+    // Build meta tags
+    const meta: HeadInput['meta'] = []
+
+    // Basic meta
+    meta.push({ name: 'description', content: description })
+    if (resolved.robots) {
+      meta.push({ name: 'robots', content: resolved.robots })
+    }
+
+    // Verification codes
+    if (global.verification?.google) {
+      meta.push({ name: 'google-site-verification', content: global.verification.google })
+    }
+    if (global.verification?.bing) {
+      meta.push({ name: 'msvalidate.01', content: global.verification.bing })
+    }
+
+    // Open Graph
+    const ogMeta = generateOpenGraphMeta(
+      resolved.openGraph,
+      global,
+      title,
+      description,
+      resolved.canonical
+    )
+    meta.push(...ogMeta.map((t) => ({ property: t.property, content: t.content })))
+
+    // Twitter
+    const twitterMeta = generateTwitterMeta(resolved.twitter, global, title, description)
+    meta.push(...twitterMeta.map((t) => ({ name: t.name, content: t.content })))
+
+    // Additional overrides
+    if (overrides?.meta) {
+      meta.push(...overrides.meta)
+    }
+
+    // Build links
+    const link: HeadInput['link'] = []
+
+    // Canonical
+    if (resolved.canonical) {
+      link.push({ rel: 'canonical', href: resolved.canonical })
+    }
+
+    // Alternate languages
+    resolved.alternates.forEach((alt) => {
+      link.push({ rel: 'alternate', href: alt.href, hreflang: alt.hreflang })
+    })
+
+    // Build scripts (JSON-LD)
+    const schemas = overrides?.schemas ?? getSchema()
+    const script: HeadInput['script'] = schemas.map((schema) => ({
+      type: 'application/ld+json',
+      children: JSON.stringify(schema),
+    }))
+
+    // Apply via useHead
+    useHead({
+      title,
+      meta,
+      link,
+      script,
+    })
+  }
+
+  return {
+    config,
+    applyHead,
+    getSchema,
+    getCanonical,
+    hasBuildTimeSeo,
+  }
+}
+
+/**
+ * Create a typed useSEO function with site-specific defaults.
+ * Useful for creating a site-wide wrapper.
+ *
+ * @example
+ * ```ts
+ * // composables/useSiteSeo.ts
+ * import { createSiteSEO } from '@duffcloudservices/cms'
+ *
+ * export const useSiteSeo = createSiteSEO({
+ *   siteName: 'My Site',
+ *   siteUrl: 'https://example.com'
+ * })
+ * ```
+ */
+export function createSiteSEO(
+  _siteDefaults: Partial<GlobalSeoConfig>
+): (pageSlug: string, pagePath?: string) => UseSeoReturn {
+  return function siteUseSEO(pageSlug: string, pagePath?: string): UseSeoReturn {
+    // Note: siteDefaults would be used if we needed to override at runtime
+    // but build-time injection handles this via dcsSeoPlugin
+    return useSEO(pageSlug, pagePath)
+  }
+}