@kenjura/ursa 0.82.0 → 0.84.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+# 0.84.0
+2026-05-08
+
+- Unified sticky headers are now standard
+
+# 0.83.0
+2026-05-07
+
+- **New `--promote-changelog=<file.md>` option** for the `generate` and `serve` commands. When supplied, the named markdown (or .mdx) file is staged into the source root for the duration of the build, so it is rendered by the normal Ursa pipeline and ends up in the output root as a sibling of the main `index.html`. The staged copy is removed after the build completes (or when the serve process exits via SIGINT/SIGTERM). If a file with the same basename already exists in the source root, no staging is performed and a warning is logged.
+- **Search UI fix**: clicking a search suggestion (or selecting one with Enter) now hides the search results dropdown immediately. Previously the dropdown could remain visible when navigation did not trigger a fresh page load (e.g. same-page anchor links, or restoration from the browser's back/forward cache). Also added a `pageshow` listener that hides results when the page is restored from bfcache.
+- **Search UI fully collapses after navigation**: clicking a search suggestion (in either the inline search dropdown or the search widget panel) now also closes the search widget panel and clears the search input, mirroring the effect of clicking the search icon a second time. The input is also cleared when the page is restored from the browser's back/forward cache.
 # 0.82.0
 2026-05-06
 

package/bin/ursa.js

@@ -5,6 +5,7 @@ import { hideBin } from 'yargs/helpers';
 import { generate } from '../src/jobs/generate.js';
 import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { stagePromotedChangelog, registerCleanupOnExit } from '../src/helper/promoteChangelog.js';
 
 // Get the directory where ursa is installed
 const __filename = fileURLToPath(import.meta.url);
@@ -48,6 +49,10 @@ yargs(hideBin(process.argv))
           describe: 'Ignore cached hashes and regenerate all files',
           type: 'boolean',
           default: false
+        })
+        .option('promote-changelog', {
+          describe: 'Path to a markdown file to render at the output root (sibling of index.html)',
+          type: 'string'
         });
     },
     async (argv) => {
@@ -57,6 +62,7 @@ yargs(hideBin(process.argv))
       const whitelist = argv.whitelist ? resolve(argv.whitelist) : null;
       const exclude = argv.exclude || null;
       const clean = argv.clean;
+      const promoteChangelog = argv['promote-changelog'] || null;
       
       console.log(`Generating site from ${source} to ${output} using meta from ${meta}`);
       if (whitelist) {
@@ -69,7 +75,9 @@ yargs(hideBin(process.argv))
         console.log(`Clean build: ignoring cached hashes`);
       }
       
+      let promoted = { stagedFile: null, cleanup: async () => {} };
       try {
+        promoted = await stagePromotedChangelog({ changelogPath: promoteChangelog, sourceDir: source });
         await generate({
           _source: source,
           _meta: meta,
@@ -82,6 +90,8 @@ yargs(hideBin(process.argv))
       } catch (error) {
         console.error('Error generating site:', error.message);
         process.exit(1);
+      } finally {
+        await promoted.cleanup();
       }
     }
   )
@@ -127,6 +137,10 @@ yargs(hideBin(process.argv))
           describe: 'Ignore cached hashes and regenerate all files',
           type: 'boolean',
           default: false
+        })
+        .option('promote-changelog', {
+          describe: 'Path to a markdown file to render at the output root (sibling of index.html)',
+          type: 'string'
         });
     },
     async (argv) => {
@@ -137,6 +151,7 @@ yargs(hideBin(process.argv))
       const whitelist = argv.whitelist ? resolve(argv.whitelist) : null;
       const exclude = argv.exclude || null;
       const clean = argv.clean;
+      const promoteChangelog = argv['promote-changelog'] || null;
       
       console.log(`Starting development server...`);
       console.log(`Source: ${source}`);
@@ -151,6 +166,8 @@ yargs(hideBin(process.argv))
       }
       
       try {
+        const promoted = await stagePromotedChangelog({ changelogPath: promoteChangelog, sourceDir: source });
+        registerCleanupOnExit(promoted.cleanup);
         const { serve } = await import('../src/serve.js');
         await serve({
           _source: source,

package/meta/templates/default-template/default.css

@@ -1264,4 +1264,40 @@ footer#site-footer {
     -webkit-text-size-adjust: 100%;
     text-size-adjust: 100%;
   }
+}
+
+
+/* sticky unified header */
+article#main-content {
+  h1, h2, h3 {
+    position: sticky;
+    z-index: 90;
+    margin: 0;
+
+    &.stuck {
+      background: var(--nav-top-bg);
+    }
+  }
+  h1 {
+    top: var(--global-nav-height);
+    height: 3rem;
+    line-height: 3rem;
+  }
+  h2 {
+    top: calc(var(--global-nav-height) + 3rem);
+    height: 2.25rem;
+    line-height: 2.25rem;
+  }
+  h3 {
+    top: calc(var(--global-nav-height) + 5.25rem);
+    height: 1.75rem;
+    line-height: 1.75rem;
+  }
+
+  /* Hide stuck h2/h3 — the breadcrumb on the stuck h1 carries their text.
+     Use visibility (not max-height/display) to preserve layout and avoid
+     the flicker loop where collapsing the heading un-sticks it. */
+  h2.stuck, h3.stuck {
+    visibility: hidden;
+  }
 }

