@kenjura/ursa 0.10.0 → 0.32.0

package/meta/toc-generator.js

@@ -0,0 +1,124 @@
+// Table of Contents Generator
+document.addEventListener('DOMContentLoaded', () => {
+    const tocNav = document.getElementById('nav-toc');
+    const article = document.querySelector('article#main-content');
+    
+    if (!tocNav || !article) return;
+    
+    // Find all headings in the article
+    const headings = article.querySelectorAll('h1, h2, h3');
+    
+    if (headings.length === 0) {
+        tocNav.style.display = 'none';
+        return;
+    }
+    
+    // Generate TOC HTML
+    const tocList = document.createElement('ul');
+    
+    headings.forEach((heading, index) => {
+        // Create unique ID for the heading if it doesn't have one
+        if (!heading.id) {
+            const text = heading.textContent.trim()
+                .toLowerCase()
+                .replace(/[^\w\s-]/g, '') // Remove special characters
+                .replace(/\s+/g, '-'); // Replace spaces with hyphens
+            heading.id = `heading-${index}-${text}`;
+        }
+        
+        // Create TOC item
+        const listItem = document.createElement('li');
+        listItem.className = `toc-${heading.tagName.toLowerCase()}`;
+        
+        const link = document.createElement('a');
+        link.href = `#${heading.id}`;
+        link.textContent = heading.textContent;
+        link.addEventListener('click', handleTocClick);
+        
+        listItem.appendChild(link);
+        tocList.appendChild(listItem);
+    });
+    
+    tocNav.appendChild(tocList);
+    
+    // Handle TOC link clicks for smooth scrolling
+    function handleTocClick(e) {
+        e.preventDefault();
+        const targetId = e.target.getAttribute('href').substring(1);
+        const targetElement = document.getElementById(targetId);
+        
+        if (targetElement) {
+            // Calculate offset to account for sticky header
+            const globalNavHeight = getComputedStyle(document.documentElement)
+                .getPropertyValue('--global-nav-height') || '48px';
+            const offset = parseInt(globalNavHeight) + 40; // Adjusted offset (was +20, now -29 for 49px less)
+            
+            const targetPosition = targetElement.getBoundingClientRect().top + window.pageYOffset - offset;
+            
+            window.scrollTo({
+                top: targetPosition,
+                behavior: 'smooth'
+            });
+        }
+    }
+    
+    // Update active TOC item based on scroll position
+    function updateActiveTocItem() {
+        const scrollPosition = window.pageYOffset;
+        const globalNavHeight = getComputedStyle(document.documentElement)
+            .getPropertyValue('--global-nav-height') || '48px';
+        const offset = parseInt(globalNavHeight) + 100;
+        
+        let activeHeading = null;
+        
+        // Find the current heading based on scroll position
+        headings.forEach(heading => {
+            const headingTop = heading.getBoundingClientRect().top + window.pageYOffset;
+            if (headingTop <= scrollPosition + offset) {
+                activeHeading = heading;
+            }
+        });
+        
+        updateTocActiveState(activeHeading);
+    }
+    
+    // Update TOC active state
+    function updateTocActiveState(activeHeading) {
+        const tocLinks = tocNav.querySelectorAll('a');
+        tocLinks.forEach(link => {
+            link.classList.remove('active');
+        });
+        
+        if (activeHeading) {
+            const activeLink = tocNav.querySelector(`a[href="#${activeHeading.id}"]`);
+            if (activeLink) {
+                activeLink.classList.add('active');
+            }
+        }
+    }
+    
+    // Listen for heading stuck state changes from sticky.js
+    document.addEventListener('headingStuckStateChanged', (event) => {
+        if (event.detail.currentStuckHeading) {
+            updateTocActiveState(event.detail.currentStuckHeading);
+        } else {
+            // If no heading is stuck, fall back to scroll-based detection
+            updateActiveTocItem();
+        }
+    });
+    
+    // Listen for scroll events
+    let ticking = false;
+    window.addEventListener('scroll', () => {
+        if (!ticking) {
+            requestAnimationFrame(() => {
+                updateActiveTocItem();
+                ticking = false;
+            });
+            ticking = true;
+        }
+    });
+    
+    // Initial update
+    updateActiveTocItem();
+});

