@xenterprises/nuxt-x-marketing 1.0.2 → 1.1.0

package/README.md

@@ -988,24 +988,143 @@ npm run test:e2e
 
 ---
 
+## Composables
+
+| Composable | Description |
+|------------|-------------|
+| `useScrollReveal(options?)` | Intersection Observer scroll animations. Auto-adds `is-visible` class to `[data-reveal]`, `.xFadeUp`, `.xFadeIn`, `.xFadeLeft`, `.xFadeRight`, `.xScale`, `.xFadeUp-stagger` elements. |
+| `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`. |
+
+All composables are SSR-safe — they guard lifecycle hooks with `getCurrentInstance()` and `import.meta.client` checks.
+
+---
+
+## Environment Variables
+
+| 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`.
+
+---
+
 ## CSS Classes
 
-The layer provides utility classes for consistent styling:
+### Typography
+
+| Class | Description |
+|-------|-------------|
+| `xText-display` | Display heading — `clamp(3rem, 8vw, 6rem)`, weight 700, tight tracking |
+| `xText-headline` | Section headline — `clamp(2rem, 5vw, 3.5rem)`, weight 600 |
+| `xText-title` | Card/feature title — `clamp(1.25rem, 3vw, 1.75rem)`, weight 600 |
+| `xText-body` | Body text — `1.125rem`, line-height 1.7 |
+| `xText-small` | Captions/labels — `0.875rem` |
+| `xText-eyebrow` | Uppercase label — `0.75rem`, 0.1em tracking |
+| `xText-balance` | Applies `text-wrap: balance` |
+| `xText-gradient` | Gradient text using primary color |
+
+### Scroll Animations
+
+| Class | Description |
+|-------|-------------|
+| `xFadeUp` | Fade in + slide up (24px) on scroll |
+| `xFadeIn` | Simple fade in on scroll |
+| `xFadeLeft` | Fade in from left (-24px) on scroll |
+| `xFadeRight` | Fade in from right (24px) on scroll |
+| `xScale` | Scale in (0.95 → 1) on scroll |
+| `xFadeUp-stagger` | Stagger children with 100ms delay increments (up to 6 children) |
+| `[data-reveal]` | Legacy fade up (40px) on scroll |
+
+### Hover Effects
+
+| Class | Description |
+|-------|-------------|
+| `xHover-lift` | Lift up 4px + shadow on hover |
+| `xHover-grow` | Scale to 1.02 on hover |
+| `xHover-glow` | Primary color glow shadow on hover |
+| `xHover-glow-neutral` | Neutral glow shadow on hover |
+| `xHover-glow-subtle` | Subtle glow shadow on hover |
+| `xHover-zoom` | Zoom child `<img>` to 1.08 on hover |
+
+### Glass & Glow
 
 | Class | Description |
 |-------|-------------|
-| `xText-display` | Large display heading |
-| `xText-headline` | Section headline |
-| `xText-title` | Card/feature title |
-| `xText-eyebrow` | Small uppercase label |
-| `xText-balance` | Text wrap balance |
-| `xFadeUp` | Scroll-triggered fade-in animation |
-| `xHover-zoom` | Zoom on hover effect |
-| `xParallax` | Parallax scroll effect |
-| `xGlass` | Glassmorphism effect |
+| `xGlass` | Glassmorphism — 20px blur, white/70 bg, border, shadow |
+| `xGlass-subtle` | Light glassmorphism — 8px blur |
+| `xGlass-heavy` | Heavy glassmorphism — 40px blur |
+| `xGlow-divider` | Glowing horizontal divider line |
+| `xGlow-border` | Glowing gradient border |
+| `xGlow-text` | Text glow shadow |
+
+### Overlays
+
+| Class | Description |
+|-------|-------------|
+| `xOverlay-light` | 30% black overlay |
+| `xOverlay-heavy` | 60% black overlay |
+| `xOverlay-gradient` | Bottom-to-top gradient overlay |
+| `xOverlay-vignette` | Radial vignette overlay |
+
+### Parallax
+
+| Class | Description |
+|-------|-------------|
+| `xParallax` | JS-driven parallax (use with `data-parallax-speed="0.3"`) |
+| `xParallax-bg` | CSS-only parallax (`background-attachment: fixed`) |
+
+All animations respect `prefers-reduced-motion: reduce`.
+
+---
+
+## How It Works
+
+The layer provides a complete marketing website toolkit built on Nuxt UI v4:
+
+1. **Component Registration**: All components in `app/components/X/Mark/` are auto-imported by Nuxt with the `XMark` prefix (e.g., `X/Mark/Hero/index.vue` → `<XMarkHero>`). Branded X Enterprises components live under `X/X/` with the `XX` prefix.
+
+2. **Design System**: `app/assets/css/x-marketing.css` defines CSS custom properties for typography scale, spacing, colors, shadows, and motion. It uses Tailwind CSS v4 with `@theme static` for custom color palettes ("brand" and "deep"). Dark mode overrides use `.dark` selector.
+
+3. **Animations**: A client-side plugin (`marketing.client.ts`) auto-initializes `useScrollReveal()` and `useParallax()` globally on mount. Components that need scroll animations can also call `useScrollReveal()` directly.
+
+4. **Configuration**: `app.config.ts` provides the `xMarketing` namespace with header/footer/blog configuration and Nuxt UI theme overrides. Consumer apps merge their own `app.config.ts` to customize.
+
+5. **Type System**: `app/types/marketing.d.ts` exports interfaces for all data structures (BlogPost, Feature, PricingPlan, Testimonial, etc.) used across components.
+
+---
+
+## Layer Architecture
+
+| Path | Purpose |
+|------|---------|
+| `nuxt.config.ts` | Registers `@nuxt/ui`, loads CSS, enables SSR and devtools |
+| `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 |
+| `app/components/X/Mark/` | Generic marketing components (auto-imported as `XMark*`) |
+| `app/components/X/X/` | X Enterprises branded components (auto-imported as `XX*`) |
+| `app/components/X/Footer/` | Legacy footer components |
+| `app/components/X/Header/` | Legacy header components |
+| `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) |
+
+### Overriding in Consumer Apps
+
+- **nuxt.config.ts**: Consumer config merges with layer config. Add modules, runtime config, etc.
+- **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`.
 
 ---
 
 ## License
 
