ultimate-jekyll-manager 0.0.118 → 0.0.120

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
 
-1. **Define icons in page frontmatter:**
+**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>
+```
+
+**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()`
+
+### What NOT to Do
 
-3. **Access icons in JavaScript:**
+**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
 
@@ -378,21 +597,188 @@ const response = await authorizedFetch(url, options);
 
 #### FormManager Library
 
-Form handling library with built-in state management and validation.
+Lightweight form state management library with built-in validation, state machine, and event system.
 
 **Import:**
 ```javascript
 import { FormManager } from '__main_assets__/js/libs/form-manager.js';
 ```
 
-**Usage:**
+**Basic Usage:**
 ```javascript
 const formManager = new FormManager('#my-form', options);
+
+formManager.on('submit', async ({ data, $submitButton }) => {
+  const response = await fetch('/api', { body: JSON.stringify(data) });
+  if (!response.ok) throw new Error('Failed');
+  formManager.showSuccess('Form submitted!');
+});
+```
+
+**State Machine:**
+```
+initializing → ready ⇄ submitting → ready (or submitted)
+```
+
+**Configuration Options:**
+```javascript
+{
+  autoReady: true,           // Auto-transition to initialState when DOM ready
+  initialState: 'ready',     // State after autoReady fires
+  allowResubmit: true,       // Allow resubmission after success (false = 'submitted' state)
+  resetOnSuccess: false,     // Clear form fields after successful submission
+  warnOnUnsavedChanges: false, // Warn user before leaving with unsaved changes
+  submittingText: 'Processing...', // Text shown on submit button during submission
+  submittedText: 'Processed!'  // Text shown on submit button after success (when allowResubmit: false)
+}
+```
+
+**Events:**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `submit` | `{ data, $submitButton }` | Form submission (throw error to show failure) |
+| `validation` | `{ data, setError }` | Custom validation before submit |
+| `change` | `{ field, name, value, data }` | Field value changed |
+| `statechange` | `{ state, previousState }` | State transition |
+
+**Validation System:**
+
+FormManager runs validation automatically before `submit`:
+1. **HTML5 validation** - Checks `required`, `minlength`, `maxlength`, `min`, `max`, `pattern`, `type="email"`, `type="url"`
+2. **Custom validation** - Use `validation` event for business logic
+
+```javascript
+fm.on('validation', ({ data, setError }) => {
+  if (data.age && parseInt(data.age) < 18) {
+    setError('age', 'You must be 18 or older');
+  }
+});
+```
+
+Errors display with Bootstrap's `is-invalid` class and `.invalid-feedback` elements.
+
+**Autofocus:**
+
+When the form transitions to `ready` state, FormManager automatically focuses the field with the `autofocus` attribute (if present and not disabled).
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `on(event, callback)` | Register event listener (chainable) |
+| `ready()` | Transition to ready state |
+| `getData()` | Get form data as nested object (supports dot notation) |
+| `setData(obj)` | Set form values from nested object |
+| `showSuccess(msg)` | Show success notification |
+| `showError(msg)` | Show error notification |
+| `reset()` | Reset form and go to ready state |
+| `isDirty()` | Check if form has unsaved changes |
+| `setDirty(bool)` | Set dirty state |
+| `clearFieldErrors()` | Clear all field validation errors |
+| `throwFieldErrors({ field: msg })` | Set and display field errors, throw error |
+
+**Nested Field Names (Dot Notation):**
+
+Use dot notation in field names for nested data:
+```html
+<input name="user.address.city" value="NYC">
+```
+
+Results in:
+```javascript
+{ user: { address: { city: 'NYC' } } }
+```
+
+**Checkbox Handling:**
+- **Single checkbox:** Returns `true`/`false`
+- **Checkbox group (same name):** Returns object `{ value1: true, value2: false }`
+
+**Multiple Submit Buttons:**
+
+Access the clicked button via `$submitButton`:
+```html
+<button type="submit" data-action="save">Save</button>
+<button type="submit" data-action="draft">Save Draft</button>
+```
+
+```javascript
+fm.on('submit', async ({ data, $submitButton }) => {
+  const action = $submitButton?.dataset?.action; // 'save' or 'draft'
+});
 ```
 
 **Reference:** `src/assets/js/libs/form-manager.js`
