ultimate-jekyll-manager 0.0.118 → 0.0.119

package/CLAUDE.md

@@ -26,19 +26,179 @@ The local development server URL is stored in `.temp/_config_browsersync.yml` in
 
 ## Asset Organization
 
-### CSS Architecture
-- `src/assets/css/ultimate-jekyll-manager.scss` - Main UJ stylesheet
-- `src/assets/css/main.scss` - Site-wide styles (runs on every page)
+### Ultimate Jekyll Manager Files (THIS project)
+
+**CSS:**
+- `src/assets/css/ultimate-jekyll-manager.scss` - Main UJ stylesheet (provides core styles)
 - `src/assets/css/global/` - Global UJ styles
-- `src/assets/css/pages/` - Page-specific styles
+- `src/assets/css/pages/` - Page-specific styles provided by UJ
   - Format: `src/assets/css/pages/[page-name]/index.scss`
+  - Example: `src/assets/css/pages/download/index.scss`
 
-### JavaScript Architecture
-- `src/assets/js/ultimate-jekyll-manager.js` - Main UJ JavaScript entry point
-- `src/assets/js/main.js` - Site-wide JavaScript (runs on every page)
+**JavaScript:**
+- `src/assets/js/ultimate-jekyll-manager.js` - Main UJ JavaScript entry point (provides core functionality)
 - `src/assets/js/core/` - Core UJ modules
-- `src/assets/js/pages/` - Page-specific JavaScript
+- `src/assets/js/pages/` - Page-specific JavaScript provided by UJ
   - Format: `src/assets/js/pages/[page-name]/index.js`
