@duffcloudservices/cms 0.3.17 → 0.5.0

package/dist/vitepressTransform-DAhmD_YQ.d.ts

@@ -0,0 +1,471 @@
+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;
+    }>;
+}
+
+/**
+ * Build-time SEO for VitePress static-site generation.
+ *
+ * VitePress 1.6 does **not** use `unhead`, so the runtime `useSEO`/`applyHead`
+ * composable is a no-op against the SSG HTML. The SSG-correct sink is the
+ * `transformPageData(pageData)` build hook: writing `<meta>`/`<link>`/JSON-LD
+ * into `pageData.frontmatter.head` (VitePress bakes those into the rendered
+ * `<head>`) and overwriting `pageData.title` / `pageData.description` (VitePress
+ * renders the `<title>` — via `titleTemplate` — and the `description` meta from
+ * those two fields).
+ *
+ * This factory generalises the bespoke `buildSeoHead`/`transformPageData` that
+ * shipped inline in a site's `.vitepress/config.ts`. It reuses the shared,
+ * framework-agnostic resolver (`resolvePageSeo`, `generateOpenGraphMeta`,
+ * `generateTwitterMeta`, `generateJsonLd`) for global + page meta / OG / Twitter
+ * / canonical and the global JSON-LD knowledge graph, and delegates **page-type
+ * JSON-LD** (e.g. Article / Place / CollectionPage / Service / FAQPage +
+ * BreadcrumbList) to a *pluggable* rule set the site supplies. None of the
+ * real-estate (or any other vertical's) schema logic lives in this package — it
+ * is all site CONFIG.
+ *
+ * It is the VitePress counterpart to the Vue-SPA per-route emitter in
+ * `dcsSeoPlugin({ emitStaticHtml: true })`; both produce identical global
+ * meta/OG/Twitter/JSON-LD from the same `seo.yaml` via the shared resolver.
+ *
+ * @example
+ * ```ts
+ * // docs/.vitepress/config.ts
+ * import { createSeoTransformPageData } from '@duffcloudservices/cms/plugins'
+ * import seoConfig from '../../.dcs/seo.yaml'
+ *
+ * export default defineConfig({
+ *   transformPageData: createSeoTransformPageData({
+ *     seoConfig,
+ *     pageTypeRules: [
+ *       { match: (ctx) => ctx.route.startsWith('/blogs/'), build: (ctx) => [ ... ] },
+ *       // ...Place / CollectionPage / Service / FAQPage rules
+ *     ],
+ *   }),
+ * })
+ * ```
+ */
+
+/**
+ * A VitePress `head` entry. Mirrors VitePress's `HeadConfig` without taking a
+ * dependency on the `vitepress` package (which is not a dependency of this
+ * library). The tuple forms are:
+ *   ['meta', { name|property, content }]
+ *   ['link', { rel, href, ... }]
+ *   ['script', { type: 'application/ld+json' }, '<serialised json>']
+ */
+type VitePressHeadConfig = [string, Record<string, string>] | [string, Record<string, string>, string];
+/**
+ * The minimal slice of VitePress's `PageData` this factory reads and mutates.
+ * Typed structurally so callers can pass VitePress's real `PageData` without a
+ * cast and without this package importing `vitepress`.
+ */
+interface VitePressPageData {
+    /** Source-relative path, e.g. `index.md`, `blogs/my-post.md`. */
+    relativePath: string;
+    /** Dynamic-route params (e.g. `{ topic: 'home-buying' }`). */
+    params?: Record<string, unknown>;
+    /** Page frontmatter; `head` is appended to here. */
+    frontmatter: Record<string, any>;
+    /** VitePress page title (drives `<title>` via `titleTemplate`). */
+    title?: string;
+    /** VitePress page description (drives the `description` meta). */
+    description?: string;
+    [key: string]: unknown;
+}
+/**
+ * Context handed to the site's page-type rules and resolver hooks. Everything a
+ * site needs to derive its title/description/og/schemas for one page, computed
+ * once per page by the factory.
+ */
+interface SeoPageContext {
+    /** Route path, e.g. `/`, `/blogs/my-post`, `/locations/birmingham`. */
+    route: string;
+    /** Slug: `'home'` for `/`, otherwise the route without its leading slash. */
+    slug: string;
+    /** Absolute canonical URL for this route. */
+    canonical: string;
+    /** Normalised site base URL (no trailing slash), e.g. `https://example.com`. */
+    siteUrl: string;
+    /** The page's frontmatter (read-only convenience; same object as pageData). */
+    frontmatter: Record<string, any>;
+    /** The resolved global SEO config block. */
+    global: GlobalSeoConfig;
+    /** The full VitePress page data (for rules that need more than the above). */
+    pageData: VitePressPageData;
+}
+/**
+ * The resolved per-page title / description / OG type a site may override.
+ * Returned by the optional `resolvePage` hook so a site can apply its own
+ * per-page-type title precedence (e.g. "{City} Luxury Real Estate") and decide
+ * whether that title should win over VitePress's `titleTemplate`.
+ */
+interface ResolvedPageOverrides {
+    /**
+     * The page title. When `setPageTitle` is true this is written to
+     * `pageData.title` (VitePress then applies `titleTemplate`).
+     */
+    title?: string;
+    /**
+     * When true, `title` is written back to `pageData.title`. Leave false for
+     * pages whose frontmatter title should remain authoritative (e.g. blog posts
+     * that already carry a good `<h1>`/title).
+     */
+    setPageTitle?: boolean;
+    /** The meta description. Written to `pageData.description` when truthy. */
+    description?: string;
+    /** Open Graph type override (e.g. `'article'`, `'profile'`). */
+    ogType?: SeoOpenGraphConfig['type'];
+    /** Open Graph image URL override (e.g. a post's header image). */
+    ogImage?: string;
+    /** Keywords override (comma-separated) for the `keywords` meta. */
+    keywords?: string;
+    /**
+     * Open Graph title override. Defaults to `title` so og:title tracks <title>.
+     */
+    ogTitle?: string;
+    /**
+     * Open Graph description override. Defaults to `description`.
+     */
+    ogDescription?: string;
+}
+/** A single pluggable page-type rule: when `match` is true, emit `build`. */
+interface SeoPageTypeRule {
+    /** Return true when this rule applies to the page (by route/slug/etc.). */
+    match: (ctx: SeoPageContext) => boolean;
+    /** Build the page-type JSON-LD objects to emit (already plain objects). */
+    build: (ctx: SeoPageContext) => Array<Record<string, unknown>>;
+}
+interface CreateSeoTransformPageDataOptions {
+    /** The parsed `.dcs/seo.yaml` (global graph + per-page meta). */
+    seoConfig: SeoConfiguration | undefined;
+    /**
+     * Pluggable page-type rules. Evaluated in order; **every** matching rule's
+     * `build` output is emitted (so a route can contribute both a primary schema
+     * and a BreadcrumbList from one rule, or be matched by several). The
+     * real-estate BlogPosting / Place / CollectionPage / Service / FAQPage logic
+     * is supplied here by the site — never hardcoded in this package.
+     */
+    pageTypeRules?: SeoPageTypeRule[];
+    /**
+     * Optional hook to override per-page title / description / OG before tags are
+     * built — the site's title precedence and per-type description fallbacks.
+     * Receives the same context as the rules. Anything it omits falls back to the
+     * resolver / frontmatter defaults.
+     */
+    resolvePage?: (ctx: SeoPageContext) => ResolvedPageOverrides | undefined;
+    /**
+     * Map a `relativePath` (+ params) to a route. Defaults to a VitePress-correct
+     * implementation: `index` becomes `/`, a trailing `/index` is dropped, `.md`
+     * is stripped, and dynamic `[name]` segments are substituted from
+     * `pageData.params`. Override only for unusual routing.
+     */
+    relativePathToRoute?: (relativePath: string, params?: Record<string, unknown>) => string;
+    /**
+     * Emit a `<meta name="keywords">` from the resolved/overridden keywords.
+     * Default true (parity with the bespoke KDH emitter, which emitted keywords).
+     */
+    includeKeywords?: boolean;
+    /** Enable debug logging of the emitted head per page. */
+    debug?: boolean;
+}
+/** Default VitePress route derivation (matches the bespoke KDH helper). */
+declare function defaultRelativePathToRoute(relativePath: string, params?: Record<string, unknown>): string;
+/**
+ * Build just the SEO head tuples for a page (no `pageData` mutation). Exposed
+ * separately so it is unit-testable without a VitePress `pageData` round-trip
+ * and reusable by callers that manage the `head`/`title` sinks themselves.
+ *
+ * @returns `{ head, title, description }` — the head tuples to append, and the
+ *   final title/description (already overridden) the caller should write to
+ *   `pageData` when `applyTitle`/`applyDescription` are appropriate.
+ */
+declare function buildVitePressSeoHead(pageData: VitePressPageData, options: CreateSeoTransformPageDataOptions): {
+    head: VitePressHeadConfig[];
+    title?: string;
+    description?: string;
+    setPageTitle: boolean;
+};
+/**
+ * Create a VitePress `transformPageData(pageData)` function that bakes DCS SEO
+ * (global meta/OG/Twitter/canonical + global JSON-LD graph + pluggable
+ * page-type JSON-LD) into the SSG `<head>`.
+ *
+ * Mutations performed on `pageData`:
+ *   - **`frontmatter.head`** — the resolved tags are *appended* to any existing
+ *     `head` (so site-level `head` config is preserved).
+ *   - **`description`** — set to the resolved/overridden description so
+ *     VitePress emits exactly one `description` meta (no duplicate; we do not
+ *     push our own description meta).
+ *   - **`title`** — set only when the site's `resolvePage` hook returns
+ *     `setPageTitle: true` for this page, mirroring the bespoke behaviour where
+ *     seo.yaml/per-type titles are authoritative but a post's frontmatter title
+ *     is left intact.
+ *
+ * Defensive: never throws (a failure logs a warning and leaves `pageData`
+ * untouched), so SEO can never break a production VitePress build.
+ */
+declare function createSeoTransformPageData(options: CreateSeoTransformPageDataOptions): (pageData: VitePressPageData) => void;
+
+export { type CreateSeoTransformPageDataOptions as C, type GlobalSeoConfig as G, type HeadOverrides as H, type PageSeoConfig as P, type ResolvedPageSeo as R, type SeoConfiguration as S, type UseSeoReturn as U, type VitePressPageData as V, type SeoSchemaConfig as a, type SeoOpenGraphConfig as b, type SeoTwitterConfig as c, createSeoTransformPageData as d, buildVitePressSeoHead as e, defaultRelativePathToRoute as f, type SeoPageContext as g, type SeoPageTypeRule as h, type ResolvedPageOverrides as i, type VitePressHeadConfig as j, type SeoAuthorConfig as k, type SeoSocialConfig as l, type SeoImagesConfig as m, type SeoAlternateConfig as n, type SeoVerificationConfig as o, type UseSeoConfig as p };

package/package.json

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