package/meta/toc.js

@@ -0,0 +1,93 @@
+(() => {
+  const toc = document.getElementById('toc');
+  if (!toc) return;
+
+  const links = Array.from(toc.querySelectorAll('a[href^="#"]'));
+  const heads = links
+    .map(a => document.getElementById(decodeURIComponent(a.hash.slice(1))))
+    .filter(Boolean);
+
+  const linkById = new Map(links.map(a => [decodeURIComponent(a.hash.slice(1)), a]));
+
+  // === sticky top detector ===
+  let STICKY_TOP = 48; // fallback
+  const nav = document.getElementById('nav-global');
+
+  function readStickyTop() {
+    const b = nav?.getBoundingClientRect();
+    // if nav is fixed at top, its bottom is the sticky line
+    STICKY_TOP = b ? Math.max(0, Math.round(b.bottom)) : 48;
+  }
+
+  readStickyTop();
+  window.addEventListener('resize', readStickyTop, { passive: true });
+  if (nav && 'ResizeObserver' in window) {
+    new ResizeObserver(readStickyTop).observe(nav);
+  }
+
+  // === build 1px sentinels just above each heading ===
+  function ensureSentinels() {
+    heads.forEach(h => {
+      if (h.previousElementSibling?.classList.contains('toc-sentinel')) return;
+      const s = document.createElement('div');
+      s.className = 'toc-sentinel';
+      s.style.position = 'relative';
+      s.style.height = '1px';
+      s.style.marginTop = `-${STICKY_TOP}px`; // place sentinel STICKY_TOP above h
+      s.style.pointerEvents = 'none';
+      s.dataset.forId = h.id;
+      h.before(s);
+    });
+  }
+
+  // === observer factory tied to current STICKY_TOP ===
+  let observer = null;
+  function (re)buildObserver() {
+    if (observer) observer.disconnect();
+    // ignore intersections near the bottom; we only care about the top line
+    const bottomRM = -(window.innerHeight - 1) + 'px';
+    observer = new IntersectionObserver(updateActiveFromSentinels, {
+      root: null,
+      rootMargin: `-${STICKY_TOP}px 0px ${bottomRM} 0px`,
+      threshold: 0
+    });
+    document.querySelectorAll('.toc-sentinel').forEach(s => observer.observe(s));
+  }
+
+  function updateActiveFromSentinels() {
+    // Pick the last sentinel whose top is <= 0 relative to the adjusted rootMargin,
+    // i.e. the heading whose sticky line has been crossed.
+    const sentinels = Array.from(document.querySelectorAll('.toc-sentinel'));
+    let candidate = null;
+    for (const s of sentinels) {
+      const top = s.getBoundingClientRect().top - STICKY_TOP; // compare to sticky line
+      if (top <= 0) candidate = s; else break;
+    }
+    const activeId = candidate ? candidate.dataset.forId : heads[0]?.id;
+    links.forEach(a => a.classList.toggle('active', decodeURIComponent(a.hash.slice(1)) === activeId));
+  }
+
+  // keep anchor jumps clear of the sticky bar
+  heads.forEach(h => h.style.scrollMarginTop = (STICKY_TOP + 8) + 'px');
+
+  // initial setup
+  ensureSentinels();
+  (re)buildObserver();
+  updateActiveFromSentinels();
+
+  // react when sticky top changes
+  let resizeTick = false;
+  window.addEventListener('resize', () => {
+    if (resizeTick) return;
+    resizeTick = true;
+    requestAnimationFrame(() => {
+      resizeTick = false;
+      readStickyTop();
+      // update sentinel offsets
+      document.querySelectorAll('.toc-sentinel').forEach(s => s.style.marginTop = `-${STICKY_TOP}px`);
+      heads.forEach(h => h.style.scrollMarginTop = (STICKY_TOP + 8) + 'px');
+      (re)buildObserver();
+      updateActiveFromSentinels();
+    });
+  }, { passive: true });
+})();

package/package.json