+  - Example: `src/assets/js/pages/download/index.js`
+- `src/assets/js/libs/` - UJ library modules (prerendered-icons, form-manager, authorized-fetch, etc.)
+
+**Default Pages & Layouts:**
+
+UJ provides default page templates and layouts in `src/defaults/dist/` that are copied to consuming projects. These are NOT meant to be edited by users.
+
+- Format: `src/defaults/dist/_layouts/themes/[theme-id]/frontend/pages/[page-name].html`
+- Examples:
+  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/download.html`
+  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/pricing.html`
+  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/payment/checkout.html`
+  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/payment/confirmation.html`
+  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/contact.html`
+- Core layouts:
+  - `src/defaults/dist/_layouts/core/root.html` - Root HTML wrapper
+  - `src/defaults/dist/_layouts/themes/[theme-id]/frontend/core/base.html` - Theme base layout
+
+**Complete UJ Page Example:**
+- **HTML:** `src/defaults/dist/_layouts/themes/classy/frontend/pages/download.html`
+- **CSS:** `src/assets/css/pages/download/index.scss`
+- **JS:** `src/assets/js/pages/download/index.js`
+
+These files serve as blueprints and reference implementations. When building custom pages in consuming projects, reference these for patterns and best practices.
+
+**IMPORTANT:** Consuming projects CAN create files with the same paths in their own `src/` directory to override UJ defaults, but this should ONLY be done when absolutely necessary. Prefer using `src/pages/` and `src/_layouts/` for custom pages instead of overriding UJ default files.
+
+### Section Configuration Files (JSON)
+
+UJ provides JSON configuration files for common sections like navigation and footer. These JSON files are consumed by corresponding HTML templates during the build process.
+
+**Configuration Files:**
+- `src/defaults/src/_includes/frontend/sections/nav.json` - Navigation configuration
+- `src/defaults/src/_includes/frontend/sections/footer.json` - Footer configuration
+
+**How It Works:**
+1. JSON files contain structured data (links, labels, settings)
+2. HTML templates in `src/defaults/dist/_includes/themes/[theme-id]/frontend/sections/` read and render this data
+3. The build process converts `.json` → data loaded by `.html` templates
+
+**Customizing Navigation/Footer:**
+
+Consuming projects should create their own JSON files in `src/_includes/frontend/sections/`:
+- `src/_includes/frontend/sections/nav.json`
+- `src/_includes/frontend/sections/footer.json`
+
+**Example: Footer Configuration**
+
+```json
+{
+  logo: {
+    href: '/',
+    class: 'filter-adaptive',
+    text: '{{ site.brand.name }}',
+    description: '{{ site.meta.description }}',
+  },
+  links: [
+    {
+      label: 'Company',
+      href: null,
+      links: [
+        {
+          label: 'About Us',
+          href: '/about',
+        },
+        {
+          label: 'Pricing',
+          href: '/pricing',
+        },
+      ],
+    },
+  ],
+  socials: {
+    enabled: true,
+  },
+  copyright: {
+    enabled: true,
+    text: null,
+  },
+}
+```
+
+**Note:** These are JSON5 files (support comments, trailing commas, unquoted keys). The corresponding HTML templates automatically process these files during the build.
+
+### Customizing Default Pages via Frontmatter
+
+**BEST PRACTICE:** UJ default pages are designed to be customized through frontmatter WITHOUT writing any HTML. Consuming projects can create a simple page that includes ONLY frontmatter to configure the default page's behavior.
+
+**How It Works:**
+1. UJ default pages use `page.resolved` to access merged frontmatter (site → layout → page)
+2. **IMPORTANT:** Before customizing, READ the UJ default page in `src/defaults/dist/_layouts/` to understand available frontmatter options and how they're used
+3. Consuming projects create a page in `src/pages/` with custom frontmatter
+4. The page uses a UJ layout (e.g., `blueprint/pricing`)
+5. Frontmatter overrides default values without any HTML
+
+**Example: Customizing the Pricing Page**
+
+**Step 1:** Read the UJ default pricing page to see available frontmatter options:
+- File: `src/defaults/dist/_layouts/themes/classy/frontend/pages/pricing.html`
+- Look for frontmatter at the top and how `page.resolved.pricing` is used in the HTML
+
+**Step 2:** In consuming project, create `src/pages/pricing.html`:
+
+```yaml
+---
+### ALL PAGES ###
+layout: blueprint/pricing
+permalink: /pricing
+
+### PAGE CONFIG ###
+pricing:
+  price_per_unit:
+    enabled: true
+    feature_id: "credits"
+    label: "credit"
+  plans:
+    - id: "basic"
+      name: "Basic"
+      tagline: "best for getting started"
+      url: "/download"
+      pricing:
+        monthly: 0
+        annually: 0
+      features:
+        - id: "credits"
+          name: "Credits"
+          value: 1
+          icon: "sparkles"
+    ...
+---
+```
+
+That's it! No HTML needed. The UJ pricing layout reads `page.resolved.pricing` and renders the plans accordingly.
+
+**When to Use Frontmatter Customization:**
+- ✅ Customizing UJ default pages (pricing, contact, download, etc.)
+- ✅ Changing configuration without touching HTML
+- ✅ Maintaining upgradability when UJ updates
+
+**When to Create Custom Pages:**
+- ❌ Building entirely new page types
+- ❌ Needing custom HTML structure
+- ❌ Pages with unique layouts not provided by UJ
+
+### Consuming Project Files
+
+**CSS:**
+- `src/assets/css/main.scss` - Site-wide custom styles (runs on every page, edits by consuming project)
+- `src/assets/css/pages/` - Page-specific custom styles
+  - Format: `src/assets/css/pages/[page-name]/index.scss`
+
+**JavaScript:**
+- `src/assets/js/main.js` - Site-wide custom JavaScript (runs on every page, edits by consuming project)
+- `src/assets/js/pages/` - Page-specific custom JavaScript
+  - Format: `src/assets/js/pages/[page-name]/index.js`
+
+**Pages & Layouts:**
+- `src/pages/` - Individual page HTML/Markdown files
+- `src/_layouts/` - Custom layouts for the consuming project
 
 **Asset Loading:** Page-specific CSS/JS files are automatically included based on the page's canonical path. Override with `asset_path` frontmatter.
 
@@ -170,36 +330,95 @@ asset_path: blog/post
 
 Uses `/assets/css/pages/{{ asset_path }}.bundle.css` instead of deriving from `page.canonical.path`. Useful when multiple pages share assets (e.g., all blog posts).
 
-## Icon Pre-rendering System
+## Icon System
 
-Ultimate Jekyll includes a frontmatter-based icon pre-rendering system for optimal performance.
+Ultimate Jekyll uses Font Awesome icons but does NOT include the Font Awesome JavaScript or CSS library. All icons must be rendered server-side using Jekyll's `{% uj_icon %}` tag.
 
-### How It Works
+### When to Use `{% uj_icon %}` vs Prerendered Icons
+
+**IMPORTANT:** Use the correct method based on WHERE the icon will be used:
+
+#### Use `{% uj_icon %}` in HTML/Liquid Templates
+
+When icons are part of the static HTML template, use `{% uj_icon %}` directly:
+
+```liquid
+<!-- Alerts -->
+<div class="alert alert-success">
+  {% uj_icon "circle-check", "fa-sm" %} Success message
+</div>
+
+<!-- Buttons -->
+<button class="btn btn-primary">
+  {% uj_icon "paper-plane", "fa-md me-2" %}
+  Send
+</button>
+
+<!-- Labels -->
+<label>
+  {% uj_icon "envelope", "fa-sm me-1 text-info" %}
+  Email
+</label>
+```
 
-1. **Define icons in page frontmatter:**
+**Use this when:**
+- The icon is in a Jekyll template (.html file)
+- The icon is static and known at build time
+- The icon is part of the page structure
+
+#### Use Prerendered Icons in JavaScript
+
+When icons need to be dynamically inserted via JavaScript, pre-render them in frontmatter and access them via the library:
+
+**1. Add icons to page frontmatter:**
 ```yaml
 ---
 prerender_icons:
