ultimate-jekyll-manager 0.0.187 → 0.0.189

package/dist/assets/js/core/appearance.js

@@ -0,0 +1,197 @@
+/**
+ * Appearance Module
+ * Handles theme appearance switching (dark, light, system)
+ */
+
+// Constants
+const STORAGE_KEY = 'appearance.preference';
+const VALID_VALUES = ['dark', 'light', 'system'];
+
+// Module state
+let webManager = null;
+let mediaQuery = null;
+
+// Module
+export default (Manager) => {
+  // Shortcuts
+  webManager = Manager.webManager;
+
+  // Create appearance API
+  const appearanceAPI = {
+    /**
+     * Get the current saved preference
+     * @returns {string|null} 'dark', 'light', 'system', or null if not set
+     */
+    get: () => webManager.storage().get(STORAGE_KEY) || null,
+
+    /**
+     * Get the resolved (actual) theme being displayed
+     * @returns {string} 'dark' or 'light'
+     */
+    getResolved: () => document.documentElement.getAttribute('data-bs-theme') || 'dark',
+
+    /**
+     * Set the appearance preference
+     * @param {string} value - 'dark', 'light', or 'system'
+     */
+    set: (value) => {
+      // Validate
+      if (!VALID_VALUES.includes(value)) {
+        console.warn(`Invalid appearance value: ${value}. Must be one of: ${VALID_VALUES.join(', ')}`);
+        return;
+      }
+
+      // Save preference
+      webManager.storage().set(STORAGE_KEY, value);
+
+      // Apply theme
+      applyTheme(value);
+
+      // Update UI elements
+      updateUI(value);
+
+      // Setup or teardown system preference listener
+      setupSystemListener(value === 'system');
+    },
+
+    /**
+     * Toggle between dark and light (skips system)
+     */
+    toggle() {
+      const current = this.getResolved();
+      const next = current === 'dark' ? 'light' : 'dark';
+      this.set(next);
+    },
+
+    /**
+     * Cycle through all three modes: dark → light → system → dark
+     */
+    cycle() {
+      const current = this.get() || this.getResolved();
+      const order = ['dark', 'light', 'system'];
+      const currentIndex = order.indexOf(current);
+      const nextIndex = (currentIndex + 1) % order.length;
+      this.set(order[nextIndex]);
+    },
+
+    /**
+     * Clear saved preference (revert to site default)
+     */
+    clear: () => {
+      webManager.storage().remove(STORAGE_KEY);
+      updateUI(null);
+      setupSystemListener(false);
+    }
+  };
+
+  // Register on UJ library
+  webManager._ujLibrary.appearance = appearanceAPI;
+
+  // Initialize UI event listeners
+  initializeUI();
+
+  // Setup system listener if current preference is 'system'
+  const currentPreference = appearanceAPI.get();
+  if (currentPreference === 'system') {
+    setupSystemListener(true);
+  }
+
+  // Update UI with current state
+  updateUI(currentPreference);
+
+  console.log('Appearance module loaded');
+};
+
+/**
+ * Apply theme to the document
+ * @param {string} preference - 'dark', 'light', or 'system'
+ */
+const applyTheme = (preference) => {
+  let theme = preference;
+
+  // Resolve system preference
+  if (preference === 'system') {
+    theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  }
+
+  // Apply to document
+  document.documentElement.setAttribute('data-bs-theme', theme);
+};
+
+/**
+ * Setup or teardown the system preference change listener
+ * @param {boolean} enable - Whether to enable the listener
+ */
+const setupSystemListener = (enable) => {
+  // Clean up existing listener
+  if (mediaQuery) {
+    mediaQuery.removeEventListener('change', handleSystemChange);
+    mediaQuery = null;
+  }
+
+  // Setup new listener if needed
+  if (enable) {
+    mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    mediaQuery.addEventListener('change', handleSystemChange);
+  }
+};
+
+/**
+ * Handle system preference change
+ * @param {MediaQueryListEvent} event
+ */
+const handleSystemChange = (event) => {
+  const theme = event.matches ? 'dark' : 'light';
+  document.documentElement.setAttribute('data-bs-theme', theme);
+  updateUI('system');
+};
+
+/**
+ * Initialize UI event listeners
+ */
+const initializeUI = () => {
+  // Use event delegation for appearance controls
+  document.addEventListener('click', (event) => {
+    const $target = event.target.closest('[data-appearance-set]');
+
+    if (!$target) {
+      return;
+    }
+
+    event.preventDefault();
+
+    const value = $target.getAttribute('data-appearance-set');
+    webManager.uj().appearance.set(value);
+  });
+};
+
+/**
+ * Update UI elements to reflect current state
+ * @param {string|null} preference - Current preference
+ */
+const updateUI = (preference) => {
+  const resolved = document.documentElement.getAttribute('data-bs-theme');
+  const displayValue = preference || resolved;
+
+  // Update [data-appearance-current] elements with the preference
+  document.querySelectorAll('[data-appearance-current]').forEach(($el) => {
+    const format = $el.getAttribute('data-appearance-current') || 'preference';
+    $el.textContent = format === 'resolved' ? resolved : displayValue;
+  });
+
+  // Update [data-appearance-icon] elements - show/hide based on current mode
+  // Icons should have data-appearance-icon="light|dark|system" attribute
+  document.querySelectorAll('[data-appearance-icon]').forEach(($el) => {
+    const iconMode = $el.getAttribute('data-appearance-icon');
+    $el.hidden = iconMode !== displayValue;
+  });
+
+  // Update active state on [data-appearance-set] elements
+  document.querySelectorAll('[data-appearance-set]').forEach(($el) => {
+    const value = $el.getAttribute('data-appearance-set');
+    const isActive = value === preference || (!preference && value === resolved);
+
+    $el.classList.toggle('active', isActive);
+    $el.setAttribute('aria-pressed', isActive ? 'true' : 'false');
+  });
+};

