@xenterprises/nuxt-x-marketing 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to `@xenterprises/nuxt-x-marketing` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.3.0] - 2026-07-24
+
+### BREAKING
+
+- **Blog migrated from Builder.io to Nuxt Content.** Consumers that relied on `NUXT_PUBLIC_BUILDERIO_KEY` and Builder models must migrate posts to `content/blog/*.md` and install the Content peer dependencies.
+- **Default app shell rewritten to a config-driven shell.** The layer's `app/app.vue` (previously a hardcoded demo referencing non-existent `XMarkNavbar`/`XMarkFooter`, rendering no navbar/footer) now renders `XHeaderNav` + `XFooter` from `xMarketing.header`/`footer` config plus the consent banner. Consumers without their own `app/app.vue` will see the rendered shell change; the hardcoded newsletter section, dead demo links, and `/logo-white.svg`/`/logo-dark.svg` fallbacks are gone.
+- **`xMarketing.name`/`url` defaults changed from placeholders to `undefined`** and both keys are now live: `name` drives the shell title template and `og:site_name` (page titles gain a `| <name>` suffix when set), `url` drives the home page `og:url`. Consumers reading the old placeholder defaults from `appConfig` now get `undefined`.
+
+### Added
+
+- Config-driven default shell with `xMarketing` opt-out switches for header, footer, and consent banner.
+- `xMarketing.blog.active` opt-out on the shipped blog pages.
+- `xMarketing.name`/`url` wired into shell SEO defaults (title template, `og:site_name`, `og:url`).
+- Playground e2e smoke suite (`test:e2e`, plan 17) and lint quality gate.
+- Consumer-minimal quickstart docs and plan-18 batteries-included audit.
+
+### Changed
+
+- Exported named `XMarketingConfig` interface for typed `app.config.ts` (plan-21 config-typing convention).
+- Peer dependency ranges tightened to caret bounds.
+
+### Fixed
+
+- Widened `better-sqlite3` peer range to `^11.0.0 || ^12.0.0`.
+- Default home page references real component names; `UToggle` replaced with `USwitch`.
+- Repaired red gates: added `test:run`/`test:coverage` aliases and pinned `vue`.
+- Test suite: fixed stale hero title assertion and scoped `h1` queries to main content.

package/README.md

