ultimate-jekyll-manager 1.2.0 → 1.2.2

package/docs/page-loading.md

@@ -0,0 +1,85 @@
+# Page Loading Protection System
+
+Ultimate Jekyll prevents race conditions by disabling buttons during JavaScript initialization.
+
+## How It Works
+
+1. HTML element starts with `data-page-loading="true"` and `aria-busy="true"` (`src/defaults/dist/_layouts/core/root.html`)
+2. Protected elements are automatically disabled during this state
+3. Attributes are removed when JavaScript completes (`src/assets/js/core/complete.js`)
+
+## Protected Elements
+
+- All form buttons (`<button>`, `<input type="submit">`, `<input type="button">`, `<input type="reset">`)
+- Elements with `.btn` class (Bootstrap buttons)
+- Elements with `.btn-action` class (custom action triggers)
+
+## The `.btn-action` Class
+
+Selectively protect non-standard elements that trigger important actions:
+
+```html
+<!-- Protected during page load -->
+<a href="/api/delete" class="custom-link btn-action">Delete Item</a>
+<div class="card-action btn-action" onclick="processData()">Process</div>
+
+<!-- NOT protected (regular navigation/UI) -->
+<a href="/about" class="btn btn-primary">About Us</a>
+<button data-bs-toggle="modal">Show Info</button>
+```
+
+**Use `.btn-action` for:**
+- API calls
+- Form submissions
+- Data modifications
+- Payment processing
+- Destructive actions
+
+**Don't use for:**
+- Navigation links
+- UI toggles (modals, accordions, tabs)
+- Harmless interactions
+
+## Implementation
+
+- **CSS:** `src/assets/css/core/utilities.scss` — Disabled styling
+- **Click Prevention:** `src/defaults/dist/_includes/core/body.html` — Inline script
+- **State Removal:** `src/assets/js/core/complete.js` — Removes loading state
+
+## Form Protection Standards
+
+All JS-managed forms use a layered protection strategy to prevent native form submission before JavaScript takes control:
+
+### Layer 1: `onsubmit="return false"` on ALL JS-managed forms
+
+Every `<form>` that will be managed by FormManager MUST include `onsubmit="return false"`:
+
+```html
+<form id="my-form" onsubmit="return false">
+```
+
+This is a zero-cost safety net that prevents native form submission if a user clicks submit before FormManager attaches its `e.preventDefault()` handler. FormManager's own submit handling overrides this — there is no conflict.
+
+**Exception:** Traditional forms with an `action` attribute that intentionally navigate (e.g., search forms, external form submissions) should NOT include this.
+
+### Layer 2: Button initial state based on use case
+
+| Use Case | Initial State | Mechanism |
+|----------|---------------|-----------|
+| Buttons dependent on async data (checkout payment methods) | `hidden` | `data-wm-bind="@show ..."` reveals when data loads |
+| Buttons on auth/sensitive forms | `disabled` | FormManager's `ready()` removes `disabled` |
+| Buttons on simple forms (contact, newsletter) | Default (visible) | FormManager's `autoReady: true` enables quickly |
+
+### Layer 3: FormManager `autoReady` configuration
+
+| Scenario | `autoReady` | `ready()` call |
+|----------|-------------|----------------|
+| No async work before form init | `true` (default) | Automatic on DOM ready |
+| Async work before form init (API calls, redirects) | `false` | Explicit call after async completes |
+
+**Reference implementations:**
+- Simple form: `src/assets/js/pages/contact/index.js`
+- Auth form: `src/assets/js/libs/auth.js`
+- Async data form: `src/assets/js/pages/payment/checkout/index.js`
+
+See also [docs/javascript-libraries.md → FormManager](javascript-libraries.md#formmanager-library) for the FormManager API itself.

package/docs/project-structure.md

@@ -0,0 +1,23 @@
+# Project Structure
+
+UJM is a template framework that consuming projects install as an NPM module to build Jekyll sites quickly and efficiently. It provides best-practice configurations, default components, themes, and build tools.
+
+> **UJM is NOT a standalone project.** You cannot run `npm start` or `npm run build` directly in this repository. The user already has a development server running in a consuming project — running those commands here would either fail or create duplicate servers unnecessarily. See [the Identity section in CLAUDE.md](../CLAUDE.md#identity) for what IS safe to run inside UJM itself.
+
+## Directory Organization (UJM repo)
+
+| Path | Purpose |
+|---|---|
+| `src/gulp/tasks` | Gulp tasks for building Jekyll sites |
+| `src/defaults/src` | Default source files (editable by users, copied to consuming project's `src/`) |
+| `src/defaults/dist` | Default distribution files (not editable by users, copied to consuming project's `dist/`) |
+| `src/assets/css` | Stylesheets (global, pages, themes) |
+| `src/assets/js` | JavaScript modules (core, pages, libraries) |
+| `src/assets/themes` | Theme SCSS and JS files |
+
+## Consuming Project Structure
+
+| Path | Purpose |
+|---|---|
+| `src/` | Compiled to `dist/` via npm |
+| `dist/` | Compiled to `_site/` via Jekyll |

package/docs/seo.md

@@ -0,0 +1,206 @@
+# SEO — Alternatives Pages & Structured Data
+
+This doc covers two SEO-focused subsystems:
+
+1. **Alternatives Collection** — competitor comparison landing pages.
+2. **Schema / Structured Data (JSON-LD)** — `SoftwareApplication` and `FAQPage` JSON-LD blocks.
+
+## Alternatives Collection (SEO Competitor Comparison Pages)
+
+UJ provides an `alternatives` collection for SEO landing pages that target users searching for competitors (e.g., "ExampleApp alternatives"). These pages are entirely frontmatter-driven and designed to convert visitors who are comparing products.
+
+### How It Works
+
+1. The `alternatives` collection is registered in `src/config/_config_default.yml` (UJM-controlled)
+2. Each alternative is a markdown file in the consuming project's `_alternatives/` directory
+3. The layout chain: `blueprint/alternatives/alternative` → `themes/classy/frontend/pages/alternatives/alternative`
+4. An index page at `/alternatives` lists all alternatives automatically
+5. **Shared content lives in the layout** — the theme layout provides default testimonials, stats, FAQs, CTA, and why_switch content so competitor pages only need competitor-specific data
+6. The layout frontmatter uses `{{ page.resolved.alternative.competitor.name }}` to dynamically insert the competitor name into shared content (e.g., FAQ questions, CTA headlines)
+
+### Creating an Alternative Page
+
+In the consuming project, create `src/_alternatives/competitor-name.md`. Only competitor-specific data is needed — shared sections are inherited from the layout:
+
+```yaml
+---
+layout: blueprint/alternatives/alternative
+sitemap:
+  include: true
+
+alternative:
+  competitor:
+    name: "Competitor Name"
+    description: "Brief description of the competitor (shown on /alternatives listing)"
+  comparison:
+    features:
+      - name: "Feature Name"
+        icon: "sparkles"
+        ours:
+          value: true  # or string like "Unlimited"
+        theirs:
+          value: false  # or string like "Limited"
+---
+```
+
+That's it! The layout automatically generates:
+- Hero with "Brand vs Competitor Name" headline
+- Why Switch section with default differentiator items
+- Testimonials, Stats, FAQs, and CTA with shared content
+- All text dynamically references the competitor name via `{{ page.resolved.alternative.competitor.name }}`
+
+**To override any inherited section**, define it in the competitor's frontmatter — `page.resolved` merge gives page-level values highest priority.
+
+### Available Sections
+
+All sections are **optional** — omit or leave empty to hide. Sections with `(shared)` have default content in the layout:
+
+| Section | Frontmatter Key | Description |
+|---------|----------------|-------------|
+| Hero | `alternative.hero` | Gradient animated hero with "Brand vs Competitor" headline (shared) |
+| Comparison | `alternative.comparison` | Side-by-side feature table — **must be defined per competitor** |
+| Why Switch | `alternative.why_switch` | Alternating image/text showcase blocks (shared) |
+| Video | `alternative.video` | YouTube embed (default: hidden, set `youtube_id` to show) |
+| Testimonials | `alternative.testimonials` | Reuses `testimonial-scroll.html` component (shared) |
+| Stats | `alternative.stats` | Social proof numbers with icons (shared) |
+| FAQs | `alternative.faqs` | Accordion with switching-related questions (shared) |
+| CTA | `alternative.cta` | Final conversion card with buttons (shared) |
+
+### Dynamic Competitor Name in Frontmatter
+
+The layout uses `{{ page.resolved.alternative.competitor.name }}` in its frontmatter defaults to dynamically reference the competitor. This works because the template pipes these values through `| uj_liquify` to resolve Liquid expressions.
+
+**Example:** The layout's default FAQ includes:
+
+```yaml
+question: "Can I import my data from {{ page.resolved.alternative.competitor.name }}?"
+```
+
+Which renders as "Can I import my data from ExampleApp?" for an ExampleApp competitor page.
+
+### Reference Implementation
+
+- **Minimal competitor page:** `src/defaults/dist/_alternatives/example-competitor.md` — shows the minimum frontmatter needed (competitor name + comparison features)
+- **Layout with all defaults:** `src/defaults/dist/_layouts/themes/classy/frontend/pages/alternatives/alternative.html` — contains shared content for all sections
+
+### File Locations
+
+| Purpose | Path |
+|---------|------|
+| Theme layout (alternative page) | `src/defaults/dist/_layouts/themes/classy/frontend/pages/alternatives/alternative.html` |
+| Theme layout (index/listing page) | `src/defaults/dist/_layouts/themes/classy/frontend/pages/alternatives/index.html` |
+| Blueprint (alternative) | `src/defaults/dist/_layouts/blueprint/alternatives/alternative.html` |
+| Blueprint (index) | `src/defaults/dist/_layouts/blueprint/alternatives/index.html` |
+| Default page (index) | `src/defaults/dist/pages/alternatives/index.md` |
+| Sample alternative | `src/defaults/dist/_alternatives/example-competitor.md` |
+| CSS | `src/assets/css/pages/alternatives/alternative/index.scss` |
+| JS | `src/assets/js/pages/alternatives/alternative/index.js` |
+
+## Schema / Structured Data (JSON-LD)
+
+UJ automatically generates JSON-LD structured data in `foot.html`. The SoftwareApplication schema with AggregateRating is opt-in via frontmatter.
+
+### SoftwareApplication Schema
+
+Renders a `SoftwareApplication` JSON-LD block with deterministic aggregate ratings. Enabled by blueprint layouts (index, pricing, download, alternatives/alternative) — consuming projects can override or disable per page.
+
+**How it works:**
+
+1. **`_config.yml`** sets fallback defaults (no `enabled` key — just field defaults like `application_category`, `price`, etc.)
+2. **Blueprint layouts** set `schema.software_application.enabled: true` with page-appropriate `features`
+3. **Consuming projects** can override any value in their page frontmatter, or disable with `enabled: false`
+
+This follows the standard `page.resolved` merge: page > layout > site.
+
+**Deterministic ratings:** Uses the `uj_hash` filter (from jekyll-uj-powertools) seeded with `site.url` by default, producing stable values across builds:
+- Rating: always `4.8` or `4.9` (deterministic per seed)
+- Review count: 200,000–999,999 (deterministic per seed)
+- Override seed per page with `hash_seed` to get different values
+
+**Blueprint frontmatter example:**
+
+```yaml
+### SCHEMA ###
+schema:
+  software_application:
+    enabled: true
+    features:
+      - "Free to use"
+      - "24/7 availability"
+      - "User-friendly interface"
+```
+
+**Consuming project override example:**
+
+```yaml
+schema:
+  software_application:
+    application_category: "EducationalApplication"
+    features:
+      - "AI-powered solutions"
+      - "24/7 availability"
+```
+
+**Consuming project disable example:**
+
+```yaml
+schema:
+  software_application:
+    enabled: false
+```
+
+**Available fields:**
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | (set by blueprint) | Enable/disable the schema block |
+| `name` | `site.brand.name` | Application name |
+| `description` | `page.resolved.meta.description` | Application description |
+| `application_category` | `WebApplication` | Schema.org application category |
+| `operating_system` | `Web-based` | Target OS |
+| `price` | `0` | Price (string) |
+| `price_currency` | `USD` | Currency code |
+| `features` | `[]` | Feature list for `featureList` field |
+| `hash_seed` | `site.url` | Seed for deterministic rating/count generation |
+
+**File locations:**
+
+| Purpose | Path |
+|---------|------|
+| Schema block (rendering) | `src/defaults/dist/_includes/core/foot.html` |
+| Site-level defaults | `src/defaults/src/_config.yml` (under `schema:`) |
+| Blueprint activation | `src/defaults/dist/_layouts/blueprint/{index,pricing,download}.html`, `blueprint/alternatives/alternative.html` |
+| Hash filter | `jekyll-uj-powertools/lib/filters/main.rb` (`uj_hash`) |
+
+### FAQPage Schema
+
+Renders a `FAQPage` JSON-LD block for pages with FAQ/accordion sections. Enabled by the alternatives blueprint — consuming projects can also enable it on any page with FAQ content.
+
+**How it works:**
+
+1. **`_config.yml`** sets `faq_page.items: []` as fallback
+2. **Blueprint layouts** set `schema.faq_page.enabled: true`
+3. **Items source (fallback chain):** `schema.faq_page.items` → `page.resolved.faqs.items` → `page.resolved.alternative.faqs.items`. Pages with generic `faqs.items` (like pricing) and alternatives pages both get FAQPage schema automatically without duplicating content
+4. Questions/answers are processed through `uj_liquify` (supports Liquid expressions like competitor names) and `uj_json_escape`
+
+**Blueprint activation:** Enabled by default in `blueprint/pricing.html`, `blueprint/contact.html`, `blueprint/download.html`, `blueprint/extension/index.html`, and `blueprint/alternatives/alternative.html`.
+
+**Consuming project usage — provide items directly:**
+
+```yaml
+schema:
+  faq_page:
+    enabled: true
+    items:
+      - question: "How do I get started?"
+        answer: "Sign up for free and follow the onboarding guide."
+      - question: "Is there a free plan?"
+        answer: "Yes, our basic plan is completely free."
+```
+
+**Available fields:**
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | (set by blueprint) | Enable/disable the schema block |
+| `items` | `[]` | Array of `{question, answer}` objects. Falls back to `alternative.faqs.items` if empty |

package/docs/xss-prevention.md

@@ -0,0 +1,126 @@
+# XSS Prevention (ZERO TRUST — MANDATORY)
+
+**TREAT ALL DYNAMIC DATA AS UNTRUSTED.** This is a zero-trust policy: any value that did not come directly from a hardcoded literal in the source file MUST be escaped before being inserted into the DOM via `innerHTML` or attribute interpolation.
+
+This includes — but is not limited to:
+- Firestore document fields (user names, emails, IDs, descriptions, etc.)
+- API response data
+- URL parameters (`location.search`, `URLSearchParams`)
+- User input from form fields
+- OAuth-provided values (displayName, email from Google/GitHub)
+- Any variable whose origin is not a hardcoded source-code constant
+
+## The Rule
+
+```javascript
+// ✅ ALWAYS escape dynamic data before innerHTML
+$el.innerHTML = `<p>${webManager.utilities().escapeHTML(data.title)}</p>`;
+$el.innerHTML = `<a href="${webManager.utilities().escapeHTML(url)}">${webManager.utilities().escapeHTML(label)}</a>`;
+
+// ✅ textContent is always safe — no escaping needed
+$el.textContent = data.title;
+
+// ❌ NEVER inject dynamic data raw into innerHTML
+$el.innerHTML = `<p>${data.title}</p>`;
+$el.innerHTML = `<a href="${url}">${label}</a>`;
+```
+
+## NEVER Write Your Own Escape Function
+
+Do NOT create a local `escapeHtml` function or any variant. The ONLY allowed escape method is:
+
+```javascript
+webManager.utilities().escapeHTML(str)
+```
+
+## When Building DOM Programmatically
+
+Prefer `document.createElement` + `textContent` for plain text nodes — it is inherently safe:
+
+```javascript
+const $el = document.createElement('div');
+$el.textContent = data.message; // Safe — no escaping needed
+```
+
+Only use `innerHTML` when you need actual HTML structure (tags, classes, etc.), and escape every dynamic value in it.
+
+## Even "Safe" Values Must Be Escaped
+
+Even values that *seem* safe (like `Date.toLocaleDateString()` output, numeric calculations, or hardcoded config strings) MUST be escaped when inserted via `innerHTML`. This is defense-in-depth — if the data source ever changes, the escaping is already in place.
+
+```javascript
+// ✅ CORRECT — escape even "safe" values in innerHTML
+$el.innerHTML = `<small>${webManager.utilities().escapeHTML(formatDate(timestamp))}</small>`;
+$el.innerHTML = `<span>${webManager.utilities().escapeHTML(reason)}</span>`;
+
+// ❌ WRONG — assuming the value is safe because it's from a date formatter
+$el.innerHTML = `<small>${formatDate(timestamp)}</small>`;
+```
+
+## Redirects Must Be Validated
+
+Never redirect to a URL from untrusted sources without validation:
+
+```javascript
+// ✅ CORRECT — validate before redirect
+const url = urlParams.get('returnUrl');
+if (url && webManager.isValidRedirectUrl(url)) {
+  window.location.href = url;
+}
+
+// ✅ CORRECT — validate API response URLs have safe scheme
+if (response.url && /^https?:\/\//i.test(response.url)) {
+  window.location.href = response.url;
+}
+
+// ❌ WRONG — redirect to unvalidated input
+window.location.href = urlParams.get('returnUrl');
+```
+
+## postMessage Handlers Must Check Origin
+
+Always validate `event.origin` when handling `window.addEventListener('message', ...)`:
+
+```javascript
+// ✅ CORRECT
+window.addEventListener('message', (event) => {
+  if (event.origin !== window.location.origin && event.origin !== 'https://trusted-domain.com') {
+    return;
+  }
+  // handle message
+});
+
+// ❌ WRONG — any origin can send messages
+window.addEventListener('message', (event) => {
+  window.location.href = event.data.url; // attacker-controlled redirect
+});
+```
+
+## Never Use eval() or new Function()
+
+Do not use `eval()`, `new Function()`, `setTimeout(string)`, or `setInterval(string)`. These execute arbitrary code and violate CSP policies.
+
+## Sanitize Markdown/Rich Text Output
+
+When rendering user-authored markdown or rich text, use DOMPurify to sanitize the output:
+
+```javascript
+import DOMPurify from 'dompurify';
+const safeHTML = DOMPurify.sanitize(md.render(userContent), {
+  ALLOWED_TAGS: ['h1', 'h2', 'h3', 'p', 'br', 'a', 'b', 'strong', 'i', 'em', 'ul', 'ol', 'li', 'img', 'code', 'pre'],
+  ALLOWED_ATTR: ['href', 'src', 'alt', 'title', 'class', 'target', 'rel'],
+});
+```
+
+## Do NOT Escape Values Passed to textContent-Based APIs
+
+`showNotification()`, `formManager.showSuccess()`, `formManager.showError()`, and `textContent` assignments use safe text insertion internally. Pre-escaping these causes double-encoding (e.g., `We'll` displays as `We&#039;ll`).
+
+```javascript
+// ✅ CORRECT — these APIs use textContent internally, so they're already safe
+webManager.utilities().showNotification('Thank you! We\'ll be in touch.', 'success');
+formManager.showSuccess('Message sent successfully!');
+
+// ❌ WRONG — double-escapes
+webManager.utilities().showNotification(webManager.utilities().escapeHTML(message), 'success');
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultimate-jekyll-manager",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Ultimate Jekyll dependency manager",
   "main": "dist/index.js",
   "exports": {