@@ -2,12 +2,17 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.10.0",
+  "version": "0.32.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
+  "bin": {
+    "ursa": "bin/ursa.js"
+  },
   "scripts": {
     "serve": "nodemon --config nodemon.json  src/serve.js",
     "serve:debug": "nodemon --config nodemon.json  --inspect-brk src/serve.js",
+    "cli:debug": "node --inspect bin/ursa.js",
+    "cli:debug-brk": "node --inspect-brk bin/ursa.js",
     "start": "node src/index.js",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
   },
@@ -27,7 +32,8 @@
     "markdown-it-sup": "^1.0.0",
     "node-watch": "^0.7.3",
     "object-to-xml": "^2.0.0",
-    "yaml": "^2.1.3"
+    "yaml": "^2.1.3",
+    "yargs": "^17.7.2"
   },
   "devDependencies": {
     "jest": "^29.6.2",
@@ -43,6 +49,21 @@
   },
   "keywords": [
     "static-site",
-    "markdown"
-  ]
+    "markdown",
+    "static-site-generator",
+    "wikitext",
+    "cli"
+  ],
+  "files": [
+    "lib/",
+    "src/",
+    "bin/",
+    "meta/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
 }

package/src/helper/WikiImage.js

@@ -0,0 +1,138 @@
+export function getImageTag(args) {
+	if (!args) args = {};
+	if (!args.name) { console.error('WikiImage.getImage > cannot get image with no name.'); return ''; }
+	// if (!args.article) { console.error('WikiImage.getImage > article not supplied.'); return ''; }
+	
+	// var images = args.article.images;
+	// var image = null;
+	// if (images) {
+	// 	for (var i = 0; i < images.length; i++) {
+	// 		if ( images[i].name == args.name ) {
+	// 			image = images[i];
+	// 			break;
+	// 		}
+	// 	}
+	// }
+	// if (!image) {
+	// 	// image not yet uploaded
+	// 	return '<div class="noImage" ng-click="activateImage(\''+args.name+'\')">?</div>';
+	// } else {
+		// path
+		// var imgUrl = WikiImage.imageRoot + image.path;		
+		var imgUrl = args.imgUrl;		
+		// style
+		var width = 'auto', height = 'auto', classes = '', caption = '', fillMode = null, float = '';
+		if (args.args&&args.args.length) {
+			for (var i = 0; i < args.args.length; i++) {
+				var arg = args.args[i];
+				// numbers = width/height. for now, let's just do width
+				if (!isNaN(arg)) { 
+					if (width=='auto') width = parseFloat(arg) + 'px'; 
+					else height = parseFloat(arg) + 'px';
+					continue; 
+				}
+				if (arg.substr(-1)=='%') { 
+					if (width=='auto') width = arg; 
+					else height = arg;
+					continue; 
+				}
+				if (arg.substr(-2)=='px') { 
+					if (width=='auto') width = arg; 
+					else height = arg;
+					continue; 
+				}
+				// string values might mean something...
+				if (arg=='right') { float = 'float: right; clear: right;'; continue; }
+				if (arg=='fit'||arg=='box') { classes += arg + ' '; continue; }
+				if (arg=='center') { classes += 'center '; continue; }
+				if (arg=='cover'||arg=='contain') { fillMode = arg; continue; }
+				// else, assume it's the caption
+				caption = arg;
+			}
+		}		
+		var style = 'width: '+width+'; height: '+height+';' + float;
+		
+		// events		
+		// var events = 'onclick="_scope.activateImage(\''+args.name+'\',\''+imgUrl+'\')"';	
+		var events = 'ng-click="activateImage(\''+args.name+'\',\''+imgUrl+'\')"';
+		
+		//return '<img class="wikiImage" src="'+imgUrl+'" style="'+style+'" '+events+' />';
+
+		var template = ''+
+		'<a href="{src}">'+
+			'<div class="wikiImage {class}" style="{style}" title="{caption}">'+
+				'<img src="{src}" {events} />'+
+				'<div class="wikiImage_caption">{caption}</div>'+
+			'</div>'+
+		'</a>';
+
+		// var template2 = ''+
+		// '<a href="{src}">'+
+		// 	'<div class="wikiImage {class}" style="background: url(\'{src}\'); background-size: {fillMode}; {style}" {events}>'+
+		// 		'<div class="wikiImage_caption">{caption}</div>'+
+		// 	'</div>'+
+		// '</a>';
+
+		const template2 = `<span class="wiki-image-container"><img src="${imgUrl}" style="${style}" class="wikiImage wiki-image" onClick="evt => imageZoom(evt)" />`;
+		return template2;
+
+
+		var html = template;
+		if (fillMode) html = template2;
+
+		html = html.replace( /\{src\}/g , imgUrl );
+		html = html.replace( '{class}' , classes );
+		html = html.replace( '{style}' , style );
+		html = html.replace( '{events}' , events );
+		html = html.replace( /\{caption\}/g , caption );
+		if (fillMode)
+			html = html.replace( '{fillMode}' , fillMode );
+
+		return html;
+	// }
+	
+	/*
+	var imgCache = localStorage.getItem('imageCache');
+	if (!imgCache) imgCache = JSON.stringify({});
+	
+	try {
+		imgCache = JSON.parse(imgCache);
+		var imgUrl = imgCache[args.name];
+		if (!imgUrl) {
+			//var img = new WikiImage(args);
+			var img = new WikiImage(args);
+			var tag = img.render();
+			imgCache[args.name] = img.url;						
+		} else {
+			args.url = imgUrl;			
+			var img = new WikiImage(args);			
+			var tag = img.render();
+		}
+		localStorage.setItem('imageCache',JSON.stringify(imgCache));
+		return tag;
+	} catch(e) {
+		error('WikiImage.getImage > could not retrieve or parse the image cache. error to follow.');
+		error(e);
+		return new WikiImage(args);
+	}
+	*/
+
+	
+}
+
+
+
+
+/* how images should work:
+* when you load an article, you also get a list of all images used in that article, and their URLs
+* when rendering an image, check that list first. if the image name isn't in that list, don't bother trying to load the image
+** if it is in the list, load it, relying on browser cache to reduce load
+** important: do not use the server method to find each image's url; get them all from the loadArticle call
+** the FS db option should store image (and link) data in a special section at the end of the article body. it also doesn't allow images to have a different name than their url
+* when an image is not yet uploaded, show a gray box with a question mark
+* when the grey box or the image is clicked, pop up the image upload modal
+* the image upload modal uses the appropriate service endpoint to upload, then returns the new URL
+** the new URL is then cached
+** the image is loaded from the URL
+** the image is associated with the article, which is immediately saved with the new image association
+*/