-  - name: "apple"
-    class: "fa-3xl"
-  - name: "android"
-    class: "fa-2xl"
-  - name: "chrome"
+  - name: "mobile"
+    class: "fa-sm me-1"
+  - name: "envelope"
+    class: "fa-sm me-1"
+  - name: "bell"
+    class: "fa-sm me-1"
 ---
 ```
 
-2. **Icons are rendered in HTML** via `src/defaults/dist/_includes/core/body.html`
+**2. Import the library in JavaScript:**
+```javascript
+import { getPrerenderedIcon } from '__main_assets__/js/libs/prerendered-icons.js';
+```
+
+**3. Use in your code:**
+```javascript
+const iconHTML = getPrerenderedIcon('mobile');
+$badge.innerHTML = `${iconHTML}Push Notification`;
+```
+
+**Use this when:**
+- Icons are dynamically inserted via JavaScript
+- Icons are part of dynamically generated content
+- Icons are added to elements created with `document.createElement()`
 
-3. **Access icons in JavaScript:**
+### What NOT to Do
+
+**NEVER use manual icon HTML in JavaScript:**
 ```javascript
-const iconHTML = webManager.utilities().getPrerenderedIcon('apple');
+// ❌ WRONG - Bootstrap Icons (we don't use Bootstrap Icons)
+$el.innerHTML = '<i class="bi bi-check-circle"></i> Text';
+
+// ❌ WRONG - Manual Font Awesome (we don't have FA JS/CSS)
+$el.innerHTML = '<i class="fa-solid fa-check"></i> Text';
+
+// ✅ CORRECT - Use prerendered icons
+const iconHTML = getPrerenderedIcon('circle-check');
+$el.innerHTML = `${iconHTML} Text`;
 ```
 
 ### Benefits
 - Icons are rendered server-side with proper Font Awesome classes
 - No client-side icon generation overhead
 - Consistent icon styling across the application
-- Easy to access via JavaScript utilities
+- No Font Awesome JavaScript/CSS library needed
 
 ## CSS Guidelines
 
@@ -393,6 +612,73 @@ const formManager = new FormManager('#my-form', options);
 **Reference:** `src/assets/js/libs/form-manager.js`
 **Example:** `src/assets/js/pages/contact/index.js`
 
+## Analytics & Tracking
+
+Ultimate Jekyll uses three tracking platforms: Google Analytics (gtag), Facebook Pixel (fbq), and TikTok Pixel (ttq).
+
+### Tracking Guidelines
+
+**IMPORTANT Rules:**
+- Track important user events with `gtag()`, `fbq()`, and `ttq()` functions
+- NEVER add conditional checks for tracking functions (e.g., `if (typeof gtag !== 'undefined')`)
+- Always assume tracking functions exist - they're globally available or stubbed
+- Reference standard events documentation before implementing custom tracking
+
+**Standard Events Documentation:**
+- **Google Analytics GA4:** https://developers.google.com/analytics/devguides/collection/ga4/reference/events
+- **Facebook Pixel:** https://www.facebook.com/business/help/402791146561655?id=1205376682832142
+- **TikTok Pixel:** https://ads.tiktok.com/help/article/standard-events-parameters?redirected=2
+
+### Platform-Specific Requirements
+
+#### TikTok Pixel Requirements
+TikTok has strict validation requirements:
+
+**Required Parameters:**
+- `content_id` - MUST be included in all events
+
+**Valid Content Types:**
+- `"product"`
+- `"product_group"`
+- `"destination"`
+- `"hotel"`
+- `"flight"`
+- `"vehicle"`
+
+Any other content type will generate a validation error.
+
+**Example:**
+```javascript
+// ✅ CORRECT
+ttq.track('ViewContent', {
+  content_id: 'product-123',
+  content_type: 'product'
+});
+
+// ❌ WRONG - Missing content_id
+ttq.track('ViewContent', {
+  content_type: 'product'
+});
+
+// ❌ WRONG - Invalid content_type
+ttq.track('ViewContent', {
+  content_id: 'product-123',
+  content_type: 'custom'  // Not in approved list
+});
+```
+
+### Tracking Implementation
+
+**IMPORTANT:** Always track events to ALL THREE platforms in this order:
+1. Google Analytics (gtag)
+2. Facebook Pixel (fbq)
+3. TikTok Pixel (ttq)
+
+Track events directly without existence checks. All three tracking calls should be made together for every event.
+
+**Development Mode:**
+In development mode, all tracking calls are intercepted and logged to the console for debugging. See `src/assets/js/libs/dev.js` for implementation.
+
 ## Audit Workflow
 
 When fixing issues identified by the audit task (`src/gulp/tasks/audit.js`):

package/dist/assets/js/core/auth.js

@@ -32,7 +32,7 @@ export default function (Manager, options) {
       console.log('[Auth] state changed:', state);
 
       // Set user ID for analytics tracking
-      setAnalyticsUserId(user);
+      setAnalyticsUserId(user, webManager);
 
       // Check if we're in the process of signing out
       if (authSignout === 'true' && user) {
@@ -119,9 +119,10 @@ function redirect(url, returnUrl) {
   window.location.href = newURL;
 }
 
-function setAnalyticsUserId(user) {
+function setAnalyticsUserId(user, webManager) {
   const userId = user?.uid;
   const email = user?.email;
+  const metaPixelId = webManager.config.tracking['meta-pixel'];
 
   // Short-circuit if no user
   if (!userId) {
@@ -129,7 +130,7 @@ function setAnalyticsUserId(user) {
     gtag('set', { user_id: null });
 
     // Facebook Pixel - Clear advanced matching
-    fbq('init', fbq.pixelId, {});
+    fbq('init', metaPixelId, {});
 
     // TikTok Pixel - Clear user data
     ttq.identify({});
@@ -147,7 +148,7 @@ function setAnalyticsUserId(user) {
   });
 
   // Facebook Pixel - Set advanced matching with user data
-  fbq('init', fbq.pixelId, {
+  fbq('init', metaPixelId, {
     external_id: userId,
     // em: email ? btoa(email.toLowerCase().trim()) : undefined,
     em: email,

package/dist/assets/js/core/cookieconsent.js

@@ -310,59 +310,66 @@ export default function (Manager, options) {
 
   // Tracking functions
   function trackCookieBannerShown() {
-    gtag('event', 'cookie_banner_shown', {
+    gtag('event', 'cookie_banner_show', {
       event_category: 'consent'
     });
-    fbq('trackCustom', 'CookieBannerShown');
+    fbq('trackCustom', 'CookieBannerShow');
     ttq.track('ViewContent', {
-      content_name: 'Cookie Banner'
+      content_id: 'cookie-banner-show',
+      content_type: 'product',
+      content_name: 'Cookie Banner Show'
     });
   }
 
   function trackCookieAccepted() {
-    gtag('event', 'cookie_consent_accepted', {
+    gtag('event', 'cookie_consent_accept', {
       event_category: 'consent',
       consent_type: config.type
     });
-    fbq('trackCustom', 'CookieConsentAccepted');
+    fbq('trackCustom', 'CookieConsentAccept');
     ttq.track('ClickButton', {
-      content_name: 'Cookie Consent Accept',
-      content_type: 'consent'
+      content_id: 'cookie-consent-accept',
+      content_type: 'product',
+      content_name: 'Cookie Consent Accept'
     });
   }
 
   function trackCookieDenied() {
-    gtag('event', 'cookie_consent_denied', {
+    gtag('event', 'cookie_consent_deny', {
       event_category: 'consent',
       consent_type: config.type
     });
-    fbq('trackCustom', 'CookieConsentDenied');
+    fbq('trackCustom', 'CookieConsentDeny');
     ttq.track('ClickButton', {
-      content_name: 'Cookie Consent Deny',
-      content_type: 'consent'
+      content_id: 'cookie-consent-deny',
+      content_type: 'product',
+      content_name: 'Cookie Consent Deny'
     });
   }
 
   function trackCookieAutoAccepted(trigger) {
-    gtag('event', 'cookie_consent_auto_accepted', {
+    gtag('event', 'cookie_consent_auto_accept', {
       event_category: 'consent',
       trigger: trigger
     });
-    fbq('trackCustom', 'CookieConsentAutoAccepted', {
+    fbq('trackCustom', 'CookieConsentAutoAccept', {
       trigger: trigger
     });
     ttq.track('ViewContent', {
-      content_name: 'Cookie Consent Auto Accept',
-      content_type: trigger
+      content_id: 'cookie-consent-auto-accept',
+      content_type: 'product',
+      content_name: 'Cookie Consent Auto Accept'
     });
   }
 
   function trackCookiePolicyReopened() {
-    gtag('event', 'cookie_policy_reopened', {
+    gtag('event', 'cookie_policy_reopen', {
       event_category: 'consent'
     });
-    fbq('trackCustom', 'CookiePolicyReopened');
+    fbq('trackCustom', 'CookiePolicyReopen');
     ttq.track('ClickButton', {
+      content_id: 'cookie-policy-reopen',
+      content_type: 'product',
       content_name: 'Cookie Policy Reopen'
     });
   }

package/dist/assets/js/core/exit-popup.js

@@ -177,20 +177,21 @@ export default function (Manager, options) {
 
   // Tracking functions
   function trackExitPopupShown() {
-    gtag('event', 'exit_popup_shown', {
+    gtag('event', 'exit_popup_show', {
       event_category: 'engagement',
       event_label: config.title,
       page_path: window.location.pathname
     });
 
-    fbq('trackCustom', 'ExitPopupShown', {
-      content_name: config.title,
+    fbq('trackCustom', 'ExitPopupShow', {
+      content_name: 'Exit Popup Show',
       page_path: window.location.pathname
     });
 
     ttq.track('ViewContent', {
-      content_name: 'Exit Popup',
-      content_type: config.title
+      content_id: 'exit-popup-show',
+      content_type: 'product',
+      content_name: 'Exit Popup Show'
     });
   }
 
@@ -207,24 +208,26 @@ export default function (Manager, options) {
     });
 
     ttq.track('ClickButton', {
-      content_name: 'Exit Popup CTA',
-      content_type: config.okButton?.text || 'OK'
+      content_id: 'exit-popup-click',
+      content_type: 'product',
+      content_name: 'Exit Popup Click'
     });
   }
 
   function trackExitPopupDismissed() {
-    gtag('event', 'exit_popup_dismissed', {
+    gtag('event', 'exit_popup_dismiss', {
       event_category: 'engagement',
       event_label: config.title
     });
 
-    fbq('trackCustom', 'ExitPopupDismissed', {
-      content_name: config.title
+    fbq('trackCustom', 'ExitPopupDismiss', {
+      content_name: 'Exit Popup Dismiss'
     });
 
     ttq.track('ViewContent', {
-      content_name: 'Exit Popup Dismissed',
-      content_type: config.title
+      content_id: 'exit-popup-dismiss',
+      content_type: 'product',
+      content_name: 'Exit Popup Dismiss'
     });
   }
 };

package/dist/assets/js/core/social-sharing.js

@@ -289,6 +289,8 @@ export default function (Manager, options) {
 
   // Tracking functions
   function trackShare(platformKey, shareConfig) {
+    const platformName = platforms[platformKey]?.name || platformKey;
+
     gtag('event', 'share', {
       method: platformKey,
       content_type: 'article',
@@ -302,9 +304,9 @@ export default function (Manager, options) {
     });
 
     ttq.track('Share', {
-      content_name: shareConfig.title,
-      content_url: shareConfig.url,
-      share_method: platformKey
+      content_id: `social-share-${platformKey}`,
+      content_type: 'product',
+      content_name: `Social Share ${platformName}`
     });
   }
 
@@ -319,7 +321,9 @@ export default function (Manager, options) {
     });
 
     ttq.track('ClickButton', {
-      content_name: 'Copy Link'
+      content_id: 'social-share-copy-link',
+      content_type: 'product',
+      content_name: 'Social Share Copy Link'
     });
   }
 };

package/dist/assets/js/libs/auth/pages.js

@@ -620,6 +620,7 @@ export default function (Manager) {
 
   function trackLogin(method, user) {
     const userId = user.uid;
+    const methodName = method.charAt(0).toUpperCase() + method.slice(1);
 
     // Google Analytics 4
     gtag('event', 'login', {
@@ -629,21 +630,22 @@ export default function (Manager) {
 
     // Facebook Pixel
     fbq('trackCustom', 'Login', {
+      content_name: `Account Login ${methodName}`,
       method: method,
-      status: 'success'
     });
 
     // TikTok Pixel
     ttq.track('Login', {
-      content_name: 'Account',
-      content_id: userId,
-      status: 'success'
+      content_id: `account-login-${method}`,
+      content_type: 'product',
+      content_name: `Account Login ${methodName}`
     });
   }
 
   // Analytics tracking functions
   function trackSignup(method, user) {
     const userId = user.uid;
+    const methodName = method.charAt(0).toUpperCase() + method.slice(1);
 
     // Google Analytics 4
     gtag('event', 'sign_up', {
@@ -653,17 +655,15 @@ export default function (Manager) {
 
     // Facebook Pixel
     fbq('track', 'CompleteRegistration', {
-      content_name: 'Account',
-      status: 'success',
-      value: 0,
-      currency: 'USD'
+      content_name: `Account Registration ${methodName}`,
+      method: method,
     });
 
     // TikTok Pixel
     ttq.track('CompleteRegistration', {
-      content_name: 'Account',
-      content_id: userId,
-      status: 'success'
+      content_id: `account-registration-${method}`,
+      content_type: 'product',
+      content_name: `Account Registration ${methodName}`
     });
   }
 
@@ -683,8 +683,9 @@ export default function (Manager) {
 
     // TikTok Pixel
     ttq.track('SubmitForm', {
-      content_name: 'Password Reset',
-      content_type: 'account_recovery'
+      content_id: 'password-reset',
+      content_type: 'product',
+      content_name: 'Password Reset'
     });
   }
 }