fenton-jekyll-boilerplate 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e62bb1bc58c9c86331a322e70bb7d8b16ce251dcc572d89361617e9f994bf53
-  data.tar.gz: 1d25e7531752be6c2690eb81843a24b1dce2a343381df86546e9bf6a0465cd40
+  metadata.gz: f0d1a8a76ec9b945ff3ab8e850ea6874390b5abbb02d68d11a750427142810de
+  data.tar.gz: a72394148f74d7fa8bf7a4cc751e44978945095982ce351b1f3285bddc96dec2
 SHA512:
-  metadata.gz: 37d7589c85c4853b70fff3699c32400a1ce2d7a1374804270bac303be382bedb22c7403ffaad665b631206812b7142fdd1d15479db92c4d185204981fafaeae5
-  data.tar.gz: 14a32ca59b666e353ec58d6274d02eda8eace7f4910564009eadf3a663aac6885bbb8adff82f4df3b1c6e2bcda39419fabf9146503c4d456de036a0bcb8a927d
+  metadata.gz: f6b74abfacb10010e0445fbe914d29e8757de93b42c746df7f9e34bf4e77a5f9bbf78215cf8b7aad5b2be336fa365a3d47fc2772afa2adb55e5efc0bdf9aaf72
+  data.tar.gz: 528baee39ddef889baf502beeef69fd884b4df3a1bd8d12c0088ca75b35712c8de1429bbe9318a351272582dfa6c3f39a19c5c612f540de3d9fdf41e517c23c3

data/assets/js/main.js

@@ -0,0 +1,18 @@
+// @ts-check
+
+import { setNavigationTree, setNavigationItem } from './modules/nav-expand.js';
+import { setClickableBlocks } from './modules/click-blocks.js';
+import { addResizedEvent } from './modules/resizing.js';
+import { addStickyNavigation } from './modules/nav-sticky.js';
+import { addMobileNavigation } from './modules/nav-mobile.js';
+import { addIntersectionObserver } from './modules/animation.js';
+
+setNavigationTree('details.sub-nav');
+setNavigationItem('.site-nav a', 'current-item')
+setClickableBlocks('data-destination');
+
+var resizedEventName = addResizedEvent();
+
+addStickyNavigation('.site-header', '.site-nav', '.site-nav > ul', resizedEventName);
+addMobileNavigation('.navigation-icon', '.site-nav', resizedEventName);
+addIntersectionObserver('.post-list .list-item, main img, main .note, main blockquote');

data/assets/js/modules/animation.js

@@ -0,0 +1,41 @@
+// @ts-check
+
+import { qsa } from './query.js';
+
+/**
+ * Assists animation by setting "--shown" CSS property
+ * 
+ * When an item is visible in the viewport, it will have --shown: 1
+ * Otherwise it will be --shown: 0
+ * This allows CSS transitions and calculated properties to animate elements
+ * 
+ * Example
+ *     transition: all 0.2s ease-in;
+ *     scale: calc(0.75 + (var(--shown, 1) * 0.25));
+ * 
+ * @param {string} listItemQuery 
+ */
+function addIntersectionObserver(listItemQuery) {
+    function handleIntersection(entries, observer) {
+        for (var entry of entries) {
+            var value = entry.isIntersecting ? 1 : 0;
+            entry.target.style.setProperty('--shown', value);
+        }
+    }
+
+    var options = {
+        root: null,
+        rootMargin: '0px',
+        threshold: 0
+    };
+
+    var observer = new IntersectionObserver(handleIntersection, options)
+
+    var items = qsa(listItemQuery);
+
+    for (var i = 0; i < items.length; i++) {
+        observer.observe(items[i]);
+    }
+}
+
+export { addIntersectionObserver };

data/assets/js/modules/click-blocks.js

@@ -0,0 +1,35 @@
+// @ts-check
+
+import { qsa } from './query.js';
+
+/**
+ * Makes an entire block clickable based on a data-attribute, usually "data-destination"
+ * 
+ * Example: You have a list of blog posts, including featured images. If you make the title
+ * clickable, clicks on the image won't open the blog. Adding links to the images means
+ * keyboard users have to tab twice as much to get through the list.
+ * 
+ * Use clickable blocks to allow keyboard users to tab through the real links, but still
+ * capture clicks elsewhere on the block.
+ * 
+ * @param {string} dataAttributeName
+ */
+ function setClickableBlocks(dataAttributeName) {
+    var listItems = qsa('[' + dataAttributeName + ']');
+
+    for(var i = 0; i < listItems.length; i++) {
+        var listItem = listItems[i];
+        listItem.style.cursor = 'pointer';
+        listItem.addEventListener('click', function (e) {
+            var location = this.getAttribute(dataAttributeName);
+
+            if (location) {
+                e.preventDefault();
+                document.location = location;
+                return false;
+            }
+        });
+    }
+}
+
+export { setClickableBlocks };