package/dist/assets/js/modules/vert.js

@@ -151,8 +151,8 @@ const createCustomAd = ($vertUnit, config) => {
   const iframeId = `vert-${window.__ujVertIdCounter = (window.__ujVertIdCounter || 0) + 1}`;
 
   // Build base URL for the ad content
-  // Use local server if debug=true OR if we're in development mode
-  const baseURL = (qsDebug || webManager.isDevelopment())
+  // Use local server if debug=true OR if we're in development mode AND on promo-server
+  const baseURL = (qsDebug || (webManager.isDevelopment() && webManager.config.brand.id === 'promo-server'))
     ? `${window.location.protocol}//${window.location.host}/verts/main`
     : 'https://promo-server.itwcreativeworks.com/verts/main';
 

package/dist/assets/js/pages/test/libraries/appearance/index.js

@@ -0,0 +1,214 @@
+/**
+ * Appearance Test Page JavaScript
+ */
+
+// Libraries
+let webManager = null;
+
+// Module
+export default (Manager) => {
+  return new Promise(async function (resolve) {
+    // Shortcuts
+    webManager = Manager.webManager;
+
+    // Initialize when DOM is ready
+    await webManager.dom().ready();
+
+    // Initialize debug panel
+    initDebugPanel();
+
+    // Initialize programmatic controls
+    initControls();
+
+    // Initialize event logging
+    initEventLog();
+
+    // Resolve after initialization
+    return resolve();
+  });
+};
+
+/**
+ * Initialize debug panel with live values
+ */
+function initDebugPanel() {
+  const $debugSaved = document.getElementById('debug-saved');
+  const $debugResolved = document.getElementById('debug-resolved');
+  const $debugAttr = document.getElementById('debug-attr');
+  const $debugLocalStorage = document.getElementById('debug-localstorage');
+  const $debugSystem = document.getElementById('debug-system');
+  const $btnRefresh = document.getElementById('btn-refresh');
+
+  // Update function
+  function updateDebug() {
+    const appearance = webManager.uj().appearance;
+
+    // Saved preference via API
+    const saved = appearance.get();
+    $debugSaved.textContent = saved !== null ? `"${saved}"` : 'null (not set)';
+
+    // Resolved theme via API
+    const resolved = appearance.getResolved();
+    $debugResolved.textContent = `"${resolved}"`;
+
+    // Raw HTML attribute
+    const attr = document.documentElement.getAttribute('data-bs-theme');
+    $debugAttr.textContent = `"${attr}"`;
+
+    // Raw localStorage value (stored under _manager.appearance.preference)
+    let rawStorage = null;
+    try {
+      const managerData = localStorage.getItem('_manager');
+      const parsedData = managerData ? JSON.parse(managerData) : null;
+      rawStorage = parsedData?.appearance?.preference || null;
+    } catch (e) {
+      rawStorage = '(error reading)';
+    }
+    $debugLocalStorage.textContent = rawStorage !== null ? `"${rawStorage}"` : 'null';
+
+    // System preference
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    const systemPref = prefersDark ? 'dark' : 'light';
+    $debugSystem.textContent = `"${systemPref}" (prefers-color-scheme: ${prefersDark ? 'dark' : 'light'})`;
+
+    console.log('[Appearance Test] Debug updated:', {
+      saved,
+      resolved,
+      attr,
+      rawStorage,
+      systemPref,
+    });
+  }
+
+  // Initial update
+  updateDebug();
+
+  // Refresh button
+  $btnRefresh.addEventListener('click', updateDebug);
+
+  // Auto-update when theme changes (observe attribute changes)
+  const observer = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+      if (mutation.attributeName === 'data-bs-theme') {
+        updateDebug();
+      }
+    });
+  });
+  observer.observe(document.documentElement, { attributes: true });
+
+  // Also listen for system preference changes
+  const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+  mediaQuery.addEventListener('change', updateDebug);
+
+  // Export for console access
+  window.updateAppearanceDebug = updateDebug;
+}
+
+/**
+ * Initialize programmatic control buttons
+ */
+function initControls() {
+  const appearance = webManager.uj().appearance;
+
+  // Toggle button
+  document.getElementById('btn-toggle').addEventListener('click', () => {
+    console.log('[Appearance Test] Toggle clicked');
+    appearance.toggle();
+  });
+
+  // Cycle button
+  document.getElementById('btn-cycle').addEventListener('click', () => {
+    console.log('[Appearance Test] Cycle clicked');
+    appearance.cycle();
+  });
+
+  // Clear button
+  document.getElementById('btn-clear').addEventListener('click', () => {
+    console.log('[Appearance Test] Clear clicked');
+    appearance.clear();
+    // Trigger debug update
+    window.updateAppearanceDebug?.();
+  });
+
+  // Quick set buttons
+  document.getElementById('btn-set-light').addEventListener('click', () => {
+    console.log('[Appearance Test] set("light") clicked');
+    appearance.set('light');
+  });
+
+  document.getElementById('btn-set-dark').addEventListener('click', () => {
+    console.log('[Appearance Test] set("dark") clicked');
+    appearance.set('dark');
+  });
+
+  document.getElementById('btn-set-system').addEventListener('click', () => {
+    console.log('[Appearance Test] set("system") clicked');
+    appearance.set('system');
+  });
+}
+
+/**
+ * Initialize event logging
+ */
+function initEventLog() {
+  const $log = document.getElementById('event-log');
+  const $clearBtn = document.getElementById('btn-clear-log');
+  let logLines = [];
+
+  function addLogEntry(message) {
+    const timestamp = new Date().toLocaleTimeString();
+    const entry = `[${timestamp}] ${message}`;
+    logLines.push(entry);
+
+    // Keep last 50 entries
+    if (logLines.length > 50) {
+      logLines = logLines.slice(-50);
+    }
+
+    $log.textContent = logLines.join('\n');
+    $log.scrollTop = $log.scrollHeight;
+  }
+
+  // Clear log button
+  $clearBtn.addEventListener('click', () => {
+    logLines = [];
+    $log.textContent = 'Log cleared...';
+  });
+
+  // Observe data-bs-theme changes
+  const observer = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+      if (mutation.attributeName === 'data-bs-theme') {
+        const oldValue = mutation.oldValue;
+        const newValue = document.documentElement.getAttribute('data-bs-theme');
+        addLogEntry(`Theme changed: "${oldValue}" -> "${newValue}"`);
+      }
+    });
+  });
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeOldValue: true,
+    attributeFilter: ['data-bs-theme'],
+  });
+
+  // Log system preference changes
+  const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+  mediaQuery.addEventListener('change', (event) => {
+    const systemPref = event.matches ? 'dark' : 'light';
+    addLogEntry(`System preference changed: "${systemPref}"`);
+  });
+
+  // Log click events on appearance controls
+  document.addEventListener('click', (event) => {
+    const $target = event.target.closest('[data-appearance-set]');
+    if ($target) {
+      const value = $target.getAttribute('data-appearance-set');
+      addLogEntry(`User clicked: set("${value}")`);
+    }
+  });
+
+  // Initial log entry
+  addLogEntry('Appearance test page loaded');
+  addLogEntry(`Initial theme: "${document.documentElement.getAttribute('data-bs-theme')}"`);
+  addLogEntry(`Saved preference: ${webManager.uj().appearance.get() || '(none)'}`);
+}