package/meta/templates/default-template/search.js

@@ -590,6 +590,27 @@ class GlobalSearch {
   }
   
   navigateToResult(result) {
+    // Hide the results dropdown immediately. This handles cases where the
+    // navigation does not trigger a fresh page load (e.g. same-page anchor
+    // links, or restoration from the browser's back/forward cache).
+    this.hideResults();
+    // Also close the search widget panel (if any) so the search UI fully
+    // collapses, mirroring the effect of clicking the search icon again.
+    if (window.widgetManager && typeof window.widgetManager.close === 'function') {
+      try {
+        const side = window.widgetManager.getSide
+          ? window.widgetManager.getSide('search')
+          : undefined;
+        window.widgetManager.close(side);
+      } catch {
+        // ignore — best effort
+      }
+    }
+    // Clear the search input so the field is empty when the user reopens it.
+    if (this.searchInput) {
+      this.searchInput.value = '';
+      this.updateClearButtonVisibility();
+    }
     if (result.url) {
       window.location.href = result.url;
     } else if (result.path) {
@@ -601,4 +622,21 @@ class GlobalSearch {
 // Initialize when DOM is loaded
 document.addEventListener('DOMContentLoaded', () => {
   window.globalSearch = new GlobalSearch();
+});
+
+// Also hide search results if the page is restored from the browser's
+// back/forward cache (bfcache). Without this, the search dropdown can
+// appear "stuck" open after returning to a previous page.
+window.addEventListener('pageshow', () => {
+  if (window.globalSearch && typeof window.globalSearch.hideResults === 'function') {
+    window.globalSearch.hideResults();
+  }
+  // Also clear the search input on bfcache restore so the field doesn't
+  // appear pre-populated with the previous query.
+  if (window.globalSearch && window.globalSearch.searchInput) {
+    window.globalSearch.searchInput.value = '';
+    if (typeof window.globalSearch.updateClearButtonVisibility === 'function') {
+      window.globalSearch.updateClearButtonVisibility();
+    }
+  }
 });

package/meta/templates/default-template/widgets.js

@@ -464,6 +464,19 @@ class WidgetManager {
     item.appendChild(path);
     
     item.addEventListener('click', () => {
+      // Close the search widget panel before navigating, so it isn't left
+      // open when the new page loads (or when a same-page anchor link
+      // doesn't trigger a fresh page load at all).
+      const side = this.getSide('search');
+      // Clear the widget search input so the field is empty next time the
+      // user opens the search panel.
+      if (this._widgetSearchInput) {
+        this._widgetSearchInput.value = '';
+      }
+      if (this._widgetSearchResults) {
+        this._widgetSearchResults.innerHTML = '';
+      }
+      this.close(side);
       window.location.href = result.url || result.path;
     });
     

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.82.0",
+  "version": "0.84.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {

package/src/helper/__test__/promoteChangelog.test.js

@@ -0,0 +1,94 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { jest } from '@jest/globals';
+import { stagePromotedChangelog } from '../promoteChangelog.js';
+
+let tmpDir;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ursa-promote-changelog-'));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('stagePromotedChangelog', () => {
+  it('is a no-op when no changelogPath is provided', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    const result = await stagePromotedChangelog({ changelogPath: null, sourceDir });
+    expect(result.stagedFile).toBe(null);
+    const entries = await fs.readdir(sourceDir);
+    expect(entries).toEqual([]);
+  });
+
+  it('throws when the source file does not exist', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    await expect(
+      stagePromotedChangelog({
+        changelogPath: path.join(tmpDir, 'missing.md'),
+        sourceDir,
+      })
+    ).rejects.toThrow(/cannot read file/);
+  });
+
+  it('copies the file into the source root using its basename', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    const cl = path.join(tmpDir, 'CHANGELOG.md');
+    await fs.writeFile(cl, '# Hello\n');
+
+    const result = await stagePromotedChangelog({ changelogPath: cl, sourceDir });
+
+    expect(result.stagedFile).toBe(path.join(sourceDir, 'CHANGELOG.md'));
+    const staged = await fs.readFile(result.stagedFile, 'utf8');
+    expect(staged).toBe('# Hello\n');
+  });
+
+  it('cleanup removes the staged file', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    const cl = path.join(tmpDir, 'CHANGELOG.md');
+    await fs.writeFile(cl, '# Hello\n');
+
+    const result = await stagePromotedChangelog({ changelogPath: cl, sourceDir });
+    await result.cleanup();
+
+    await expect(fs.access(result.stagedFile)).rejects.toThrow();
+  });
+
+  it('cleanup is idempotent', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    const cl = path.join(tmpDir, 'CHANGELOG.md');
+    await fs.writeFile(cl, '# Hello\n');
+
+    const result = await stagePromotedChangelog({ changelogPath: cl, sourceDir });
+    await result.cleanup();
+    await expect(result.cleanup()).resolves.toBeUndefined();
+  });
+
+  it('refuses to clobber an existing file in the source root', async () => {
+    const sourceDir = path.join(tmpDir, 'src');
+    await fs.mkdir(sourceDir);
+    const existing = path.join(sourceDir, 'CHANGELOG.md');
+    await fs.writeFile(existing, '# Original\n');
+    const cl = path.join(tmpDir, 'CHANGELOG.md');
+    await fs.writeFile(cl, '# Promoted\n');
+
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const result = await stagePromotedChangelog({ changelogPath: cl, sourceDir });
+      expect(result.stagedFile).toBe(null);
+      // Existing file untouched
+      const content = await fs.readFile(existing, 'utf8');
+      expect(content).toBe('# Original\n');
+      expect(warn).toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});