data/assets/js/modules/events.js

@@ -0,0 +1,19 @@
+// @ts-check
+
+/**
+ * 
+ * @param {string} name 
+ * @param {{[key: string]: any}} detail 
+ * @param {Document | HTMLElement} [target]
+ */
+function raiseEvent(name, detail, target) {
+    if (!target) {
+        target = document;
+    }
+
+    const event = new CustomEvent(name, { detail: detail});
+    document.dispatchEvent(event);
+    console.log('Event Raised', name, detail);
+}
+
+export { raiseEvent };

data/assets/js/modules/focus.js

@@ -0,0 +1,76 @@
+// @ts-check
+
+import { qsa } from './query.js';
+
+/**
+ * Gets first, last, and all focusable elements in the target
+ * 
+ * For the supplied element, finds all the elements that can receive keyboard focus.
+ * 
+ * Examples: a, button, input, textarea, select, and other valid interactive items
+ * that haven't been disabled or hidden.
+ * 
+ * @param {HTMLElement} target element
+ * @returns {{first: HTMLElement, last: HTMLElement, all: HTMLElement[]}}
+ */
+ function getFocusableElement(target) {
+    var focusElements = Array.from(
+        qsa('a[href], button, input, textarea, select, details,[tabindex]:not([tabindex="-1"])', target)
+    ).filter(function(el) {
+        return !el.hasAttribute('disabled') && !el.getAttribute('aria-hidden');
+    });
+    
+    return {
+        first: focusElements[0],
+        last: focusElements[focusElements.length -1],
+        all: focusElements
+    };
+}
+
+/**
+ * Mechanism to trap focus
+ * 
+ * @param {KeyboardEvent} event 
+ * @param {HTMLElement} focusItem 
+ * @returns 
+ */
+function trapFocus(event, focusItem) {
+    switch (event.code.toLowerCase()) {
+        case 'tab':
+        event.preventDefault();    
+        focusItem.focus();
+        return false;
+    }
+}
+
+/**
+ * Mechanism to trap focus (TAB)
+ * 
+ * @param {KeyboardEvent} event 
+ * @param {HTMLElement} focusItem 
+ * @returns 
+ */
+function trapFocusForward(event, focusItem) {
+    if (event.shiftKey) {
+        return;
+    }
+
+    trapFocus(event, focusItem);
+}
+
+/**
+ * Mechanism to trap tab (SHIFT + TAB)
+ * 
+ * @param {KeyboardEvent} event 
+ * @param {HTMLElement} focusItem 
+ * @returns 
+ */
+function trapReverseFocus(event, focusItem) {
+    if (!event.shiftKey) {
+        return;
+    }
+
+    trapFocus(event, focusItem);
+}
+
+export { getFocusableElement, trapFocusForward, trapReverseFocus };

data/assets/js/modules/nav-expand.js

@@ -0,0 +1,51 @@
+// @ts-check
+
+import { qs, qsa } from './query.js';
+
+/**
+ * Sets the navigation based on the current page
+ * 
+ * Example: You have a navigation tree with an "About" page with several child items.
+ * When the user is on the "About" page, or any child pages, the navigation should
+ * be automatically expanded so the user can orient themselves within the site.
+ * 
+ * @param {string} className 
+ */
+ function setNavigationTree(className) {
+    var summaries = qsa(className);
+    var site = document.location.origin;
+    var location = document.location.pathname;
+
+    for (var i = 0; i < summaries.length; i++) {
+        var summary = summaries[i];
+        var anchorElement = /** @type {HTMLAnchorElement} */(qs('a', summary));
+        var address = anchorElement.href.replace(site, '');
+
+        if (location.startsWith(address)){
+            summary.setAttribute('open', 'open');
+        }
+    }
+}
+
+/**
+ * Highlights the current navigation item
+ * 
+ * @param {string} navQuery 
+ * @param {string} selectedClass 
+ */
+function setNavigationItem(navQuery, selectedClass) {
+    var anchors = qsa(navQuery);
+    var site = document.location.origin;
+    var location = document.location.pathname;
+
+    for (var j = 0; j < anchors.length; j++) {
+        var anchor = /** @type {HTMLAnchorElement} */ (anchors[j]);
+        var href = anchor.href.replace(site, '');
+
+        if (href === location) {
+            anchor.classList.add(selectedClass);
+        }
+    }
+}
+
+export { setNavigationTree, setNavigationItem };