package/dist/assets/js/ultimate-jekyll-manager.js

@@ -4,6 +4,7 @@ import authModule from '__main_assets__/js/core/auth.js';
 import lazyLoadingModule from '__main_assets__/js/core/lazy-loading.js';
 import queryStringsModule from '__main_assets__/js/core/query-strings.js';
 import serviceWorkerModule from '__main_assets__/js/core/service-worker.js';
+import appearanceModule from '__main_assets__/js/core/appearance.js';
 import completeModule from '__main_assets__/js/core/complete.js';
 
 // Ultimate Jekyll Manager Module
@@ -32,6 +33,7 @@ export default async function (Manager, options) {
   lazyLoadingModule(Manager, options);
   queryStringsModule(Manager, options);
   serviceWorkerModule(Manager, options);
+  appearanceModule(Manager, options);
 
   // Conditionally loaded modules based on config (keep as dynamic imports)
   const conditionalModules = [

package/dist/defaults/dist/_includes/core/body.html

@@ -38,18 +38,54 @@
 <!-- Prerendered Icons -->
 {%- assign icons = page.resolved.prerender_icons | default: empty -%}
 {%- iftruthy icons -%}
-<!-- Pre-rendered Icon Templates -->
-<div id="prerendered-icons" class="d-none" aria-hidden="true">
-  {%- for icon in icons -%}
-    {%- assign icon_name = icon.name | default: icon -%}
-    {%- assign icon_class = icon.class | default: "fa-3xl" -%}
-    <div data-icon="{{ icon_name }}" data-class="{{ icon_class }}">
-      {% uj_icon icon_name, icon_class %}
-    </div>
-  {%- endfor -%}
-</div>
+  <!-- Pre-rendered Icon Templates -->
+  <div id="prerendered-icons" class="d-none" aria-hidden="true">
+    {%- for icon in icons -%}
+      {%- assign icon_name = icon.name | default: icon -%}
+      {%- assign icon_class = icon.class | default: "fa-3xl" -%}
+      <div data-icon="{{ icon_name }}" data-class="{{ icon_class }}">
+        {% uj_icon icon_name, icon_class %}
+      </div>
+    {%- endfor -%}
+  </div>
 {%- endiftruthy -%}
 
+<!-- Script - Set preferred appearance -->
+<!-- This runs immediately to prevent flash of wrong theme -->
+<!-- Priority: 1) User saved preference, 2) Site preset, 3) System preference (if preset is 'system') -->
+<script type="text/javascript">
+  (function() {
+    'use strict';
+    var $html = document.documentElement;
+
+    // Get the preset value from Jekyll (set at build time)
+    var preset = $html.getAttribute('data-bs-theme');
+
+    // Try to read user's saved preference from _manager storage
+    // (same format as webManager.storage() uses)
+    var saved = null;
+    try {
+      var managerData = localStorage.getItem('_manager');
+      var parsedData = managerData ? JSON.parse(managerData) : null;
+      saved = parsedData && parsedData.appearance && parsedData.appearance.preference;
+    } catch (e) {}
+
+    // Use saved preference if available, otherwise fall back to preset
+    var preference = saved || preset;
+    var theme = preference;
+
+    // If preference is 'system', resolve to actual light/dark based on OS setting
+    if (preference === 'system') {
+      theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+
+    // Only update if different from preset (avoid unnecessary DOM write)
+    if (theme && theme !== preset) {
+      $html.setAttribute('data-bs-theme', theme);
+    }
+  })();
+</script>
+
 <!-- Script to prevent clicks on disabled elements during page load -->
 <script type="text/javascript">
   (function() {

package/dist/defaults/dist/pages/test/libraries/appearance.html

@@ -0,0 +1,271 @@
+---
+### ALL PAGES ###
+layout: themes/[ site.theme.id ]/frontend/core/base
+permalink: /test/libraries/appearance
+
+### REGULAR PAGES ###
+sitemap:
+  include: false
+meta:
+  title: "Appearance Test Page"
+  description: "Testing the appearance switching system (dark, light, system modes)."
+  breadcrumb: "Appearance Test"
+  index: false
+
+---
+
+<div class="container py-5">
+  <h1 class="mb-4">Appearance Test Page</h1>
+  <p class="text-muted mb-5">Testing the appearance switching system with detailed debugging information.</p>
+
+  <div class="row g-4">
+
+    <!-- Theme Switcher -->
+    <div class="col-lg-6">
+      <div class="card">
+        <div class="card-header">
+          <h5 class="mb-0">Theme Switcher</h5>
+          <small class="text-muted">Click to change appearance mode</small>
+        </div>
+        <div class="card-body">
+          <!-- Dropdown Switcher -->
+          <div class="mb-4">
+            <label class="form-label">Dropdown Switcher</label>
+            <div class="dropdown">
+              <button class="btn btn-outline-adaptive dropdown-toggle w-100" type="button" data-bs-toggle="dropdown" aria-expanded="false">
+                <span data-appearance-icon="light" hidden>{% uj_icon "sun", "fa-md me-2" %}</span>
+                <span data-appearance-icon="dark" hidden>{% uj_icon "moon-stars", "fa-md me-2" %}</span>
+                <span data-appearance-icon="system" hidden>{% uj_icon "circle-half-stroke", "fa-md me-2" %}</span>
+                <span data-appearance-current></span>
+              </button>
+              <ul class="dropdown-menu w-100">
+                <li><a class="dropdown-item" href="#" data-appearance-set="light">{% uj_icon "sun", "fa-md me-2" %} Light</a></li>
+                <li><a class="dropdown-item" href="#" data-appearance-set="dark">{% uj_icon "moon-stars", "fa-md me-2" %} Dark</a></li>
+                <li><a class="dropdown-item" href="#" data-appearance-set="system">{% uj_icon "circle-half-stroke", "fa-md me-2" %} System</a></li>
+              </ul>
+            </div>
+          </div>
+
+          <!-- Button Group Switcher -->
+          <div class="mb-4">
+            <label class="form-label">Button Group Switcher</label>
+            <div class="btn-group w-100" role="group">
+              <button type="button" class="btn btn-outline-adaptive" data-appearance-set="light">
+                {% uj_icon "sun", "fa-md me-1" %} Light
+              </button>
+              <button type="button" class="btn btn-outline-adaptive" data-appearance-set="dark">
+                {% uj_icon "moon-stars", "fa-md me-1" %} Dark
+              </button>
+              <button type="button" class="btn btn-outline-adaptive" data-appearance-set="system">
+                {% uj_icon "circle-half-stroke", "fa-md me-1" %} System
+              </button>
+            </div>
+          </div>
+
+          <!-- Programmatic Controls -->
+          <div class="mb-4">
+            <label class="form-label">Programmatic Controls</label>
+            <div class="d-flex gap-2 flex-wrap">
+              <button type="button" class="btn btn-primary btn-sm" id="btn-toggle">
+                {% uj_icon "repeat", "fa-md me-1" %} Toggle (dark/light)
+              </button>
+              <button type="button" class="btn btn-secondary btn-sm" id="btn-cycle">
+                {% uj_icon "arrows-spin", "fa-md me-1" %} Cycle (all 3)
+              </button>
+              <button type="button" class="btn btn-warning btn-sm" id="btn-clear">
+                {% uj_icon "trash", "fa-md me-1" %} Clear Preference
+              </button>
+            </div>
+          </div>
+
+          <!-- Quick Set -->
+          <div>
+            <label class="form-label">Quick Set via API</label>
+            <div class="d-flex gap-2 flex-wrap">
+              <button type="button" class="btn btn-outline-warning btn-sm" id="btn-set-light">set('light')</button>
+              <button type="button" class="btn btn-outline-info btn-sm" id="btn-set-dark">set('dark')</button>
+              <button type="button" class="btn btn-outline-success btn-sm" id="btn-set-system">set('system')</button>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Debug Panel -->
+    <div class="col-lg-6">
+      <div class="card">
+        <div class="card-header d-flex justify-content-between align-items-center">
+          <div>
+            <h5 class="mb-0">Debug Panel</h5>
+            <small class="text-muted">Live values (updates automatically)</small>
+          </div>
+          <button type="button" class="btn btn-outline-secondary btn-sm" id="btn-refresh">
+            {% uj_icon "arrows-rotate", "fa-md" %}
+          </button>
+        </div>
+        <div class="card-body">
+          <table class="table table-sm mb-0">
+            <tbody>
+              <tr>
+                <th scope="row" class="text-muted" style="width: 50%;">Saved Preference</th>
+                <td><code id="debug-saved">-</code></td>
+              </tr>
+              <tr>
+                <th scope="row" class="text-muted">Resolved Theme</th>
+                <td><code id="debug-resolved">-</code></td>
+              </tr>
+              <tr>
+                <th scope="row" class="text-muted">data-bs-theme attr</th>
+                <td><code id="debug-attr">-</code></td>
+              </tr>
+              <tr>
+                <th scope="row" class="text-muted">localStorage raw</th>
+                <td><code id="debug-localstorage">-</code></td>
+              </tr>
+              <tr>
+                <th scope="row" class="text-muted">System Preference</th>
+                <td><code id="debug-system">-</code></td>
+              </tr>
+              <tr>
+                <th scope="row" class="text-muted">Site Preset (Jekyll)</th>
+                <td><code id="debug-preset">{{ page.resolved.theme.appearance }}</code></td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <!-- Event Log -->
+      <div class="card mt-4">
+        <div class="card-header d-flex justify-content-between align-items-center">
+          <div>
+            <h5 class="mb-0">Event Log</h5>
+            <small class="text-muted">Theme change events</small>
+          </div>
+          <button type="button" class="btn btn-outline-secondary btn-sm" id="btn-clear-log">
+            {% uj_icon "trash", "fa-md" %}
+          </button>
+        </div>
+        <div class="card-body p-0">
+          <pre id="event-log" class="mb-0 p-3 small" style="max-height: 200px; overflow: auto; background: var(--bs-tertiary-bg);">Waiting for events...</pre>
+        </div>
+      </div>
+    </div>
+
+    <!-- Visual Test -->
+    <div class="col-12">
+      <div class="card">
+        <div class="card-header">
+          <h5 class="mb-0">Visual Theme Test</h5>
+          <small class="text-muted">These elements should adapt to the current theme</small>
+        </div>
+        <div class="card-body">
+          <div class="row g-3">
+            <!-- Background colors -->
+            <div class="col-md-4">
+              <h6>Backgrounds</h6>
+              <div class="p-2 mb-2 bg-body border rounded">bg-body</div>
+              <div class="p-2 mb-2 bg-body-secondary border rounded">bg-body-secondary</div>
+              <div class="p-2 mb-2 bg-body-tertiary border rounded">bg-body-tertiary</div>
+            </div>
+
+            <!-- Text colors -->
+            <div class="col-md-4">
+              <h6>Text</h6>
+              <p class="text-body mb-2">text-body (primary text)</p>
+              <p class="text-body-secondary mb-2">text-body-secondary</p>
+              <p class="text-body-tertiary mb-2">text-body-tertiary</p>
+              <p class="text-muted mb-2">text-muted</p>
+            </div>
+
+            <!-- Buttons -->
+            <div class="col-md-4">
+              <h6>Adaptive Buttons</h6>
+              <div class="d-flex gap-2 flex-wrap">
+                <button class="btn btn-adaptive">btn-adaptive</button>
+                <button class="btn btn-outline-adaptive">btn-outline-adaptive</button>
+              </div>
+            </div>
+
+            <!-- Alerts -->
+            <div class="col-md-6">
+              <h6>Alerts</h6>
+              <div class="alert alert-primary py-2 mb-2">Primary alert</div>
+              <div class="alert alert-secondary py-2 mb-2">Secondary alert</div>
+              <div class="alert alert-success py-2 mb-0">Success alert</div>
+            </div>
+
+            <!-- Form -->
+            <div class="col-md-6">
+              <h6>Form Elements</h6>
+              <input type="text" class="form-control mb-2" placeholder="Text input">
+              <select class="form-select mb-2">
+                <option>Select option</option>
+              </select>
+              <div class="form-check">
+                <input class="form-check-input" type="checkbox" id="test-check" checked>
+                <label class="form-check-label" for="test-check">Checkbox</label>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- API Reference -->
+    <div class="col-12">
+      <div class="card">
+        <div class="card-header">
+          <h5 class="mb-0">API Reference</h5>
+          <small class="text-muted">webManager.uj().appearance methods</small>
+        </div>
+        <div class="card-body">
+          <div class="table-responsive">
+            <table class="table table-sm mb-0">
+              <thead>
+                <tr>
+                  <th>Method</th>
+                  <th>Returns</th>
+                  <th>Description</th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td><code>.get()</code></td>
+                  <td><code>'dark' | 'light' | 'system' | null</code></td>
+                  <td>Get saved preference (null if not set)</td>
+                </tr>
+                <tr>
+                  <td><code>.getResolved()</code></td>
+                  <td><code>'dark' | 'light'</code></td>
+                  <td>Get actual displayed theme</td>
+                </tr>
+                <tr>
+                  <td><code>.set(value)</code></td>
+                  <td><code>void</code></td>
+                  <td>Save and apply preference ('dark', 'light', or 'system')</td>
+                </tr>
+                <tr>
+                  <td><code>.toggle()</code></td>
+                  <td><code>void</code></td>
+                  <td>Toggle between dark and light</td>
+                </tr>
+                <tr>
+                  <td><code>.cycle()</code></td>
+                  <td><code>void</code></td>
+                  <td>Cycle: dark -> light -> system -> dark</td>
+                </tr>
+                <tr>
+                  <td><code>.clear()</code></td>
+                  <td><code>void</code></td>
+                  <td>Clear saved preference (revert to site default)</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+        </div>
+      </div>
+    </div>
+
+  </div>
+</div>

package/package.json

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