-MIT License - see LICENSE file for details.
+UNLICENSED - Proprietary to X Enterprises.

package/app/components/X/Mark/CodeBlock/index.vue

@@ -23,7 +23,7 @@
 
     <!-- Shiki Highlighter - wrapped in ClientOnly for SSR compatibility -->
     <ClientOnly>
-      <Shiki :code="code" :lang="(language as any)" />
+      <Shiki :code="code" :lang="language" />
       <template #fallback>
         <pre class="shiki-fallback"><code>{{ code }}</code></pre>
       </template>
@@ -31,12 +31,24 @@
   </div>
 </template>
 
-<script setup lang="ts">
-const props = defineProps<{
-  code: string;
-  language?: string;
-  showCopy?: boolean;
-}>();
+<script setup>
+const props = defineProps({
+  /** Code string to highlight */
+  code: {
+    type: String,
+    required: true,
+  },
+  /** Language for syntax highlighting */
+  language: {
+    type: String,
+    default: '',
+  },
+  /** Show copy button */
+  showCopy: {
+    type: Boolean,
+    default: false,
+  },
+});
 
 const copied = ref(false);
 

package/app/components/X/Mark/Divider/Glow.vue

@@ -28,25 +28,31 @@
   </div>
 </template>
 
-<script setup lang="ts">
-const props = withDefaults(
-  defineProps<{
-    /** Color theme - any Tailwind color or 'white' */
-    color?: string
-    /** Vertical spacing (padding) */
-    spacing?: string
-    /** Glow intensity */
-    intensity?: 'none' | 'subtle' | 'medium' | 'strong'
-    /** Line height */
-    height?: 'thin' | 'default' | 'thick'
-  }>(),
-  {
-    color: 'primary',
-    spacing: 'py-16',
-    intensity: 'medium',
-    height: 'default',
-  }
-)
+<script setup>
+const props = defineProps({
+  /** Color theme - any Tailwind color or 'white' */
+  color: {
+    type: String,
+    default: 'primary',
+  },
+  /** Vertical spacing (padding) */
+  spacing: {
+    type: String,
+    default: 'py-16',
+  },
+  /** Glow intensity */
+  intensity: {
+    type: String,
+    default: 'medium',
+    validator: (v) => ['none', 'subtle', 'medium', 'strong'].includes(v),
+  },
+  /** Line height */
+  height: {
+    type: String,
+    default: 'default',
+    validator: (v) => ['thin', 'default', 'thick'].includes(v),
+  },
+})
 
 const heightClass = computed(() => {
   const heights = {

package/app/components/X/Mark/Section/Stitch.vue

@@ -25,37 +25,51 @@
   </div>
 </template>
 
-<script setup lang="ts">
-const props = withDefaults(
-  defineProps<{
-    /** Shape variant */
-    variant?: 'concave' | 'convex' | 'diagonal' | 'slant' | 'clouds' | 'waves' | 'tilt' | 'peaks' | 'scallop' | 'arrow'
-    /** Top section color */
-    topColor?: string
-    /** Bottom section color */
-    bottomColor?: string
-    /** Height size */
-    height?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl'
-    /** Reverse direction (flip horizontally) */
-    reverse?: boolean
-    /** Invert vertically (swap top/bottom) */
-    invert?: boolean
-    /** Show glow line */
-    glow?: boolean
-    /** Glow line color */
-    glowColor?: string
-  }>(),
-  {
-    variant: 'diagonal',
-    topColor: 'rgb(243 244 246)',
-    bottomColor: 'rgb(249 250 251)',
-    height: 'md',
-    reverse: false,
-    invert: false,
-    glow: false,
-    glowColor: 'rgba(99, 102, 241, 0.5)',
-  }
-)
+<script setup>
+const props = defineProps({
+  /** Shape variant */
+  variant: {
+    type: String,
+    default: 'diagonal',
+    validator: (v) => ['concave', 'convex', 'diagonal', 'slant', 'clouds', 'waves', 'tilt', 'peaks', 'scallop', 'arrow'].includes(v),
+  },
+  /** Top section color */
+  topColor: {
+    type: String,
+    default: 'rgb(243 244 246)',
+  },
+  /** Bottom section color */
+  bottomColor: {
+    type: String,
+    default: 'rgb(249 250 251)',
+  },
+  /** Height size */
+  height: {
+    type: String,
+    default: 'md',
+    validator: (v) => ['sm', 'md', 'lg', 'xl', '2xl', '3xl'].includes(v),
+  },
+  /** Reverse direction (flip horizontally) */
+  reverse: {
+    type: Boolean,
+    default: false,
+  },
+  /** Invert vertically (swap top/bottom) */
+  invert: {
+    type: Boolean,
+    default: false,
+  },
+  /** Show glow line */
+  glow: {
+    type: Boolean,
+    default: false,
+  },
+  /** Glow line color */
+  glowColor: {
+    type: String,
+    default: 'rgba(99, 102, 241, 0.5)',
+  },
+})
 
 const heightValue = computed(() => {
   const heights = {

package/app/composables/{useParallax.ts → useParallax.js}

@@ -1,7 +1,6 @@
 /**
  * Parallax Scroll Effect Composable
  * Implements smooth parallax scrolling for background elements
- * From spec-prompt.md specification
  */
 export const useParallax = (options = {}) => {
   // Only register lifecycle hooks when inside a component instance
@@ -13,8 +12,8 @@ export const useParallax = (options = {}) => {
     ...options,
   };
 
-  const elements = ref<Element[]>([]);
-  let handleScroll: (() => void) | null = null;
+  const elements = ref([]);
+  let handleScroll = null;
 
   const initParallax = () => {
     if (import.meta.client) {
@@ -28,7 +27,7 @@ export const useParallax = (options = {}) => {
         const scrollY = window.scrollY;
 
         elements.value.forEach((el) => {
-          const speed = parseFloat((el as HTMLElement).dataset.parallaxSpeed || String(defaultOptions.defaultSpeed));
+          const speed = parseFloat(el.dataset.parallaxSpeed || String(defaultOptions.defaultSpeed));
           const rect = el.getBoundingClientRect();
           const offsetTop = rect.top + scrollY;
 
@@ -36,7 +35,7 @@ export const useParallax = (options = {}) => {
           const offset = (scrollY - offsetTop) * speed;
 
           // Apply the transform
-          (el as HTMLElement).style.transform = `translateY(${offset}px)`;
+          el.style.transform = `translateY(${offset}px)`;
         });
       };
 
@@ -89,8 +88,8 @@ export const useParallax = (options = {}) => {
  * Usage: const { elementRef } = useElementParallax(0.3)
  */
 export const useElementParallax = (speed = 0.5) => {
-  const elementRef = ref<HTMLElement | null>(null);
-  let handleScroll: (() => void) | null = null;
+  const elementRef = ref(null);
+  let handleScroll = null;
 
   onMounted(() => {
     if (import.meta.client && elementRef.value) {

package/app/composables/{useScrollReveal.ts → useScrollReveal.js}

@@ -8,7 +8,7 @@
  * - .xFadeUp, .xFadeIn, .xFadeLeft, .xFadeRight, .xScale classes
  * - .xFadeUp-stagger for staggered child animations
  */
-export const useScrollReveal = (options: Record<string, unknown> = {}) => {
+export const useScrollReveal = (options = {}) => {
   // Only register lifecycle hooks when inside a component instance
   const instance = getCurrentInstance();
   if (!instance) return { initScrollReveal: () => {}, cleanup: () => {} };
@@ -19,7 +19,7 @@ export const useScrollReveal = (options: Record<string, unknown> = {}) => {
     ...options,
   };
 
-  const observer = ref<IntersectionObserver | null>(null);
+  const observer = ref(null);
 
   // Selector for all animation elements
   const animationSelectors = [
@@ -82,7 +82,7 @@ export const useScrollReveal = (options: Record<string, unknown> = {}) => {
 /**
  * Helper to add staggered reveal delays to child elements
  */
-export const useStaggerReveal = (containerSelector: string, staggerDelay = 100) => {
+export const useStaggerReveal = (containerSelector, staggerDelay = 100) => {
   if (import.meta.client) {
     onMounted(() => {
       setTimeout(() => {
@@ -90,7 +90,7 @@ export const useStaggerReveal = (containerSelector: string, staggerDelay = 100)
         if (container) {
           const children = container.querySelectorAll('[data-reveal]');
           children.forEach((child, index) => {
-            (child as HTMLElement).style.transitionDelay = `${index * staggerDelay}ms`;
+            child.style.transitionDelay = `${index * staggerDelay}ms`;
           });
         }
       }, 100);

package/nuxt.config.ts

@@ -9,16 +9,6 @@ export default defineNuxtConfig({
 
     },
   },
-  modules: ["@nuxt/ui", "nuxt-shiki"],
-  shiki: {
-    bundledThemes: ["github-dark-default", "github-light-default"],
-    bundledLangs: ["javascript", "typescript", "vue", "html", "css", "json", "yaml", "sql", "markdown", "bash", "shellscript"],
-    defaultTheme: "github-dark-default",
-    langAlias: {
-      shell: "bash",
-      sh: "bash",
-      zsh: "bash",
-    },
-  },
+  modules: ["@nuxt/ui"],
   css: [resolve(__dirname, "app/assets/css/x-marketing.css")],
 });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@xenterprises/nuxt-x-marketing",
   "license": "UNLICENSED",
   "type": "module",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "main": "./nuxt.config.ts",
   "scripts": {
     "dev": "nuxi dev .playground",

package/.claude/settings.local.json

@@ -1,23 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(curl:*)",
-      "Bash(npm run dev:*)",
-      "Bash(cat:*)",
-      "Bash(npm install:*)",
-      "Bash(find:*)",
-      "Bash(ls:*)",
-      "Skill(frontend-design)",
-      "Bash(git log:*)",
-      "Bash(test:*)",
-      "Bash(timeout 300 npx playwright test:*)",
-      "Bash(npx playwright test:*)",
-      "Bash(npx playwright install:*)",
-      "Bash({} ;)",
-      "mcp__plugin_context7_context7__resolve-library-id",
-      "mcp__plugin_context7_context7__query-docs",
-      "Bash(git reset:*)",
-      "Bash(python3:*)"
-    ]
-  }
-}

package/.nuxtrc

@@ -1 +0,0 @@
-typescript.includeWorkspace = true

package/.playground/app.config.ts

@@ -1,74 +0,0 @@
-export default defineAppConfig({
-  xMarketing: {
-    name: "X Marketing Components",
-    config: {
-      markerProjectId: "",
-      emailMarketingNewsletters: {
-        organizationId: "",  // Disabled for documentation playground
-      },
-    },
-    header: {
-      logo: {
-        src: "https://cdn.x.enterprises/logo-x.png",
-        srcDark: "https://cdn.x.enterprises/logo-x.png",
-        alt: "nuxt-x-marketing",
-      },
-      nav: {
-        links: [
-          { label: "Features", to: "#features" },
-          { label: "Testimonials", to: "#testimonials" },
-          { label: "Pricing", to: "#pricing" },
-          { label: "Blog", to: "/blog/card" },
-        ],
-        buttons: [
-          { label: "Sign In", to: "#" },
-          { label: "Get Started", to: "#", color: "primary" },
-        ],
-      },
-    },
-    footer: {
-      bg: {
-        color: "bg-gray-900",
-      },
-      logo: {
-        src: "https://cdn.x.enterprises/logo-x.png",
-        alt: "nuxt-x-marketing",
-      },
-      body: "A comprehensive collection of beautifully designed marketing components built with Nuxt UI v4 and Tailwind CSS. Perfect for landing pages, marketing sites, and SaaS products.",
-      socials: [
-        { name: "GitHub", url: "https://github.com", icon: "i-lucide-github" },
-        { name: "Twitter", url: "https://twitter.com", icon: "i-lucide-twitter" },
-        { name: "LinkedIn", url: "https://linkedin.com", icon: "i-lucide-linkedin" },
-      ],
-      columns: [
-        {
-          headerLabel: "Product",
-          links: [
-            { label: "Features", to: "#features" },
-            { label: "Pricing", to: "#pricing" },
-            { label: "Changelog", to: "#" },
-            { label: "Roadmap", to: "#" },
-          ],
-        },
-        {
-          headerLabel: "Company",
-          links: [
-            { label: "About", to: "#" },
-            { label: "Blog", to: "/blog/card" },
-            { label: "Careers", to: "#" },
-            { label: "Contact", to: "#" },
-          ],
-        },
-        {
-          headerLabel: "Resources",
-          links: [
-            { label: "Documentation", to: "#" },
-            { label: "Guides", to: "#" },
-            { label: "Help Center", to: "#" },
-            { label: "Community", to: "#" },
-          ],
-        },
-      ],
-    },
-  },
-});