jekyll-theme-zer0 1.28.0 → 1.29.0

data/_sass/tokens/_typography.scss

@@ -28,6 +28,10 @@
   --zer0-text-h5: 1.125rem;
   --zer0-text-h6: 1rem;
 
+  // Display sizes (Bootstrap .display-* — hero titles) ---------------------
+  --zer0-text-display-4: clamp(2.5rem, 6vw, 3.5rem);
+  --zer0-text-display-5: clamp(2rem, 5vw, 3rem);
+
   // Line heights -----------------------------------------------------------
   --zer0-leading-tight: 1.2;
   --zer0-leading-normal: 1.55;

data/_sass/utilities/_focus.scss

@@ -19,6 +19,20 @@ summary:focus-visible {
   border-radius: 0.125rem;
 }
 
+// Skip-link target — <main id="main-content" tabindex="-1"> in _layouts/root.html.
+// The -1 lets the skip link move real keyboard focus into the content (see the
+// comment there), but it also makes the container paintable by the UA's default
+// focus outline. Suppress it on the container ONLY: this rule cannot match a
+// descendant, so links, buttons and headings inside the content keep their rings
+// — including the :focus-visible ring defined at the top of this file.
+//
+// Safe here specifically because the element is tabindex="-1": it is never
+// reachable by Tab, so no keyboard user can land on it and be left without an
+// indicator. Do not generalise this selector to focusable elements.
+#main-content:focus {
+  outline: none;
+}
+
 // Skip-to-content link — visually hidden until focused
 .zer0-skip-link {
   position: absolute;

data/assets/css/main.scss

@@ -40,7 +40,10 @@
 @import "components/content-tables";
 @import "components/search-modal";
 @import "components/page-feedback";
+@import "components/page-views";
 @import "components/book";
+@import "components/recipe";
+@import "components/setup-wizard";
 
 // 6. Layout partials
 @import "layouts/landing";

data/assets/js/modules/navigation/navbar.js

@@ -55,6 +55,7 @@ export class Navbar {
         this._setupMobileDropdowns();
         this._setupOutsideClickClose();
         this._setupOffcanvasReset();
+        this._setupSettingsExclusivity();
         this._setupNavTooltips();
         this._setupDropdownHoverDelay();
         this._setupFocusTrap();
@@ -224,6 +225,60 @@ export class Navbar {
         });
     }
 