package/src/helper/automenu.js

@@ -1,69 +1,225 @@
 import dirTree from "directory-tree";
-import { extname, basename } from "path";
+import { extname, basename, join, dirname } from "path";
+import { existsSync } from "fs";
 
-export async function getAutomenu(source) {
-  const tree = dirTree(source);
-  const menuItems = [];
+// Icon extensions to check for custom icons
+const ICON_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico'];
 
-  /** order of menu items:
-   *  - Home
-   *  - Top-level folders A-Z
-   *  - Top-level files A-Z
-   **/
+// Default icons (using emoji for simplicity, can be replaced with SVG)
+const FOLDER_ICON = '📁';
+const DOCUMENT_ICON = '📄';
+const HOME_ICON = '🏠';
 
-  menuItems.push({
-    path: "/",
-    name: "Home",
-    type: "file",
-  });
+// Index file extensions to check for folder links
+const INDEX_EXTENSIONS = ['.md', '.txt', '.yml', '.yaml'];
 
-  const topLevelItems = tree.children.sort(childSorter);
-  const topLevelHtml = topLevelItems
-    .map((item) => renderMenuItem({ ...item, source }))
-    .join("");
+function hasIndexFile(dirPath) {
+  for (const ext of INDEX_EXTENSIONS) {
+    const indexPath = join(dirPath, `index${ext}`);
+    if (existsSync(indexPath)) {
+      return true;
+    }
+  }
+  return false;
+}
 
-  return `<ul>${topLevelHtml}</ul>`;
+function findCustomIcon(dirPath, source) {
+  for (const ext of ICON_EXTENSIONS) {
+    const iconPath = join(dirPath, `icon${ext}`);
+    if (existsSync(iconPath)) {
+      // Return the web-accessible path
+      return iconPath.replace(source, '/');
+    }
+  }
+  return null;
 }
 
-function renderMenuItem({ path, name, children, source }) {
-  const ext = extname(path);
-  const href = path.replace(source, "").replace(ext, "");
-  const label = basename(path, ext);
-  //   const childMenuItems = Array.isArray(children)
-  //     ? children
-  //         .map((child) => renderMenuItem({ ...child, source }))
-  //         .sort(menuItemSorter)
-  //     : null;
-  const html = `
-<li data-has-children="${!!children}">
-  <a href="/${href}">${label}</a>
-  ${
-    children
-      ? `<ul>
-    ${children
-      .sort(childSorter)
-      .map((child) => renderMenuItem({ ...child, source }))
-      .join("")}
-  </ul>`
-      : ""
+function getIcon(item, source, isHome = false) {
+  if (isHome) {
+    return `<span class="menu-icon">${HOME_ICON}</span>`;
   }
-</li>`;
-  return html;
+  
+  if (item.children) {
+    // It's a folder - check for custom icon
+    const customIcon = findCustomIcon(item.path, source);
+    if (customIcon) {
+      return `<span class="menu-icon"><img src="${customIcon}" alt="" /></span>`;
+    }
+    return `<span class="menu-icon">${FOLDER_ICON}</span>`;
+  }
+  
+  // It's a file - check for custom icon in parent directory with matching name
+  const dir = dirname(item.path);
+  const base = basename(item.path, extname(item.path));
+  for (const ext of ICON_EXTENSIONS) {
+    const iconPath = join(dir, `${base}-icon${ext}`);
+    if (existsSync(iconPath)) {
+      return `<span class="menu-icon"><img src="${iconPath.replace(source, '/')}" alt="" /></span>`;
+    }
+  }
+  
+  return `<span class="menu-icon">${DOCUMENT_ICON}</span>`;
+}
 
-  return {
-    href,
-    label,
-    childMenuItems,
-  };
+/**
+ * Resolve an href to a valid .html file path, checking against validPaths.
+ * Returns { href, inactive, debug } where inactive is true if the link doesn't resolve to a valid path.
+ * 
+ * Logic:
+ * - "/" -> "/index.html"
+ * - Any link lacking an extension:
+ *   - Try adding ".html" - if path exists, use it
+ *   - Try adding "/index.html" - if path exists, use it
+ *   - Otherwise, mark as inactive
+ * - Links with extensions are checked directly
+ */
+function resolveHref(rawHref, validPaths) {
+  const debugTries = [];
+  
+  if (!rawHref) {
+    return { href: null, inactive: false, debug: 'null href' };
+  }
+  
+  // Normalize for checking (lowercase)
+  const normalize = (path) => path.toLowerCase();
+  
+  // Root link
+  if (rawHref === '/') {
+    const indexPath = '/index.html';
+    const exists = validPaths.has(normalize(indexPath));
+    debugTries.push(`${indexPath} → ${exists ? '✓' : '✗'}`);
+    if (exists) {
+      return { href: '/index.html', inactive: false, debug: debugTries.join(' | ') };
+    }
+    return { href: '/', inactive: true, debug: debugTries.join(' | ') };
+  }
+  
+  // Check if the link already has an extension
+  const ext = extname(rawHref);
+  if (ext) {
+    // Has extension - check if path exists
+    const exists = validPaths.has(normalize(rawHref));
+    debugTries.push(`${rawHref} → ${exists ? '✓' : '✗'}`);
+    return { href: rawHref, inactive: !exists, debug: debugTries.join(' | ') };
+  }
+  
+  // No extension - try .html first
+  const htmlPath = rawHref + '.html';
+  const htmlExists = validPaths.has(normalize(htmlPath));
+  debugTries.push(`${htmlPath} → ${htmlExists ? '✓' : '✗'}`);
+  if (htmlExists) {
+    return { href: htmlPath, inactive: false, debug: debugTries.join(' | ') };
+  }
+  
+  // Try /index.html
+  const indexPath = rawHref + '/index.html';
+  const indexExists = validPaths.has(normalize(indexPath));
+  debugTries.push(`${indexPath} → ${indexExists ? '✓' : '✗'}`);
+  if (indexExists) {
+    return { href: indexPath, inactive: false, debug: debugTries.join(' | ') };
+  }
+  
+  // Neither exists - mark as inactive, keep original href
+  return { href: rawHref, inactive: true, debug: debugTries.join(' | ') };
+}
+
+// Build a flat tree structure with path info for JS navigation
+function buildMenuData(tree, source, validPaths, parentPath = '') {
+  const items = [];
+  
+  for (const item of tree.children || []) {
+    const ext = extname(item.path);
+    const label = basename(item.path, ext);
+    const hasChildren = !!item.children;
+    const relativePath = item.path.replace(source, '');
+    const folderPath = parentPath ? `${parentPath}/${label}` : label;
+    
+    let rawHref = null;
+    if (hasChildren) {
+      if (hasIndexFile(item.path)) {
+        rawHref = `/${relativePath}/index.html`;
+      }
+    } else {
+      rawHref = `/${relativePath.replace(ext, '')}`;
+    }
+    
+    // Resolve the href and check if target exists
+    const { href, inactive, debug } = resolveHref(rawHref, validPaths);
+    
+    const menuItem = {
+      label,
+      path: folderPath,
+      href,
+      inactive,
+      debug,
+      hasChildren,
+      icon: getIcon(item, source),
+    };
+    
+    if (hasChildren) {
+      menuItem.children = buildMenuData(item, source, validPaths, folderPath);
+    }
+    
+    items.push(menuItem);
+  }
+  
+  return items.sort((a, b) => {
+    if (a.hasChildren && !b.hasChildren) return -1;
+    if (b.hasChildren && !a.hasChildren) return 1;
+    if (a.label > b.label) return 1;
+    if (a.label < b.label) return -1;
+    return 0;
+  });
+}
+
+export async function getAutomenu(source, validPaths) {
+  const tree = dirTree(source);
+  const menuData = buildMenuData(tree, source, validPaths);
+  
+  // Add home item with resolved href
+  const homeResolved = resolveHref('/', validPaths);
+  const fullMenuData = [
+    { label: 'Home', path: '', href: homeResolved.href, inactive: homeResolved.inactive, debug: homeResolved.debug, hasChildren: false, icon: `<span class="menu-icon">${HOME_ICON}</span>` },
+    ...menuData
+  ];
+  
+  // Embed the menu data as JSON for JavaScript to use
+  const menuDataScript = `<script type="application/json" id="menu-data">${JSON.stringify(fullMenuData)}</script>`;
+  
+  // Render the breadcrumb header (hidden by default, shown when navigating)
+  const breadcrumbHtml = `
+<div class="menu-breadcrumb" style="display: none;">
+  <button class="menu-back" title="Go back">←</button>
+  <button class="menu-home" title="Go to root">🏠</button>
+  <span class="menu-current-path"></span>
+</div>`;
 
-  /**
-   * example output:
-   * {
-   *   href:'Foo/Bar',
-   *   label:'Bar',
-   *   childMenuItems: [thisObject]
-   * }
-   */
+  // Render the initial menu (root level)
+  const menuHtml = renderMenuLevel(fullMenuData, 0);
+  
+  return `${menuDataScript}${breadcrumbHtml}<ul class="menu-level" data-level="0">${menuHtml}</ul>`;
+}
+
+function renderMenuLevel(items, level) {
+  return items.map(item => {
+    const hasChildrenClass = item.hasChildren ? ' has-children' : '';
+    const hasChildrenIndicator = item.hasChildren ? '<span class="menu-more">⋯</span>' : '';
+    const inactiveClass = item.inactive ? ' inactive' : '';
+    const debugText = item.debug ? ` [DEBUG: ${item.debug}]` : '';
+    
+    const labelHtml = item.href
+      ? `<a href="${item.href}" class="menu-label${inactiveClass}">${item.label}${debugText}</a>`
+      : `<span class="menu-label">${item.label}</span>`;
+    
+    return `
+<li class="menu-item${hasChildrenClass}" data-path="${item.path}">
+  <div class="menu-item-row">
+    ${item.icon}
+    ${labelHtml}
+    ${hasChildrenIndicator}
+  </div>
+</li>`;
+  }).join('');
 }
 
 function childSorter(a, b) {