@@ -31,86 +31,56 @@ export default defineNuxtConfig({
 
 ## Quick Start
 
-### Basic App Layout
+### What the consumer writes
 
-Create your `app.vue` with Navbar, Newsletter, and Footer:
+The layer is batteries-included: it ships a default app shell (navbar + footer + cookie-consent banner) and default pages (`/`, `/blog`, `/blog/[...slug]`). You do **not** write an `app.vue` — configure the shell in `app/app.config.ts` under the `xMarketing` namespace (it must live in `app/`, not the project root):
 
-```vue
-<template>
-  <div class="min-h-screen flex flex-col">
-    <XMarkNavbar
-      :links="navLinks"
-      :logo-light="'/logo-white.svg'"
-      :logo-dark="'/logo-dark.svg'"
-      logo-alt="Company"
-    >
-      <template #actions>
-        <UButton variant="ghost" color="neutral">Sign In</UButton>
-        <UButton color="primary">Get Started</UButton>
-      </template>
-    </XMarkNavbar>
-
-    <main class="flex-grow">
-      <NuxtPage />
-    </main>
-
-    <XMarkSection bg="subtle" padding="lg">
-      <XMarkNewsletter
-        title="Stay in the loop"
-        description="Get the latest updates delivered to your inbox."
-        @submit="handleNewsletterSubmit"
-      />
-    </XMarkSection>
+```javascript
+// app/app.config.ts
+export default defineAppConfig({
+  xMarketing: {
+    name: "Acme Inc",
+    url: "https://acme.com",
+    header: {
+      logo: { src: "/logo.svg", srcDark: "/logo-dark.svg", alt: "Acme" },
+      nav: {
+        links: [
+          { label: "Pricing", to: "/#pricing" },
+          { label: "Blog", to: "/blog" },
+        ],
+        buttons: [{ label: "Get Started", to: "/signup", color: "primary" }],
+      },
+    },
+    footer: {
+      logo: { src: "/logo.svg", alt: "Acme" },
+      body: "Building the future of modern software.",
+      socials: [
+        { name: "GitHub", url: "https://github.com/acme", icon: "i-lucide-github" },
+      ],
+      columns: [
+        {
+          headerLabel: "Product",
+          links: [{ label: "Blog", to: "/blog" }],
+        },
+      ],
+    },
+    blog: { active: true, title: "Blog" },
+    tracking: { gtmId: "GTM-XXXXXXX" }, // optional; fires only after consent
+  },
+});
+```
 
-    <XMarkFooter
-      :logo="'/logo-dark.svg'"
-      description="Building the future of modern software."
-      :social="socialLinks"
-      :columns="footerColumns"
-      :legal-links="legalLinks"
-    />
-  </div>
-</template>
+Blog posts are markdown in `content/blog/*.md` — re-declare the `blog` collection in your own `content.config.ts` so Nuxt Content binds it to your content dir (the layer's `.playground/content.config.ts` is the reference).
 
-<script setup>
-const navLinks = [
-  { label: "Features", to: "/#features" },
-  { label: "Pricing", to: "/pricing" },
-  { label: "Blog", to: "/blog" },
-];
-
-const socialLinks = [
-  { name: "Twitter", href: "https://twitter.com", icon: "i-lucide-twitter" },
-  { name: "GitHub", href: "https://github.com", icon: "i-lucide-github" },
-];
-
-const footerColumns = [
-  {
-    title: "Product",
-    links: [
-      { label: "Features", to: "/#features" },
-      { label: "Pricing", to: "/pricing" },
-    ],
-  },
-  {
-    title: "Company",
-    links: [
-      { label: "About", to: "/about" },
-      { label: "Blog", to: "/blog" },
-    ],
-  },
-];
+### Opting out of the defaults
 
-const legalLinks = [
-  { label: "Privacy Policy", to: "/privacy" },
-  { label: "Terms of Service", to: "/terms" },
-];
+Every shipped default has a switch or a standard Nuxt override:
 
-const handleNewsletterSubmit = (email) => {
-  console.log("Newsletter signup:", email);
-};
-</script>
-```
+- `xMarketing.header.active: false` — removes the default navbar from the shell
+- `xMarketing.footer.active: false` — removes the default footer
+- `xMarketing.consent.active: false` — removes the cookie-consent banner (tracking scripts then never fire)
+- `xMarketing.blog.active: false` — the shipped `/blog` pages 404
+- Replace the whole shell by shipping your own `app/app.vue`; replace any page by shipping the same path under `app/pages/` (standard Nuxt layer overriding)
 
 ### Example Landing Page
 
@@ -177,32 +147,28 @@ const pricingPlans = [
 
 ### Core Layout
 
-#### XMarkNavbar
+#### XMarkLayoutNavbar
 
-Fixed navigation header with transparent-to-solid scroll transition.
+Fixed navigation header with transparent-to-solid scroll transition. Falls back to `xMarketing.header` (logo, nav links, nav buttons) when props are omitted.
 
 ```vue
-<XMarkNavbar
+<XMarkLayoutNavbar
   :links="[{ label: 'Features', to: '/#features' }]"
-  logo-light="/logo-white.svg"
-  logo-dark="/logo-dark.svg"
-  logo-alt="Company"
+  :logo="{ src: '/logo.svg', srcDark: '/logo-dark.svg', alt: 'Company' }"
+  :buttons="[
+    { label: 'Sign In', to: '/login', variant: 'ghost' },
+    { label: 'Get Started', to: '/signup', color: 'primary' },
+  ]"
   :transparent="true"
   :scroll-threshold="100"
->
-  <template #actions>
-    <UButton variant="ghost">Sign In</UButton>
-    <UButton color="primary">Get Started</UButton>
-  </template>
-</XMarkNavbar>
+/>
 ```
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `links` | `Array` | `[]` | Navigation links `{ label, to }` |
-| `logoLight` | `String` | `''` | Logo for transparent/dark state |
-| `logoDark` | `String` | `''` | Logo for solid/light state |
-| `logoAlt` | `String` | `'Logo'` | Logo alt text |
+| `links` | `Array` | `xMarketing.header.nav.links` | Navigation links `{ label, to }` |
+| `logo` | `Object` | `xMarketing.header.logo` | Logo `{ src, srcDark?, alt? }` |
+| `buttons` | `Array` | `xMarketing.header.nav.buttons` | Action buttons `{ label, to, color?, variant?, icon? }` |
 | `transparent` | `Boolean` | `true` | Start transparent over hero |
 | `scrollThreshold` | `Number` | `100` | Pixels before transition |
 
@@ -226,40 +192,39 @@ Section wrapper with background variants and optional patterns.
 | `bgImage` | `String` | `''` | Background image URL |
 | `parallax` | `Boolean` | `false` | Enable parallax on bg image |
 
-#### XMarkFooter
+#### XMarkLayoutFooter
 
 Full footer with brand, link columns, social icons, and newsletter.
 
 ```vue
-<XMarkFooter
-  logo="/logo.svg"
-  logo-alt="Company"
+<XMarkLayoutFooter
+  :logo="{ src: '/logo.svg', alt: 'Company' }"
   description="Building the future of modern software."
   :social="[{ name: 'Twitter', href: 'https://twitter.com', icon: 'i-lucide-twitter' }]"
   :columns="[{ title: 'Product', links: [{ label: 'Features', to: '/features' }] }]"
   :legal-links="[{ label: 'Privacy', to: '/privacy' }]"
-  :show-newsletter="true"
+  :has-newsletter="true"
   @newsletter-submit="handleSubmit"
 />
 ```
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `logo` | `String` | `''` | Logo image URL |
+| `logo` | `Object` | `null` | Logo `{ src, alt? }` |
 | `description` | `String` | `''` | Brand description |
 | `social` | `Array` | `[]` | Social links `{ name, href, icon }` |
 | `columns` | `Array` | `[]` | Link columns `{ title, links: [{ label, to }] }` |
 | `legalLinks` | `Array` | `[]` | Legal links `{ label, to }` |
 | `copyright` | `String` | auto | Copyright text |
-| `showNewsletter` | `Boolean` | `false` | Show newsletter section |
+| `hasNewsletter` | `Boolean` | `false` | Show newsletter section |
 
-#### XMarkLegalFooter
+#### XMarkLayoutFooterLegal
 
 Minimal footer with copyright and legal links only.
 
 ```vue
-<XMarkLegalFooter
-  company-name="X Enterprises"
+<XMarkLayoutFooterLegal
+  copyright="© 2026 Acme Inc. All rights reserved."
   :links="[{ label: 'Privacy', to: '/privacy' }]"
 />
 ```
@@ -1072,7 +1037,7 @@ npm run test:e2e
 | `useStaggerReveal(selector, delay?)` | Adds incremental `transition-delay` to `[data-reveal]` children inside a container. |
 | `useParallax(options?)` | Parallax scroll effect for `.xParallax[data-parallax-speed]` elements. Uses `requestAnimationFrame` for performance. |
 | `useElementParallax(speed?)` | Individual element parallax via template ref. Returns `{ elementRef }`. |
-| `useXBlog()` | Blog data fetching composable. Reads `runtimeConfig.public.apiURL`. |
+| `useXBlog()` | Nuxt Content blog helpers (`getPosts`, `getPostByPath`, `getSurround`, `normalizeBlogPost`). Expects a `blog` collection and markdown under `content/blog/`. |
 
 All composables are SSR-safe — they guard lifecycle hooks with `getCurrentInstance()` and `import.meta.client` checks.
 
@@ -1082,11 +1047,10 @@ All composables are SSR-safe — they guard lifecycle hooks with `getCurrentInst
 
 | Name | Required | Description |
 |------|----------|-------------|
-| `NUXT_PUBLIC_API_URL` | No | Base API URL for blog composable (used by `useXBlog`) |
 | Marker.io Project ID | No | Set via `appConfig.xMarketing.config.markerProjectId` (not env var) |
 | Newsletter Org ID | No | Set via `appConfig.xMarketing.config.emailMarketingNewsletters.organizationId` |
 
-The layer itself has no required environment variables. All configuration is done via `app.config.ts`.
+The layer itself has no required environment variables. Blog content is **file-based via Nuxt Content** (not Builder.io). All site config is done via `app.config.ts`.
 
 ---
 
@@ -1179,7 +1143,8 @@ The layer provides a complete marketing website toolkit built on Nuxt UI v4:
 
 | Path | Purpose |
 |------|---------|
-| `nuxt.config.ts` | Registers `@nuxt/ui`, loads CSS, enables SSR and devtools |
+| `nuxt.config.ts` | Registers `@nuxt/ui` + `@nuxt/content`, loads CSS, enables SSR |
+| `content.config.ts` | Default Nuxt Content `blog` collection schema |
 | `app/app.config.ts` | Default xMarketing config + Nuxt UI theme overrides + type augmentation |
 | `app/app.vue` | Default app shell with navbar, newsletter, footer (override in consumer app) |
 | `app/assets/css/x-marketing.css` | Full design system: colors, typography, animations, effects |
@@ -1190,7 +1155,36 @@ The layer provides a complete marketing website toolkit built on Nuxt UI v4:
 | `app/composables/` | Composables: useScrollReveal, useParallax, useXBlog |
 | `app/plugins/marketing.client.ts` | Client plugin: auto-initializes scroll/parallax globally |
 | `app/types/marketing.d.ts` | TypeScript interfaces for all data structures |
-| `app/pages/` | Default blog pages (index + detail with slug routing) |
+| `app/pages/blog/` | Default blog index + slug detail (Nuxt Content, not Builder.io) |
+
+### Blog (Nuxt Content)
+
+**Breaking (Builder.io removed):** default `/blog` pages no longer call the Builder CDN.
+Posts come from markdown in the consumer app.
+
+1. Peer-install `@nuxt/content` and `better-sqlite3` (already required by Content v3).
+2. Ensure the layer is extended so `content.config.ts` defines the `blog` collection (or copy/adapt it).
+3. Add posts under `content/blog/*.md`:
+
+```md
+---
+title: Getting Started
+description: First post on the marketing site.
+date: 2025-01-15
+author: Tim
+image: /blog/cover.jpg
+category: Tutorial
+tags: [nuxt, marketing]
+published: true
+readingTime: 5
+---
+
+## Hello
+
+Markdown body rendered via `ContentRenderer`.
+```
+
+4. `useXBlog().getPosts()` / `getPostByPath()` feed `XMarkBlogList` and `XMarkBlogDetail`.
 
 ### Overriding in Consumer Apps
 
@@ -1198,6 +1192,7 @@ The layer provides a complete marketing website toolkit built on Nuxt UI v4:
 - **app.config.ts**: Deep-merges with layer defaults. Set `xMarketing.header`, `xMarketing.footer`, etc.
 - **app.vue**: Override entirely by creating your own `app.vue` in the consumer app.
 - **Pages**: Consumer pages take precedence. Override `/blog` by creating `pages/blog/index.vue`.
+- **Content**: Own the markdown under `content/blog/`; do not put secrets in frontmatter.
 
 ---
 

package/app/app.config.ts

@@ -1,3 +1,5 @@
+import type { XMarketingConfig } from "./types/config";
+
 export default defineAppConfig({
   ui: {
     primary: "brand",
@@ -25,19 +27,24 @@ export default defineAppConfig({
     },
   },
   xMarketing: {
-    name: "X Enterprises",
-    url: "https://x-enterprises.com",
+    /** Site name — used by the shipped shell for the SEO title template
+     *  ("%s | name") and og:site_name. Leave undefined to keep bare titles. */
+    name: undefined,
+    /** Canonical site URL — used as og:url on the shipped home page. */
+    url: undefined,
     config: {
-      markerProjectId: "",
+      markerProjectId: undefined,
       emailMarketingNewsletters: {
-        organizationId: "",
+        organizationId: undefined,
       },
     },
     header: {
+      /** Set false to opt out of the default navbar in the shipped shell. */
+      active: true as boolean,
       logo: {
-        src: "",
-        srcDark: "",
-        alt: "",
+        src: undefined,
+        srcDark: undefined,
+        alt: undefined,
       },
       nav: {
         buttons: [],
@@ -45,23 +52,29 @@ export default defineAppConfig({
       },
     },
     footer: {
+      /** Set false to opt out of the default footer in the shipped shell. */
+      active: true as boolean,
       logo: {
-        src: "",
-        alt: "",
+        src: undefined,
+        alt: undefined,
       },
       bg: {
-        color: "",
+        color: undefined,
         img: {
-          src: "",
-          alt: "",
+          src: undefined,
+          alt: undefined,
         },
       },
-      body: "",
+      body: undefined,
       socials: [],
       columns: [],
     },
+    /** Cookie-consent banner in the shipped shell; gates tracking injection. */
+    consent: {
+      active: true as boolean,
+    },
     blog: {
-      active: true,
+      active: true as boolean,
       title: "Blog",
       description:
         "Welcome to our blog. Here you can find the latest news, updates, and articles.",
@@ -94,121 +107,14 @@ export default defineAppConfig({
       scripts: [],
       // ---- Behavior ----
       /** Auto-inject configured scripts on consent. Default: true. */
-      autoInject: true,
+      autoInject: true as boolean,
     },
   },
 });
 
 declare module "@nuxt/schema" {
   interface AppConfigInput {
-    xMarketing?: {
-      /** Project name */
-      name?: string;
-      /** Project URL */
-      url?: string;
-      config?: {
-        markerProjectId?: string;
-        emailMarketingNewsletters?: {
-          organizationId?: string;
-        };
-      };
-      header?: {
-        logo?: {
-          src?: string;
-          srcDark?: string;
-          alt?: string;
-        };
-        nav?: {
-          buttons?: {
-            label: string;
-            to: string;
-            icon?: string;
-            target?: string;
-            variant?: string;
-            square?: boolean;
-            color?: string;
-          }[];
-          links?: NavLink[];
-        };
-      };
-      footer?: {
-        body?: string;
-        bg?: {
-          color?: string;
-          img?: {
-            src?: string;
-            alt?: string;
-          };
-        };
-        logo?: {
-          src?: string;
-          alt?: string;
-        };
-socials?: {
-        name: string;
-        url: string;
-        icon: string;
-      }[];
-      columns?: {
-        headerLabel: string;
-        links: {
-          label: string;
-          to: string;
-          target?: string;
-        }[];
-      }[];
-      /**
-       * Tracking + analytics config. Read by
-       * `<XMarkPrivacyCookieConsent>` and `useConsentTracking()`.
-       * Only fires after the matching consent category is granted.
-       */
-      tracking?: XMarketingTracking;
-    };
+    xMarketing?: XMarketingConfig;
   }
 }
 
-/**
- * Tracking entry — use the convenience IDs for the common tools
- * (GTM, GA4, Clarity) or `scripts[]` for everything else. Scripts
- * are injected only after the visitor grants consent for the
- * matching `category` (default: "analytics").
- */
-interface XMarketingTracking {
-  /** Google Tag Manager container ID, e.g. "GTM-XXXXXXX". */
-  gtmId?: string;
-  /** Google Analytics 4 measurement ID, e.g. "G-XXXXXXXX". */
-  ga4Id?: string;
-  /** Microsoft Clarity project ID, e.g. "abc123def4". */
-  clarityId?: string;
-  /**
-   * Arbitrary scripts (Meta Pixel, Hotjar, Segment, LinkedIn Insight,
-   * Pinterest, TikTok, etc.). Each fires once the matching consent
-   * category is granted. Use `inline` for hand-written snippets like
-   * `gtag('js', new Date())`.
-   */
-  scripts?: XMarketingTrackingScript[];
-  /** Auto-inject configured scripts on consent. Default: true. */
-  autoInject?: boolean;
-}
-
-interface XMarketingTrackingScript {
-  /** Stable ID — used to dedupe re-injection. */
-  id: string;
-  /** External script URL (e.g. "https://www.googletagmanager.com/gtag/js?id=G-XXX"). */
-  src?: string;
-  /** Inline script body (no `src` required). */
-  inline?: string;
-  /** Consent category gate. "necessary" fires immediately; "analytics" / "marketing" gated. */
-  category?: "necessary" | "analytics" | "marketing";
-  /** Extra attributes applied to the injected <script>. */
-  attrs?: Record<string, string>;
-}
-}
-
-interface NavLink {
-  label: string;
-  to?: string;
-  target?: string;
-  children?: NavLink[];
-}
-