+    /**
+     * Mobile: opening Settings from inside a nav panel must not leave the two
+     * stacked on top of each other.
+     *
+     * #bdNavbar (and the optional unified drawer) and #info-section are both
+     * `offcanvas-end` at Bootstrap's $zindex-offcanvas. #bdNavbar additionally
+     * lives inside the fixed header, which _navbar.scss lifts above the
+     * offcanvas backdrop while the menu is open — so a tap on the menu's own
+     * "Settings" item used to open Settings *behind* the still-open menu, with
+     * nothing on screen to show it had worked.
+     *
+     * Intercept the Bootstrap `show` event (capture phase, before Bootstrap's
+     * own handler runs) and defer it until the host panel has finished sliding
+     * out. Doing it on the event rather than on the trigger keeps the plain
+     * data-api working for every other entry point — footer, keyboard, a
+     * consumer's own button — and leaves the markup functional if this module
+     * never loads.
+     */
+    _setupSettingsExclusivity() {
+        const settingsEl = document.getElementById('info-section');
+        if (!settingsEl) return;
+
+        const hostEls = ['bdNavbar', 'zer0UnifiedDrawer']
+            .map((id) => document.getElementById(id))
+            .filter(Boolean);
+        if (!hostEls.length) return;
+
+        this._on(
+            settingsEl,
+            'show.bs.offcanvas',
+            (event) => {
+                const Offcanvas = window.bootstrap?.Offcanvas;
+                if (!Offcanvas) return;
+                const openHost = hostEls.find((el) => el.classList.contains('show'));
+                if (!openHost) return;
+
+                event.preventDefault();
+                event.stopImmediatePropagation();
+
+                const hostInstance = Offcanvas.getInstance(openHost);
+                const show = () => Offcanvas.getOrCreateInstance(settingsEl).show();
+                if (!hostInstance) {
+                    show();
+                    return;
+                }
+                // `hidden.bs.offcanvas` fires after the slide-out transition, so
+                // the header's z-index lift has already been released by then.
+                openHost.addEventListener('hidden.bs.offcanvas', show, { once: true });
+                hostInstance.hide();
+            },
+            true,
+        );
+    }
+
     _setupNavTooltips() {
         if (typeof window.bootstrap === 'undefined' || !window.bootstrap.Tooltip) return;
         const navLinks = document.querySelectorAll('#bdNavbar .nav-link[title]');

data/assets/js/page-views.js

@@ -0,0 +1,372 @@
+// Feature: ZER0-083
+/*
+ * ===================================================================
+ * page-views.js — page-view counter (tracking + display)
+ * ===================================================================
+ *
+ * File:    assets/js/page-views.js
+ * Purpose: Record a view for the current page and render the count into
+ *          every `[data-page-views]` badge on the page.
+ *
+ * Reads one JSON block injected by _includes/components/page-views-init.html:
+ *   #pageViewsConfig — provider, endpoint, privacy gates, labels
+ *
+ * Providers
+ *   local   (default) counts live in this visitor's localStorage. Zero
+ *           config, zero network, GitHub-Pages safe — the count is "how
+ *           often YOU opened this page", so it is honest without a server.
+ *   remote  counts come from an HTTP counter endpoint (the chat-proxy
+ *           worker, a self-hosted function, CounterAPI, …). The endpoint
+ *           owns the truth; this script only asks for it.
+ *
+ * Privacy
+ *   Do Not Track, Global Privacy Control, and (optionally) the theme's
+ *   cookie-consent "analytics" category all suppress RECORDING. Display of
+ *   an already-known count is never suppressed — nothing is collected to
+ *   show it. When consent is required and later granted, the pending view
+ *   is recorded on the `cookieConsentChanged` event.
+ *
+ * Public API (also what the Playwright spec drives):
+ *   window.zer0PageViews.get(path)   -> number | null
+ *   window.zer0PageViews.all()       -> { path: count }
+ *   window.zer0PageViews.refresh()   -> re-render every badge
+ *   window.zer0PageViews.reset()     -> clear the local store
+ * Event: `zer0:page-views` on document, detail { path, count, provider }.
+ * ===================================================================
+ */
+(function () {
+  "use strict";
+
+  var STORE_KEY = "zer0-page-views";
+  var SESSION_KEY = "zer0-page-views-session";
+  var STORE_VERSION = 1;
+
+  function readJSON(id, fallback) {
+    var el = document.getElementById(id);
+    if (!el) return fallback;
+    try {
+      return JSON.parse(el.textContent);
+    } catch (err) {
+      return fallback;
+    }
+  }
+
+  var CONFIG = readJSON("pageViewsConfig", null);
+  if (!CONFIG || !CONFIG.enabled) return;
+
+  // --- storage helpers --------------------------------------------------
+  // Private-mode Safari and "block all cookies" throw on access, not on use,
+  // so every touch is wrapped: the widget degrades to "no count" rather than
+  // taking the page down with it.
+  function safeStorage(kind) {
+    try {
+      var s = window[kind];
+      var probe = "__zer0_probe__";
+      s.setItem(probe, "1");
+      s.removeItem(probe);
+      return s;
+    } catch (err) {
+      return null;
+    }
+  }
+
+  var local = safeStorage("localStorage");
+  var session = safeStorage("sessionStorage");
+
+  function readStore() {
+    if (!local) return { v: STORE_VERSION, paths: {} };
+    try {
+      var raw = JSON.parse(local.getItem(STORE_KEY));
+      if (raw && raw.paths && typeof raw.paths === "object") return raw;
+    } catch (err) {
+      /* corrupt payload — start clean rather than throwing */
+    }
+    return { v: STORE_VERSION, paths: {} };
+  }
+
+  function writeStore(store) {
+    if (!local) return;
+    try {
+      local.setItem(STORE_KEY, JSON.stringify(store));
+    } catch (err) {
+      /* quota exceeded — the count is a nicety, never a hard failure */
+    }
+  }
+
+  // Keep the store bounded: evict the least-recently-viewed paths first.
+  function prune(store) {
+    var max = CONFIG.maxEntries > 0 ? CONFIG.maxEntries : 500;
+    var keys = Object.keys(store.paths);
+    if (keys.length <= max) return store;
+    keys
+      .sort(function (a, b) {
+        return (store.paths[a].t || 0) - (store.paths[b].t || 0);
+      })
+      .slice(0, keys.length - max)
+      .forEach(function (key) {
+        delete store.paths[key];
+      });
+    return store;
+  }
+
+  // --- paths ------------------------------------------------------------
+  // Badges carry site-relative, baseurl-free paths (page.url), so the
+  // runtime location has to be normalized the same way or a project-pages
+  // site would count "/repo/foo/" separately from "/foo/".
+  function normalizePath(input) {
+    var path = input;
+    try {
+      path = new URL(input, window.location.href).pathname;
+    } catch (err) {
+      /* already a bare path */
+    }
+    var base = CONFIG.baseurl || "";
+    if (base && path.indexOf(base) === 0) path = path.slice(base.length);
+    path = path.replace(/index\.html?$/, "");
+    if (path.charAt(0) !== "/") path = "/" + path;
+    if (path.charAt(path.length - 1) !== "/" && !/\.[a-z0-9]+$/i.test(path)) path += "/";
+    return path;
+  }
+
+  var CURRENT = normalizePath(window.location.pathname);
+
+  // --- privacy gates ----------------------------------------------------
+  function dntEnabled() {
+    if (!CONFIG.respectDnt) return false;
+    var dnt = navigator.doNotTrack || window.doNotTrack || navigator.msDoNotTrack;
+    return dnt === "1" || dnt === "yes";
+  }
+
+  function gpcEnabled() {
+    return !!CONFIG.respectGpc && navigator.globalPrivacyControl === true;
+  }
+
+  function analyticsConsented() {
+    if (window.cookieConsent && typeof window.cookieConsent.analytics === "boolean") {
+      return window.cookieConsent.analytics;
+    }
+    if (!local) return false;
+    try {
+      var stored = JSON.parse(local.getItem("zer0-cookie-consent"));
+      return !!(stored && stored.analytics);
+    } catch (err) {
+      return false;
+    }
+  }
+
+  function mayRecord() {
+    if (!CONFIG.track) return false;
+    if (dntEnabled() || gpcEnabled()) return false;
+    if (CONFIG.requireConsent && !analyticsConsented()) return false;
+    return true;
+  }
+
+  // One view per path per browser session, so a reload or a back-navigation
+  // does not inflate the number. `dedupe: "never"` counts every load.
+  function alreadyCountedThisSession(path) {
+    if (CONFIG.dedupe !== "session" || !session) return false;
+    try {
+      var seen = JSON.parse(session.getItem(SESSION_KEY)) || [];
+      return seen.indexOf(path) !== -1;
+    } catch (err) {
+      return false;
+    }
+  }
+
+  function markCountedThisSession(path) {
+    if (CONFIG.dedupe !== "session" || !session) return;
+    try {
+      var seen = JSON.parse(session.getItem(SESSION_KEY)) || [];
+      if (seen.indexOf(path) === -1) seen.push(path);
+      session.setItem(SESSION_KEY, JSON.stringify(seen));
+    } catch (err) {
+      /* non-fatal */
+    }
+  }
+
+  // --- counts -----------------------------------------------------------
+  var counts = {};
+
+  function seedFromLocalStore() {
+    var store = readStore();
+    Object.keys(store.paths).forEach(function (path) {
+      var entry = store.paths[path];
+      if (entry && typeof entry.c === "number") counts[path] = entry.c;
+    });
+  }
+
+  function recordLocal(path) {
+    var store = readStore();
+    var entry = store.paths[path] || { c: 0, t: 0 };
+    entry.c += 1;
+    entry.t = Date.now();
+    store.paths[path] = entry;
+    writeStore(prune(store));
+    return entry.c;
+  }
+
+  // Pull a count out of an arbitrary JSON body, e.g. countKey "data.views".
+  function pluck(payload, key) {
+    var value = payload;
+    var parts = String(key || "views").split(".");
+    for (var i = 0; i < parts.length; i++) {
+      if (value === null || typeof value !== "object") return null;
+      value = value[parts[i]];
+    }
+    return typeof value === "number" && isFinite(value) ? value : null;
+  }
+
+  function remoteUrl(path) {
+    var endpoint = CONFIG.endpoint || "";
+    if (endpoint.indexOf("{path}") !== -1) {
+      return endpoint.replace("{path}", encodeURIComponent(path));
+    }
+    return endpoint + (endpoint.indexOf("?") === -1 ? "?" : "&") + "path=" + encodeURIComponent(path);
+  }
+
+  function recordRemote(path, record) {
+    var method = record ? CONFIG.method || "POST" : "GET";
+    var init = { method: method, credentials: "omit", mode: "cors" };
+    if (method !== "GET" && method !== "HEAD") {
+      init.headers = { "Content-Type": "application/json" };
+      init.body = JSON.stringify({ path: path });
+    }
+    return fetch(remoteUrl(path), init)
+      .then(function (res) {
+        if (!res.ok) throw new Error("page-views: endpoint returned " + res.status);
+        return res.json();
+      })
+      .then(function (payload) {
+        var count = pluck(payload, CONFIG.countKey);
+        if (count === null) throw new Error("page-views: no count at '" + CONFIG.countKey + "'");
+        return count;
+      });
+  }
+
+  // --- rendering --------------------------------------------------------
+  var formatter = null;
+  try {
+    formatter = new Intl.NumberFormat();
+  } catch (err) {
+    formatter = null;
+  }
+
+  function format(count) {
+    return formatter ? formatter.format(count) : String(count);
+  }
+
+  function render() {
+    var badges = document.querySelectorAll("[data-page-views]");
+    Array.prototype.forEach.call(badges, function (badge) {
+      var path = normalizePath(badge.getAttribute("data-page-views") || CURRENT);
+      var count = counts[path];
+      if (typeof count !== "number") return; // unknown → stays hidden, no "0 views" flash
+      var countEl = badge.querySelector("[data-page-views-count]");
+      var labelEl = badge.querySelector("[data-page-views-label]");
+      if (countEl) countEl.textContent = format(count);
+      if (labelEl) labelEl.textContent = count === 1 ? CONFIG.labelOne : CONFIG.labelOther;
+      badge.removeAttribute("hidden");
+    });
+  }
+
+  function publish(path, count) {
+    counts[path] = count;
+    render();
+    document.dispatchEvent(
+      new CustomEvent("zer0:page-views", {
+        detail: { path: path, count: count, provider: CONFIG.provider }
+      })
+    );
+  }
+
+  // --- orchestration ----------------------------------------------------
+  var recorded = false;
+
+  function recordCurrentView() {
+    if (recorded || !mayRecord()) return;
+    if (alreadyCountedThisSession(CURRENT)) return;
+    recorded = true;
+    markCountedThisSession(CURRENT);
+
+    if (CONFIG.provider === "remote") {
+      recordRemote(CURRENT, true)
+        .then(function (count) {
+          publish(CURRENT, count);
+        })
+        .catch(function (err) {
+          if (CONFIG.fallbackLocal) publish(CURRENT, recordLocal(CURRENT));
+          if (window.console && console.debug) console.debug(String(err));
+        });
+      return;
+    }
+    publish(CURRENT, recordLocal(CURRENT));
+  }
+
+  function readOnlyRemote() {
+    // Recording is blocked (DNT/GPC/consent) but a remote count is public
+    // information — show it without contributing to it.
+    recordRemote(CURRENT, false)
+      .then(function (count) {
+        publish(CURRENT, count);
+      })
+      .catch(function () {
+        /* endpoint unavailable — badges stay hidden */
+      });
+  }
+
+  function start() {
+    if (CONFIG.provider !== "remote") seedFromLocalStore();
+    render();
+
+    if (mayRecord()) {
+      recordCurrentView();
+    } else if (CONFIG.provider === "remote") {
+      readOnlyRemote();
+    }
+
+    // Consent can arrive after load — record the pending view when it does.
+    if (CONFIG.requireConsent) {
+      document.addEventListener("cookieConsentChanged", function () {
+        recordCurrentView();
+      });
+    }
+  }
+
+  window.zer0PageViews = {
+    get: function (path) {
+      var count = counts[normalizePath(path || CURRENT)];
+      return typeof count === "number" ? count : null;
+    },
+    all: function () {
+      var copy = {};
+      Object.keys(counts).forEach(function (path) {
+        copy[path] = counts[path];
+      });
+      return copy;
+    },
+    refresh: render,
+    reset: function () {
+      counts = {};
+      if (local) {
+        try {
+          local.removeItem(STORE_KEY);
+        } catch (err) {
+          /* non-fatal */
+        }
+      }
+      if (session) {
+        try {
+          session.removeItem(SESSION_KEY);
+        } catch (err) {
+          /* non-fatal */
+        }
+      }
+    }
+  };
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", start);
+  } else {
+    start();
+  }
+})();