package/src/helper/promoteChangelog.js

@@ -0,0 +1,107 @@
+/**
+ * Promote-changelog helper.
+ *
+ * Implements the `--promote-changelog=<file.md>` CLI option for `generate`
+ * and `serve`. The named markdown (or .mdx) file is staged into the source
+ * root before the build runs, so that it is rendered by the normal Ursa
+ * pipeline and ends up in the output root as a sibling of the main
+ * `index.html`. Once the build finishes (or the serve process exits) the
+ * staged copy is removed, leaving the source tree untouched.
+ *
+ * Behavior:
+ *   - If no `--promote-changelog` value is provided, this is a no-op.
+ *   - The staged filename is the basename of the supplied path (e.g.
+ *     `CHANGELOG.md` becomes `<source>/CHANGELOG.md`).
+ *   - If a file with the same basename already exists in the source root,
+ *     no staging is performed and the existing file is left in place. A
+ *     warning is logged so the user can resolve the conflict.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Stage a changelog file into the source root.
+ *
+ * @param {Object} args
+ * @param {string|null|undefined} args.changelogPath - Path supplied via --promote-changelog.
+ * @param {string} args.sourceDir - Resolved absolute path to the source directory.
+ * @returns {Promise<{ stagedFile: string|null, cleanup: () => Promise<void> }>}
+ */
+export async function stagePromotedChangelog({ changelogPath, sourceDir }) {
+  const noop = { stagedFile: null, cleanup: async () => {} };
+  if (!changelogPath) return noop;
+
+  const absolute = path.resolve(changelogPath);
+  let content;
+  try {
+    content = await fs.readFile(absolute, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `--promote-changelog: cannot read file at ${absolute}: ${err.message}`
+    );
+  }
+
+  const baseName = path.basename(absolute);
+  const stagedFile = path.join(sourceDir, baseName);
+
+  // Refuse to clobber an existing file in the source root.
+  let alreadyExists = false;
+  try {
+    await fs.access(stagedFile);
+    alreadyExists = true;
+  } catch {
+    // expected when the file does not exist
+  }
+
+  if (alreadyExists) {
+    console.warn(
+      `--promote-changelog: a file already exists at ${stagedFile}; leaving it in place.`
+    );
+    return noop;
+  }
+
+  await fs.writeFile(stagedFile, content);
+  console.log(`--promote-changelog: staged ${absolute} -> ${stagedFile}`);
+
+  let cleanedUp = false;
+  const cleanup = async () => {
+    if (cleanedUp) return;
+    cleanedUp = true;
+    try {
+      await fs.unlink(stagedFile);
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        console.warn(
+          `--promote-changelog: failed to remove staged file ${stagedFile}: ${err.message}`
+        );
+      }
+    }
+  };
+
+  return { stagedFile, cleanup };
+}
+
+/**
+ * Register process-exit handlers that invoke the given cleanup function.
+ * Used by long-running commands (serve, dev) so the staged file is removed
+ * even when the user stops the process with Ctrl-C.
+ *
+ * @param {() => Promise<void>} cleanup
+ */
+export function registerCleanupOnExit(cleanup) {
+  if (!cleanup) return;
+  let triggered = false;
+  const run = (exitCode) => {
+    if (triggered) return;
+    triggered = true;
+    Promise.resolve(cleanup())
+      .catch(() => {})
+      .finally(() => {
+        if (typeof exitCode === 'number') process.exit(exitCode);
+      });
+  };
+  process.once('exit', () => run());
+  process.once('SIGINT', () => run(130));
+  process.once('SIGTERM', () => run(143));
+}