data/assets/js/modules/nav-mobile.js

@@ -0,0 +1,104 @@
+// @ts-check
+
+import { qs } from './query.js';
+import { getFocusableElement, trapFocusForward, trapReverseFocus } from './focus.js';
+
+/**
+ * Provides an overlay with the navigation for mobile users.
+ * 
+ * Example: You have site navigation on the page, but demote it (closer to the footer) on mobile to avoid
+ * the content being pushed below the fold. You provide an icon that bookmarks to the
+ * navigation.
+ * 
+ * The mobile navigation intercepts the bookmark link and opens the navigation in a modal
+ * overlay, trapping keyboard focus until the overlay is closed.
+ * 
+ * @param {string} iconSelector 
+ * @param {string} navigationSelector 
+ */
+ function addMobileNavigation(iconSelector, navigationSelector, resizedEventName) {
+    var icon = qs(iconSelector);
+    var originalIcon = icon.innerHTML;
+    var overlay = document.createElement('div');
+    var dataOpen = 'data-open';
+
+    icon.addEventListener('keydown', function(e) { 
+        if (icon.getAttribute(dataOpen) === dataOpen) {
+            var focusElements = getFocusableElement(overlay);
+            trapFocusForward(e, focusElements.first); 
+            trapReverseFocus(e, focusElements.last);
+        }
+    });
+
+    function handleIconInteraction() {
+        if (icon.dataset.open == dataOpen) {
+            closeMobileMenu();
+        } else {
+            openMobileMenu();
+        }
+    }
+
+    function openMobileMenu(){
+        document.body.style.overflow = 'hidden';
+        var navigation = qs(navigationSelector);
+        
+        overlay.innerHTML = navigation.outerHTML;
+        overlay.className = 'overlay';
+        overlay.style.display = 'block';
+
+        // Modal Accessibility
+        var title = qs('.site-nav-title', overlay);
+        title.setAttribute('id', 'modal-title');
+        title.setAttribute('tabindex', '-1');
+        overlay.setAttribute('role', 'dialog');
+        overlay.setAttribute('aria-modal', 'true');
+        overlay.setAttribute('aria-labelled-by', 'modal-title');
+
+        // Trap Focus to Visible Overlay
+        var focusElements = getFocusableElement(overlay);
+
+        focusElements.first.addEventListener('keydown', function(e) {
+            trapReverseFocus(e, icon);
+        })
+        focusElements.last.addEventListener('keydown', function(e) { 
+            trapFocusForward(e, icon); 
+        });
+
+        icon.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" 
+            width="40" height="40" viewBox="0 0 24 24" stroke-width="1.5" 
+            fill="none" stroke-linecap="round" stroke-linejoin="round">
+            <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
+            <line x1="18" y1="6" x2="6" y2="18" />
+            <line x1="6" y1="6" x2="18" y2="18" />
+            </svg>`;
+
+        document.body.appendChild(overlay);
+        icon.setAttribute(dataOpen, dataOpen);
+        title.focus();
+    }
+
+    function closeMobileMenu() {
+        document.body.style.overflow = 'auto';
+
+        if (icon.getAttribute(dataOpen) === dataOpen) {
+            overlay.innerHTML = '';
+            overlay.style.display = 'none';
+            document.body.removeChild(overlay);
+        }
+
+        icon.innerHTML = originalIcon;
+        icon.removeAttribute(dataOpen);
+    }
+
+    icon.addEventListener('click', function (e) {
+        e.preventDefault();
+        handleIconInteraction();
+        return false;
+    });
+
+    document.addEventListener(resizedEventName, function () {
+        closeMobileMenu();
+    })
+}
+
+export { addMobileNavigation };

data/assets/js/modules/nav-sticky.js

@@ -0,0 +1,54 @@
+// @ts-check
+
+import { qs, qsa } from './query.js';
+
+/**
+ * Makes an existing navigation element sticky
+ * 
+ * Example: If the existing navigation is not as tall as the content, the
+ * navigation will stick to the top, allowing the user to see it as 
+ * they scroll through the article
+ * 
+ * @param {string} headerSelector 
+ * @param {string} navigationSelector 
+ * @param {string} navigationListSelector 
+ */
+function addStickyNavigation(headerSelector, navigationSelector, navigationListSelector, resizedEventName) {
+    function setNavigationMode() {
+        var header = qs(headerSelector);
+        var navigation = qs(navigationSelector);
+        var navigationList = qs(navigationListSelector); 
+        
+        var buffer = 50;
+        var className = 'sticky';
+
+        var dimensions = {
+            browserHeight: window.innerHeight,
+            browserWidth: window.innerWidth,
+            headerHeight: header.clientHeight,
+            navigationHeight: navigationList.clientHeight
+        };
+
+        // Only enable sticky mode if the menu will fit vertically
+        // && where the browser is more than 860px wide
+        if (dimensions.navigationHeight < ((dimensions.browserHeight - dimensions.headerHeight) - buffer)
+            && dimensions.browserWidth > 860) {
+            console.log('Navigation: Sticky Mode');
+            navigation.classList.add(className)
+            navigation.style.top = dimensions.headerHeight.toString() + 'px';
+        } else {
+            console.log('Navigation: Fixed Mode');
+            navigation.classList.remove(className);
+        }
+    }
+
+    setNavigationMode();
+
+    document.addEventListener(resizedEventName, function(e) {
+        if (e.detail && e.detail.change && e.detail.change.height != 0) {
+            setNavigationMode();
+        }
+    });
+}
+
+export { addStickyNavigation };

data/assets/js/modules/query.js

@@ -0,0 +1,42 @@
+// @ts-check
+
+/**
+ * Utility for query selector
+ * 
+ * @param {string} query
+ * @param {HTMLElement | null} [container]
+ * @returns {HTMLElement}
+ */
+ function qs(query, container) {
+    var target = (container)
+        ? container
+        : document;
+
+    /** @type {HTMLElement | null} */
+    var result = target.querySelector(query);
+
+    if (result) {
+        return result;
+    }
+
+    throw new Error(`No element ${query}`);
+}
+
+/**
+ * Utility for query selector all
+ * 
+ * @param {string} query
+ * @param {HTMLElement | null} [container]
+ * @returns {NodeListOf<any>}
+ */
+ function qsa(query, container) {
+    var target = (container)
+        ? container
+        : document;
+
+    /** @type {NodeListOf<HTMLElement>} */
+    var result = target.querySelectorAll(query);
+    return result;
+}
+
+export { qs, qsa };

data/assets/js/modules/resizing.js

@@ -0,0 +1,43 @@
+// @ts-check
+
+import { raiseEvent } from './events.js';
+
+var resizeEventName = 'resize';
+var resizedEventName = 'resized';
+
+var width = window.innerWidth;
+var height = window.innerHeight;
+
+/**
+ * Adds a de-bounced "resized" event, so you can listen to:
+ * document.addEventListener('resized', <handler>);
+ * 
+ * @returns {string}
+ */
+ function addResizedEvent() {
+    var debounce = null;
+
+    function resizeEnd(e) {
+        window.clearTimeout(debounce);
+        debounce = window.setTimeout(raiseResizeEvent, 500);
+    }
+
+    function raiseResizeEvent() {
+        var change = {
+            width: window.innerWidth - width,
+            height: window.innerHeight - height
+        };
+
+        width = window.innerWidth;
+        height = window.innerHeight;
+        
+
+        raiseEvent(resizedEventName, { change: change });
+    }
+
+    window.addEventListener(resizeEventName, resizeEnd);
+
+    return resizedEventName;
+}
+
+export { addResizedEvent };

data/assets/js/modules/string.js

@@ -0,0 +1,49 @@
+// @ts-check
+
+/**
+ * Looks for a search within a string
+ * 
+ * @param {string} string 
+ * @param {string} search 
+ * @returns 
+ */
+ function contains(string, search) {
+    return string.indexOf(search) > -1;
+}
+
+/**
+ * Simplifies a string to plain lower case, removing diacritic characters and hyphens
+ * This means a search for "co-op" will be found in "COOP" and "Café" will be found in "cafe"
+ * @param {string} string 
+ * @returns 
+ */
+ function sanitise(string) {
+    // @ts-ignore
+    if (String.prototype.normalize) {
+        // Reduces diacritic characters to plain characters
+        string.trim().normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/-/g, '');
+    }
+
+    // Some browsers can't normalise strings
+    return string.trim().toLowerCase().replace(/-/g, '');
+}
+
+/**
+ * Sets a minimum length for a search
+ * @param {string} string 
+ * @returns 
+ */
+ function isLongEnough(string) {
+    return string.length > 1;
+}
+
+/**
+ * Splits a sentence into individual search terms
+ * @param {string} string 
+ * @returns 
+ */
+function explode(string) {
+    return string.split(' ').filter(isLongEnough).map(sanitise);
+}
+
+export { contains, sanitise, explode };

data/assets/js/search.js

@@ -0,0 +1,154 @@
+// @ts-check
+
+import { qs } from './modules/query.js';
+import { raiseEvent } from './modules/events.js';
+import { contains, sanitise, explode } from './modules/string.js';
+
+var haystack = [];
+var needles = [];
+var currentQuery = null;
+
+var ready = false;
+var scrolled = false;
+
+/**
+ * Performs the search
+ * @param {string} s 
+ * @returns 
+ */
+function search(s) {
+    needles = [];
+
+    // Clean the input
+    var cleanQuery = sanitise(s);
+
+    if (currentQuery === cleanQuery) {
+        return;
+    }
+
+    raiseEvent('searched', { search: s });
+
+    currentQuery = cleanQuery;
+
+    var queryTerms = explode(currentQuery);
+
+    for (var i = 0; i < haystack.length; i++) {
+        var item = haystack[i];
+
+        item.score = 0;
+        
+        var title = sanitise(item.title);
+        var category = sanitise(item.category);
+        var tags = sanitise(item.tags);
+
+        for (var j = 0; j < queryTerms.length; j++) {
+            var term = queryTerms[j];
+
+            if (contains(title, term)) {
+                item.score = item.score + 10;
+            }
+
+            if (contains(category, term)) {
+                item.score = item.score + 5;
+            }
+
+            if (contains(tags, term)) {
+                item.score = item.score + 5;
+            }
+        }
+
+        if (item.score > 0) {
+            needles.push(item);
+        }
+    }
+
+    needles.sort(function (a, b){
+        return b.score - a.score;
+    });
+
+    var results = qs('#site-search-results');
+
+    if (results == null) {
+        throw new Error('Cannot find #site-search-results');
+    }
+
+    var ol = document.createElement('ol');
+    ol.className = 'site-search-results';
+
+    var limit = Math.min(needles.length, 12)
+
+    for (var i = 0; i < limit; i++) {
+        var needle = needles[i];
+
+        var a = document.createElement('a');
+        a.innerHTML = needle.title;
+        a.href = needle.url;
+
+        var li = document.createElement('li');
+        li.appendChild(a);
+
+        ol.appendChild(li);
+    }
+
+    var h2 = document.createElement('h2');
+    h2.innerHTML = needles.length === 0
+        ? results.dataset.emptytitle || 'No Results'
+        : results.dataset.title || 'Results';
+
+    results.innerHTML = '';
+    results.appendChild(h2);
+    results.appendChild(ol);
+}
+
+var debounceTimer;
+
+function debounceSearch() {
+    var input = /** @type {HTMLInputElement} */(qs('#site-search-query'));
+
+    if (input == null) {
+        throw new Error('Cannot find #site-search-query');
+    }
+
+    var s = input.value;
+
+    window.clearTimeout(debounceTimer);
+    debounceTimer = window.setTimeout(function () {
+        if (ready) {
+            search(s);
+        }
+    }, 400);
+}
+
+fetch('/search.json')
+    .then(function (response) { 
+        return response.json();
+    })
+    .then(function (data) { 
+        haystack = data;
+        ready = true;
+
+        var siteSearch = qs('#site-search');
+        var siteSearchQuery = qs('#site-search-query');
+
+        if (siteSearch == null || siteSearchQuery == null) {
+            throw new Error('Cannot find #site-search or #site-search-query');
+        }
+    
+        siteSearch.addEventListener('submit', function (e) {
+            e.preventDefault();
+            debounceSearch();
+            return false;
+        });
+    
+        siteSearchQuery.addEventListener('keyup', function (e) {
+            e.preventDefault();
+            if (!scrolled) {
+                scrolled = true;
+                this.scrollIntoView(true);
+            }
+            debounceSearch();
+            return false;
+        });
+
+        console.log('Search ready');
+    });

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fenton-jekyll-boilerplate
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Steve Fenton
@@ -70,6 +70,18 @@ files:
 - assets/icons/favicon-16x16.png
 - assets/icons/favicon-32x32.png
 - assets/icons/favicon.ico
+- assets/js/main.js
+- assets/js/modules/animation.js
+- assets/js/modules/click-blocks.js
+- assets/js/modules/events.js
+- assets/js/modules/focus.js
+- assets/js/modules/nav-expand.js
+- assets/js/modules/nav-mobile.js
+- assets/js/modules/nav-sticky.js
+- assets/js/modules/query.js
+- assets/js/modules/resizing.js
+- assets/js/modules/string.js
+- assets/js/search.js
 homepage: https://jekyll.stevefenton.co.uk/
 licenses:
 - Apache-2.0