+**Test Page:** `src/assets/js/pages/test/libraries/form-manager/index.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/README.md

@@ -381,14 +381,183 @@ const response = await authorizedFetch(serverApiURL, {
 
 #### FormManager Library
 
-Custom library for form handling with built-in state management and validation.
+Lightweight form state management library with built-in validation, state machine, and event system.
 
 **Import:**
 ```javascript
 import { FormManager } from '__main_assets__/js/libs/form-manager.js';
 ```
 
-**Documentation:** See [form-manager.js](src/assets/js/libs/form-manager.js) for full API and usage examples.
+**Basic Usage:**
+```javascript
+const formManager = new FormManager('#my-form', {
+  allowResubmit: true,      // Allow form to be submitted again after success
+  resetOnSuccess: false,    // Don't clear fields after success
+  warnOnUnsavedChanges: false // Don't warn on page leave
+});
+
+// Handle form submission
+formManager.on('submit', async ({ data, $submitButton }) => {
+  const response = await fetch('/api/submit', {
+    method: 'POST',
+    body: JSON.stringify(data)
+  });
+
+  if (!response.ok) {
+    throw new Error('Submission failed');
+  }
+
+  formManager.showSuccess('Form submitted successfully!');
+});
+```
+
+**State Machine:**
+```
+initializing → ready ⇄ submitting → ready (or submitted)
+```
+
+**Events:**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `submit` | `{ data, $submitButton }` | Form submission. Throw an error to show failure message. |
+| `validation` | `{ data, setError }` | Custom validation before submit. Use `setError(fieldName, message)` to add errors. |
+| `change` | `{ field, name, value, data }` | Called when any field value changes. |
+| `statechange` | `{ state, previousState }` | Called when form state changes. |
+
+**Validation:**
+
+FormManager runs validation automatically before the `submit` event:
+
+1. **HTML5 Validation** - Automatically checks `required`, `minlength`, `maxlength`, `min`, `max`, `pattern`, `type="email"`, `type="url"`
+2. **Custom Validation** - Use the `validation` event for business logic
+
+```javascript
+formManager.on('validation', ({ data, setError }) => {
+  // Custom validation runs AFTER HTML5 validation
+  if (data.age && parseInt(data.age) < 18) {
+    setError('age', 'You must be 18 or older');
+  }
+
+  if (data.password !== data.confirmPassword) {
+    setError('confirmPassword', 'Passwords do not match');
+  }
+});
+```
+
+Validation errors are displayed using Bootstrap's `is-invalid` class and `.invalid-feedback` elements. The first field with an error is automatically focused.
+
+**Autofocus:**
+
+When the form transitions to `ready` state, FormManager automatically focuses any field with the `autofocus` attribute:
+
+```html
+<input type="text" name="email" autofocus>
+```
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `on(event, callback)` | Register event listener (chainable) |
+| `ready()` | Manually transition to ready state (for `autoReady: false`) |
+| `getData()` | Get form data as nested object |
+| `setData(obj)` | Populate form from a nested object |
+| `showSuccess(msg)` | Show success notification |
+| `showError(msg)` | Show error notification |
+| `reset()` | Reset form and state |
+| `isDirty()` | Check if form has unsaved changes |
+| `clearFieldErrors()` | Clear all validation error displays |
+| `throwFieldErrors({ field: msg })` | Set errors and throw (for use in submit handler) |
+
+**Nested Field Names (Dot Notation):**
+
+Use dot notation in field `name` attributes for nested data structures:
+
+```html
+<input name="user.name" value="John">
+<input name="user.address.city" value="NYC">
+<input name="user.address.zip" value="10001">
+```
+
+Produces:
+```javascript
+{
+  user: {
+    name: 'John',
+    address: {
+      city: 'NYC',
+      zip: '10001'
+    }
+  }
+}
+```
+
+**Checkbox Handling:**
+
+- **Single checkbox:** Returns `true` or `false`
+- **Checkbox group (multiple with same name):** Returns object with each value as key
+
+```html
+<!-- Single checkbox -->
+<input type="checkbox" name="subscribe" checked>
+<!-- Result: { subscribe: true } -->
+
+<!-- Checkbox group -->
+<input type="checkbox" name="features" value="darkmode" checked>
+<input type="checkbox" name="features" value="analytics">
+<input type="checkbox" name="features" value="beta" checked>
+<!-- Result: { features: { darkmode: true, analytics: false, beta: true } } -->
+```
+
+**Multiple Submit Buttons:**
+
+Access the clicked submit button to handle different actions:
+
+```html
+<button type="submit" data-action="save">Save</button>
+<button type="submit" data-action="draft">Save as Draft</button>
+```
+
+```javascript
+formManager.on('submit', async ({ data, $submitButton }) => {
+  const action = $submitButton?.dataset?.action;
+
+  if (action === 'draft') {
+    await saveDraft(data);
+    formManager.showSuccess('Draft saved!');
+  } else {
+    await saveAndPublish(data);
+    formManager.showSuccess('Published!');
+  }
+});
+```
+
+**Manual Ready Mode:**
+
+For forms that need async initialization (e.g., loading data from API):
+
+```javascript
+const formManager = new FormManager('#my-form', { autoReady: false });
+
+// Load data, then mark ready
+const userData = await fetchUserData();
+formManager.setData(userData);
+formManager.ready(); // Now form is interactive
+```
+
+**Configuration Options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `autoReady` | `true` | Auto-transition to ready when DOM is ready |
+| `initialState` | `'ready'` | State after autoReady fires |
+| `allowResubmit` | `true` | Allow form resubmission after success |
+| `resetOnSuccess` | `false` | Clear fields after successful submission |
+| `warnOnUnsavedChanges` | `false` | Show browser warning when leaving with unsaved changes |
+| `submittingText` | `'Processing...'` | Text shown on submit button during submission |
+
+**Test Page:** Navigate to `/test/libraries/form-manager` to see FormManager in action with various configurations.
 
 ### Icons
 * Fontawesome