@forwardimpact/pathway 0.1.0

package/app/lib/reactive.js

@@ -0,0 +1,77 @@
+/**
+ * Reactive state utilities for local component state
+ */
+
+/**
+ * @template T
+ * @typedef {Object} Reactive
+ * @property {() => T} get - Get current value
+ * @property {(value: T) => void} set - Set new value
+ * @property {(fn: (prev: T) => T) => void} update - Update value with function
+ * @property {(fn: (value: T) => void) => () => void} subscribe - Subscribe to changes
+ */
+
+/**
+ * Create a reactive state container
+ * @template T
+ * @param {T} initial - Initial value
+ * @returns {Reactive<T>}
+ */
+export function createReactive(initial) {
+  let state = initial;
+  const subscribers = new Set();
+
+  return {
+    get: () => state,
+
+    set: (next) => {
+      state = next;
+      subscribers.forEach((fn) => fn(state));
+    },
+
+    update: (fn) => {
+      state = fn(state);
+      subscribers.forEach((sub) => sub(state));
+    },
+
+    subscribe: (fn) => {
+      subscribers.add(fn);
+      return () => subscribers.delete(fn);
+    },
+  };
+}
+
+/**
+ * Create a computed value that updates when dependencies change
+ * @template T
+ * @param {() => T} compute - Computation function
+ * @param {Reactive<*>[]} deps - Dependencies
+ * @returns {Reactive<T>}
+ */
+export function createComputed(compute, deps) {
+  const computed = createReactive(compute());
+
+  deps.forEach((dep) => {
+    dep.subscribe(() => {
+      computed.set(compute());
+    });
+  });
+
+  return computed;
+}
+
+/**
+ * Bind a reactive value to an element attribute
+ * @template T
+ * @param {Reactive<T>} reactive - Reactive state
+ * @param {HTMLElement} element - Element to bind
+ * @param {string} attribute - Attribute name
+ * @param {(value: T) => *} [transform] - Transform function
+ */
+export function bind(reactive, element, attribute, transform = (v) => v) {
+  const update = (value) => {
+    element[attribute] = transform(value);
+  };
+  update(reactive.get());
+  reactive.subscribe(update);
+}

package/app/lib/render.js

