@duffcloudservices/cms 0.3.17 → 0.4.0

package/dist/seo-DsJjfI1p.d.ts

@@ -0,0 +1,267 @@
+import * as vue from 'vue';
+
+/**
+ * Types for .dcs/seo.yaml structure
+ * Matches contracts/generated/schemas/seo.json
+ */
+/**
+ * Root structure of .dcs/seo.yaml
+ */
+interface SeoConfiguration {
+    /** Schema version */
+    version: number;
+    /** ISO timestamp of last update */
+    lastUpdated?: string;
+    /** Email or identifier of who made the update */
+    updatedBy?: string;
+    /** Global/site-wide SEO defaults */
+    global?: GlobalSeoConfig;
+    /** Page-specific SEO configurations keyed by page slug */
+    pages?: Record<string, PageSeoConfig>;
+}
+/**
+ * Global/site-wide SEO configuration
+ */
+interface GlobalSeoConfig {
+    /** Site name used in titles and structured data */
+    siteName?: string;
+    /** Base URL of the site (e.g., https://example.com) */
+    siteUrl?: string;
+    /** Locale for Open Graph (e.g., en_US) */
+    locale?: string;
+    /** Default page title */
+    defaultTitle?: string;
+    /** Default meta description */
+    defaultDescription?: string;
+    /** Title template with %s placeholder (e.g., "%s | Site Name") */
+    titleTemplate?: string;
+    /** Author information for structured data */
+    author?: SeoAuthorConfig;
+    /** Social media handles */
+    social?: SeoSocialConfig;
+    /** Default images for social sharing */
+    images?: SeoImagesConfig;
+    /** Default robots directive (e.g., "index, follow") */
+    robots?: string;
+    /** Global JSON-LD schemas (Organization, WebSite, etc.) */
+    schemas?: SeoSchemaConfig[];
+    /** Search engine verification codes */
+    verification?: SeoVerificationConfig;
+}
+/**
+ * Page-specific SEO configuration
+ */
+interface PageSeoConfig {
+    /** Page title */
+    title?: string;
+    /** Meta description */
+    description?: string;
+    /** Meta keywords (comma-separated) */
+    keywords?: string;
+    /** Canonical URL */
+    canonical?: string;
+    /** Page-specific robots directive */
+    robots?: string;
+    /** Open Graph configuration */
+    openGraph?: SeoOpenGraphConfig;
+    /** Twitter Card configuration */
+    twitter?: SeoTwitterConfig;
+    /** Page-specific JSON-LD schemas */
+    schemas?: SeoSchemaConfig[];
+    /** Alternate language links */
+    alternates?: SeoAlternateConfig[];
+    /** If true, don't apply titleTemplate to this page */
+    noTitleTemplate?: boolean;
+}
+/**
+ * Author information for structured data
+ */
+interface SeoAuthorConfig {
+    /** Author name */
+    name?: string;
+    /** Author email */
+    email?: string;
+    /** Author image URL */
+    image?: string;
+    /** Job title */
+    jobTitle?: string;
+    /** Social profile URLs */
+    sameAs?: string[];
+}
+/**
+ * Social media handles
+ */
+interface SeoSocialConfig {
+    /** Twitter handle (without @) */
+    twitter?: string;
+    /** LinkedIn company or profile slug */
+    linkedin?: string;
+    /** GitHub username */
+    github?: string;
+    /** Facebook page name */
+    facebook?: string;
+    /** Instagram username */
+    instagram?: string;
+    /** YouTube channel */
+    youtube?: string;
+}
+/**
+ * Default images for social sharing
+ */
+interface SeoImagesConfig {
+    /** Logo image URL */
+    logo?: string;
+    /** Default Open Graph image */
+    ogDefault?: string;
+    /** Default Twitter Card image */
+    twitterDefault?: string;
+    /** Favicon URL */
+    favicon?: string;
+}
+/**
+ * Open Graph meta configuration
+ */
+interface SeoOpenGraphConfig {
+    /** OG title (defaults to page title) */
+    title?: string;
+    /** OG description (defaults to page description) */
+    description?: string;
+    /** OG image URL */
+    image?: string;
+    /** Alt text for OG image */
+    imageAlt?: string;
+    /** OG image width in pixels */
+    imageWidth?: number;
+    /** OG image height in pixels */
+    imageHeight?: number;
+    /** OG type */
+    type?: 'website' | 'article' | 'profile' | 'book' | 'music.song' | 'music.album' | 'video.movie' | 'video.episode' | 'video.tv_show' | 'video.other';
+    /** OG URL (defaults to canonical) */
+    url?: string;
+    /** Article published time (ISO 8601) */
+    publishedTime?: string;
+    /** Article modified time (ISO 8601) */
+    modifiedTime?: string;
+    /** Article author */
+    author?: string;
+    /** Article section/category */
+    section?: string;
+    /** Article tags */
+    tags?: string[];
+}
+/**
+ * Twitter Card configuration
+ */
+interface SeoTwitterConfig {
+    /** Card type */
+    card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+    /** Twitter title */
+    title?: string;
+    /** Twitter description */
+    description?: string;
+    /** Twitter image URL */
+    image?: string;
+    /** Alt text for Twitter image */
+    imageAlt?: string;
+    /** Site's Twitter handle (without @) */
+    site?: string;
+    /** Content creator's Twitter handle (without @) */
+    creator?: string;
+}
+/**
+ * JSON-LD schema configuration
+ */
+interface SeoSchemaConfig {
+    /** Schema.org type (e.g., "WebSite", "Organization", "Article") */
+    type: string;
+    /** Schema properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Alternate language link
+ */
+interface SeoAlternateConfig {
+    /** Language code (e.g., "en", "es", "x-default") */
+    hreflang: string;
+    /** URL of alternate version */
+    href: string;
+}
+/**
+ * Search engine verification codes
+ */
+interface SeoVerificationConfig {
+    /** Google Search Console verification code */
+    google?: string;
+    /** Bing Webmaster Tools verification code */
+    bing?: string;
+    /** DuckDuckGo verification (reserved for future use) */
+    duckduckgo?: string;
+}
+/**
+ * Resolved page SEO configuration (after merging global + page)
+ */
+interface ResolvedPageSeo {
+    /** Final page title */
+    title: string;
+    /** Final meta description */
+    description: string;
+    /** Page keywords (comma-separated), if configured */
+    keywords?: string;
+    /** Final canonical URL */
+    canonical: string;
+    /** Final robots directive */
+    robots: string;
+    /** Merged Open Graph configuration */
+    openGraph: Required<Pick<SeoOpenGraphConfig, 'title' | 'description' | 'type'>> & SeoOpenGraphConfig;
+    /** Merged Twitter configuration */
+    twitter: Required<Pick<SeoTwitterConfig, 'card'>> & SeoTwitterConfig;
+    /** All schemas (global + page) */
+    schemas: SeoSchemaConfig[];
+    /** Alternate links */
+    alternates: SeoAlternateConfig[];
+}
+/**
+ * Configuration for useSEO composable
+ */
+interface UseSeoConfig {
+    /** Page slug matching entry in seo.yaml */
+    pageSlug: string;
+    /** Optional page path for canonical URL generation */
+    pagePath?: string;
+}
+/**
+ * Return type of useSEO composable
+ */
+interface UseSeoReturn {
+    /** Computed page SEO configuration */
+    config: vue.ComputedRef<ResolvedPageSeo>;
+    /** Apply all meta tags via useHead */
+    applyHead: (overrides?: HeadOverrides) => void;
+    /** Get JSON-LD schema objects for the page */
+    getSchema: () => object[];
+    /** Get canonical URL for the page */
+    getCanonical: () => string;
+    /** Whether SEO config was loaded from build-time */
+    hasBuildTimeSeo: boolean;
+}
+/**
+ * Overrides that can be passed to applyHead
+ */
+interface HeadOverrides {
+    /** Override title */
+    title?: string;
+    /** Override description */
+    description?: string;
+    /** Override keywords meta tag */
+    keywords?: string;
+    /** Additional or replacement schemas */
+    schemas?: object[];
+    /** Additional meta tags */
+    meta?: Array<{
+        name?: string;
+        property?: string;
+        content: string;
+    }>;
+}
+
+export type { GlobalSeoConfig as G, HeadOverrides as H, PageSeoConfig as P, ResolvedPageSeo as R, SeoConfiguration as S, UseSeoReturn as U, SeoSchemaConfig as a, SeoOpenGraphConfig as b, SeoTwitterConfig as c, SeoAuthorConfig as d, SeoSocialConfig as e, SeoImagesConfig as f, SeoAlternateConfig as g, SeoVerificationConfig as h, UseSeoConfig as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duffcloudservices/cms",
-  "version": "0.3.17",
+  "version": "0.4.0",
   "description": "Vue 3 composables and Vite plugins for DCS CMS integration",
   "type": "module",
   "exports": {

package/src/composables/useSEO.ts

@@ -4,6 +4,10 @@
  * Provides SEO configuration with build-time injection support from .dcs/seo.yaml.
  * Generates meta tags, Open Graph, Twitter Cards, and JSON-LD structured data.
  *
+ * The actual tag resolution lives in the framework-agnostic `../seo/headTags`
+ * module so that the build-time static-HTML emitter (`dcsSeoPlugin`) produces
+ * byte-identical output. This composable is a thin Vue/unhead wrapper over it.
+ *
  * @example
  * ```vue
  * <script setup lang="ts">
@@ -28,13 +32,11 @@ import { useHead } from '@unhead/vue'
 import type {
   SeoConfiguration,
   GlobalSeoConfig,
-  SeoOpenGraphConfig,
-  SeoTwitterConfig,
-  SeoSchemaConfig,
   ResolvedPageSeo,
   UseSeoReturn,
   HeadOverrides,
 } from '../types/seo'
+import { buildHeadTags, resolvePageSeo, generateJsonLd } from '../seo/headTags'
 
 // Declare the global injected by dcsSeoPlugin
 declare const __DCS_SEO__: SeoConfiguration | undefined
@@ -54,199 +56,6 @@ function getBuildTimeSeo(): SeoConfiguration | undefined {
   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.
  *
@@ -278,78 +87,31 @@ export function useSEO(pageSlug: string, pagePath?: string): UseSeoReturn {
   }
 
   /**
-   * Apply all meta tags via useHead
+   * Apply all meta tags via useHead.
+   *
+   * Delegates to the shared `buildHeadTags` resolver so the emitted tags match
+   * the build-time static-HTML emitter exactly. Keywords are intentionally not
+   * emitted at runtime (historical behaviour), so `includeKeywords` is omitted.
    */
   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 })
+    const { title, meta, link, script } = buildHeadTags(pageSlug, pagePath, seoConfig, {
+      title: overrides?.title,
+      description: overrides?.description,
+      keywords: overrides?.keywords,
+      schemas: overrides?.schemas,
+      meta: overrides?.meta,
     })
 
-    // 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
+    // Apply via useHead. The shared resolver returns framework-agnostic tag
+    // shapes (HeadMetaTag/HeadLinkTag/HeadScriptTag); unhead's input types are
+    // structurally compatible but add an open-ended `data-*` index signature,
+    // so we hand them over via useHead's Head input type. Runtime is identical.
     useHead({
       title,
       meta,
       link,
       script,
-    })
+    } as unknown as Parameters<typeof useHead>[0])
   }
 
   return {