@@ -0,0 +1,212 @@
+/**
+ * DOM rendering utilities
+ */
+
+import {
+  SKILL_LEVEL_ORDER,
+  BEHAVIOUR_MATURITY_ORDER,
+} from "../model/levels.js";
+
+/**
+ * Get the main content container
+ * @returns {HTMLElement}
+ */
+export function getContainer() {
+  return document.getElementById("app-content");
+}
+
+/**
+ * Clear and render content to the main container
+ * @param {HTMLElement|string} content
+ */
+export function render(content) {
+  const container = getContainer();
+  container.innerHTML = "";
+
+  if (typeof content === "string") {
+    container.innerHTML = content;
+  } else if (content instanceof HTMLElement) {
+    container.appendChild(content);
+  }
+}
+
+/**
+ * Create an element with attributes and children
+ * @param {string} tag - HTML tag name
+ * @param {Object} [attrs] - Attributes and properties
+ * @param {...(HTMLElement|string)} children - Child elements or text
+ * @returns {HTMLElement}
+ */
+export function createElement(tag, attrs = {}, ...children) {
+  const element = document.createElement(tag);
+
+  for (const [key, value] of Object.entries(attrs)) {
+    if (key === "className") {
+      element.className = value;
+    } else if (key === "style" && typeof value === "object") {
+      Object.assign(element.style, value);
+    } else if (key.startsWith("on") && typeof value === "function") {
+      element.addEventListener(key.slice(2).toLowerCase(), value);
+    } else if (key === "dataset" && typeof value === "object") {
+      Object.assign(element.dataset, value);
+    } else if (typeof value === "boolean") {
+      // Handle boolean attributes - only set if true, skip if false
+      if (value) {
+        element.setAttribute(key, "");
+      }
+    } else {
+      element.setAttribute(key, value);
+    }
+  }
+
+  for (const child of children) {
+    if (child == null || child === false) continue;
+    if (typeof child === "string" || typeof child === "number") {
+      element.appendChild(document.createTextNode(String(child)));
+    } else if (child instanceof HTMLElement) {
+      element.appendChild(child);
+    } else if (Array.isArray(child)) {
+      child.forEach((c) => {
+        if (c == null || c === false) return;
+        if (c instanceof HTMLElement) {
+          element.appendChild(c);
+        } else if (typeof c === "string" || typeof c === "number") {
+          element.appendChild(document.createTextNode(String(c)));
+        }
+      });
+    }
+  }
+
+  return element;
+}
+
+// Shorthand element creators
+export const div = (attrs, ...children) =>
+  createElement("div", attrs, ...children);
+export const span = (attrs, ...children) =>
+  createElement("span", attrs, ...children);
+export const h1 = (attrs, ...children) =>
+  createElement("h1", attrs, ...children);
+export const h2 = (attrs, ...children) =>
+  createElement("h2", attrs, ...children);
+export const h3 = (attrs, ...children) =>
+  createElement("h3", attrs, ...children);
+export const h4 = (attrs, ...children) =>
+  createElement("h4", attrs, ...children);
+export const p = (attrs, ...children) => createElement("p", attrs, ...children);
+export const a = (attrs, ...children) => createElement("a", attrs, ...children);
+export const ul = (attrs, ...children) =>
+  createElement("ul", attrs, ...children);
+export const li = (attrs, ...children) =>
+  createElement("li", attrs, ...children);
+export const table = (attrs, ...children) =>
+  createElement("table", attrs, ...children);
+export const thead = (attrs, ...children) =>
+  createElement("thead", attrs, ...children);
+export const tbody = (attrs, ...children) =>
+  createElement("tbody", attrs, ...children);
+export const tr = (attrs, ...children) =>
+  createElement("tr", attrs, ...children);
+export const th = (attrs, ...children) =>
+  createElement("th", attrs, ...children);
+export const td = (attrs, ...children) =>
+  createElement("td", attrs, ...children);
+export const button = (attrs, ...children) =>
+  createElement("button", attrs, ...children);
+export const input = (attrs) => createElement("input", attrs);
+export const select = (attrs, ...children) =>
+  createElement("select", attrs, ...children);
+export const option = (attrs, ...children) =>
+  createElement("option", attrs, ...children);
+export const label = (attrs, ...children) =>
+  createElement("label", attrs, ...children);
+export const form = (attrs, ...children) =>
+  createElement("form", attrs, ...children);
+export const section = (attrs, ...children) =>
+  createElement("section", attrs, ...children);
+export const article = (attrs, ...children) =>
+  createElement("article", attrs, ...children);
+export const header = (attrs, ...children) =>
+  createElement("header", attrs, ...children);
+export const footer = (attrs, ...children) =>
+  createElement("footer", attrs, ...children);
+export const nav = (attrs, ...children) =>
+  createElement("nav", attrs, ...children);
+export const main = (attrs, ...children) =>
+  createElement("main", attrs, ...children);
+export const details = (attrs, ...children) =>
+  createElement("details", attrs, ...children);
+export const summary = (attrs, ...children) =>
+  createElement("summary", attrs, ...children);
+
+/**
+ * Semantic heading aliases that match heading levels
+ * Use these instead of h1/h2/h3 for clarity in slides and formatters
+ */
+export const heading1 = h1;
+export const heading2 = h2;
+export const heading3 = h3;
+
+/**
+ * Create a fragment from multiple elements
+ * @param {...HTMLElement} children
+ * @returns {DocumentFragment}
+ */
+export function fragment(...children) {
+  const frag = document.createDocumentFragment();
+  children.forEach((child) => {
+    if (child instanceof HTMLElement) {
+      frag.appendChild(child);
+    }
+  });
+  return frag;
+}
+
+/**
+ * Show a loading state
+ */
+export function showLoading() {
+  render(
+    div(
+      { className: "loading" },
+      div({ className: "loading-spinner" }),
+      p({}, "Loading..."),
+    ),
+  );
+}
+
+/**
+ * Show an error message
+ * @param {string} message
+ */
+export function showError(message) {
+  render(div({ className: "error-message" }, h2({}, "Error"), p({}, message)));
+}
+
+/**
+ * Format a skill level or behaviour maturity for display
+ * @param {string} value - The level/maturity value
+ * @returns {string}
+ */
+export function formatLevel(value) {
+  if (!value) return "";
+  return value.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Get the index for a skill level (1-5)
+ * @param {string} level
+ * @returns {number}
+ */
+export function getSkillLevelIndex(level) {
+  return SKILL_LEVEL_ORDER.indexOf(level) + 1;
+}
+
+/**
+ * Get the index for a behaviour maturity (1-5)
+ * @param {string} maturity
+ * @returns {number}
+ */
+export function getBehaviourMaturityIndex(maturity) {
+  return BEHAVIOUR_MATURITY_ORDER.indexOf(maturity) + 1;
+}

package/app/lib/router-core.js

@@ -0,0 +1,160 @@
+/**
+ * Core Router Factory
+ *
+ * Pure factory function for hash-based routing with no dependencies.
+ */
+
+import { withErrorBoundary } from "./error-boundary.js";
+
+/**
+ * @typedef {Object} Route
+ * @property {string} pattern - Route pattern with :params
+ * @property {RegExp} regex - Compiled pattern
+ * @property {string[]} paramNames - Extracted param names
+ * @property {Function} handler - Route handler
+ */
+
+/**
+ * @typedef {Object} RouteMatch
+ * @property {Function} handler - Matched handler
+ * @property {Object} params - Extracted parameters
+ */
+
+/**
+ * @typedef {Object} Router
+ * @property {(pattern: string, handler: Function) => void} on - Register route
+ * @property {(path: string) => void} navigate - Navigate to path
+ * @property {() => string} currentPath - Get current hash path
+ * @property {() => void} handleRoute - Process current route
+ * @property {() => void} start - Begin listening for hash changes
+ * @property {() => void} stop - Stop listening for hash changes
+ * @property {() => string[]} patterns - Get registered patterns
+ */
+
+/**
+ * Parse route pattern into regex and param names
+ * @param {string} pattern
+ * @returns {{ regex: RegExp, paramNames: string[] }}
+ */
+function parsePattern(pattern) {
+  const paramNames = [];
+  const regexStr = pattern
+    .replace(/:([^/]+)/g, (_, name) => {
+      paramNames.push(name);
+      return "([^/]+)";
+    })
+    .replace(/\//g, "\\/");
+  return {
+    regex: new RegExp(`^${regexStr}$`),
+    paramNames,
+  };
+}
+
+/**
+ * Create a router instance
+ * @param {{ onNotFound?: (path: string) => void, onError?: (error: Error) => void, renderError?: (title: string, message: string) => void }} options
+ * @returns {Router}
+ */
+export function createRouter(options = {}) {
+  const { onNotFound = () => {}, onError, renderError } = options;
+  /** @type {Route[]} */
+  const routes = [];
+  let hashChangeHandler = null;
+
+  /**
+   * Match a path to a route
+   * @param {string} path
+   * @returns {RouteMatch|null}
+   */
+  function matchRoute(path) {
+    for (const route of routes) {
+      const match = path.match(route.regex);
+      if (match) {
+        const params = {};
+        route.paramNames.forEach((name, i) => {
+          params[name] = decodeURIComponent(match[i + 1]);
+        });
+        return { handler: route.handler, params };
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get current path from hash (including query string)
+   * @returns {string}
+   */
+  function currentPath() {
+    return window.location.hash.slice(1) || "/";
+  }
+
+  /**
+   * Handle the current route
+   */
+  function handleRoute() {
+    const fullPath = currentPath();
+    const path = fullPath.split("?")[0];
+    const matched = matchRoute(path);
+    if (matched) {
+      matched.handler(matched.params);
+    } else {
+      onNotFound(path);
+    }
+  }
+
+  return {
+    /**
+     * Register a route
+     * @param {string} pattern - Route pattern (e.g., '/skills/:id')
+     * @param {Function} handler - Handler function
+     */
+    on(pattern, handler) {
+      const { regex, paramNames } = parsePattern(pattern);
+      const wrappedHandler = withErrorBoundary(handler, {
+        onError,
+        backPath: "/",
+        backText: "← Back to Home",
+        renderErrorFn: renderError,
+      });
+      routes.push({ pattern, regex, paramNames, handler: wrappedHandler });
+    },
+
+    /**
+     * Navigate to a path
+     * @param {string} path
+     */
+    navigate(path) {
+      window.location.hash = path;
+    },
+
+    currentPath,
+    handleRoute,
+
+    /**
+     * Start listening for hash changes
+     */
+    start() {
+      hashChangeHandler = () => handleRoute();
+      window.addEventListener("hashchange", hashChangeHandler);
+      handleRoute();
+    },
+
+    /**
+     * Stop listening for hash changes
+     */
+    stop() {
+      if (hashChangeHandler) {
+        window.removeEventListener("hashchange", hashChangeHandler);
+        hashChangeHandler = null;
+      }
+    },
+
+    /**
+     * Get all registered route patterns
+     * @returns {string[]}
+     */
+    patterns() {
+      return routes.map((r) => r.pattern);
+    },
+  };
+}

package/app/lib/router-pages.js

@@ -0,0 +1,16 @@
+/**
+ * Pages Router
+ *
+ * Router instance for the main app pages.
+ */
+
+import { createRouter } from "./router-core.js";
+
+/**
+ * Create the pages router for the main app
+ * @param {{ onNotFound?: (path: string) => void }} options
+ * @returns {import('./router-core.js').Router}
+ */
+export function createPagesRouter(options = {}) {
+  return createRouter(options);
+}

package/app/lib/router-slides.js

@@ -0,0 +1,202 @@
+/**
+ * Slide Router
+ *
+ * Extended router with navigation state and keyboard controls for slides.
+ */
+
+import { createRouter } from "./router-core.js";
+
+/**
+ * @typedef {Object} SlideRouter
+ * @property {(pattern: string, handler: Function) => void} on - Register route
+ * @property {(path: string) => void} navigate - Navigate to path
+ * @property {() => string} currentPath - Get current hash path
+ * @property {() => void} handleRoute - Process current route
+ * @property {() => void} start - Begin listening for hash changes
+ * @property {() => void} stop - Stop listening for hash changes
+ * @property {() => string[]} patterns - Get registered patterns
+ * @property {(paths: string[]) => void} setSlideOrder - Define navigation order
+ * @property {() => void} next - Navigate to next slide
+ * @property {() => void} prev - Navigate to previous slide
+ * @property {() => void} home - Navigate to index
+ * @property {() => number} currentIndex - Current position in order
+ * @property {() => number} totalSlides - Total slide count
+ * @property {() => void} startKeyboardNav - Enable keyboard shortcuts
+ * @property {() => void} stopKeyboardNav - Disable keyboard shortcuts
+ */
+
+/**
+ * Create a slide router with navigation capabilities
+ * @param {{ onNotFound?: (path: string) => void, renderError?: (title: string, message: string) => void }} options
+ * @returns {SlideRouter}
+ */
+export function createSlideRouter(options = {}) {
+  const router = createRouter(options);
+  let slideOrder = [];
+  let chapterBoundaries = [];
+  let keyHandler = null;
+
+  /**
+   * Find current position in slide order
+   * @returns {number}
+   */
+  function findCurrentIndex() {
+    const path = router.currentPath();
+    return slideOrder.indexOf(path);
+  }
+
+  /**
+   * Navigate to slide at given index
+   * @param {number} index
+   */
+  function navigateToIndex(index) {
+    if (index >= 0 && index < slideOrder.length) {
+      router.navigate(slideOrder[index]);
+    }
+  }
+
+  const slideRouter = {
+    // Expose core router methods
+    on: router.on,
+    navigate: router.navigate,
+    currentPath: router.currentPath,
+    handleRoute: router.handleRoute,
+    start: router.start,
+    stop: router.stop,
+    patterns: router.patterns,
+
+    /**
+     * Define the slide navigation order
+     * @param {string[]} paths
+     * @param {number[]} boundaries - Indices where chapters start
+     */
+    setSlideOrder(paths, boundaries = []) {
+      slideOrder = paths;
+      chapterBoundaries = boundaries;
+    },
+
+    /**
+     * Navigate to next slide
+     */
+    next() {
+      const idx = findCurrentIndex();
+      navigateToIndex(idx + 1);
+    },
+
+    /**
+     * Navigate to previous slide
+     */
+    prev() {
+      const idx = findCurrentIndex();
+      navigateToIndex(idx - 1);
+    },
+
+    /**
+     * Navigate to previous chapter
+     */
+    prevChapter() {
+      const idx = findCurrentIndex();
+      // Find the previous chapter boundary before current position
+      const prevBoundary = chapterBoundaries.filter((b) => b < idx).pop();
+      if (prevBoundary !== undefined) {
+        navigateToIndex(prevBoundary);
+      } else if (idx > 0) {
+        navigateToIndex(0);
+      }
+    },
+
+    /**
+     * Navigate to next chapter
+     */
+    nextChapter() {
+      const idx = findCurrentIndex();
+      // Find the next chapter boundary after current position
+      const nextBoundary = chapterBoundaries.find((b) => b > idx);
+      if (nextBoundary !== undefined) {
+        navigateToIndex(nextBoundary);
+      }
+    },
+
+    /**
+     * Navigate to first slide (index)
+     */
+    home() {
+      navigateToIndex(0);
+    },
+
+    /**
+     * Get current slide index
+     * @returns {number}
+     */
+    currentIndex() {
+      return findCurrentIndex();
+    },
+
+    /**
+     * Get total number of slides
+     * @returns {number}
+     */
+    totalSlides() {
+      return slideOrder.length;
+    },
+
+    /**
+     * Start keyboard navigation
+     */
+    startKeyboardNav() {
+      keyHandler = (e) => {
+        // Ignore if typing in an input
+        if (e.target.tagName === "INPUT" || e.target.tagName === "TEXTAREA") {
+          return;
+        }
+
+        switch (e.key) {
+          case "ArrowRight":
+          case " ":
+          case "PageDown":
+            e.preventDefault();
+            slideRouter.next();
+            break;
+          case "ArrowLeft":
+          case "PageUp":
+            e.preventDefault();
+            slideRouter.prev();
+            break;
+          case "ArrowDown":
+            e.preventDefault();
+            slideRouter.nextChapter();
+            break;
+          case "ArrowUp":
+            e.preventDefault();
+            slideRouter.prevChapter();
+            break;
+          case "Home":
+            e.preventDefault();
+            slideRouter.home();
+            break;
+          case "End":
+            e.preventDefault();
+            navigateToIndex(slideOrder.length - 1);
+            break;
+          case "Escape":
+            e.preventDefault();
+            slideRouter.home();
+            break;
+        }
+      };
+      document.addEventListener("keydown", keyHandler);
+    },
+
+    /**
+     * Stop keyboard navigation
+     */
+    stopKeyboardNav() {
+      if (keyHandler) {
+        document.removeEventListener("keydown", keyHandler);
+        keyHandler = null;
+      }
+    },
+  };
+
+  return slideRouter;
+}