@abreen/tada 1.0.0

package/src/util.ts

@@ -0,0 +1,122 @@
+export function debounce(fn: Function, time: number) {
+  let timer: number;
+  return (...args: any[]) => {
+    window.clearTimeout(timer);
+    timer = window.setTimeout(() => {
+      fn.apply(null, args);
+    }, time);
+  };
+}
+
+export function removeClass(el: HTMLElement, className: string) {
+  el.classList.remove(className);
+  if (!el.className) {
+    el.removeAttribute('class');
+  }
+}
+
+export function getElement(
+  parent: Document | Element,
+  selector: string,
+): HTMLElement {
+  const el = parent.querySelector(selector);
+  if (!el) {
+    throw new Error(`no element matching "${selector}"`);
+  }
+  return el as HTMLElement;
+}
+
+export function applyBasePath(subPath: string): string {
+  if (!subPath.startsWith('/')) {
+    throw new Error('invalid internal path, must start with "/": ' + subPath);
+  }
+
+  let path = window.siteVariables.basePath || '/';
+  if (path.endsWith('/')) {
+    path = path.slice(0, -1);
+  }
+  return path + subPath;
+}
+
+export function scheduleTask(fn: () => void) {
+  if (typeof window.requestIdleCallback === 'function') {
+    window.requestIdleCallback(fn);
+  } else {
+    return setTimeout(fn, 0);
+  }
+}
+
+export function formatDuration(ms: number): string {
+  const sign = ms < 0 ? '-' : '';
+  const absMs = Math.abs(ms);
+
+  const roundTo = (val: number, decimals: number) => {
+    const factor = Math.pow(10, decimals);
+    return Math.round(val * factor) / factor;
+  };
+
+  const formatSecondsFromMs = (msVal: number): string => {
+    const sec = msVal / 1000;
+    // Ensure fixed width 8 for seconds:
+    // <10s => 1 + '.' + 5 + 's' = 8
+    // >=10s => 2 + '.' + 4 + 's' = 8
+    let decimals = sec < 10 ? 5 : 4;
+    let rounded = roundTo(sec, decimals);
+
+    // If rounding reaches 60, switch to minutes
+    if (rounded >= 60) {
+      return formatMinutesFromMs(msVal);
+    }
+
+    // If value was <10 but rounding crossed into >=10, drop one decimal to keep width 8
+    if (decimals === 5 && rounded >= 10) {
+      decimals = 4;
+      rounded = roundTo(sec, decimals);
+      if (rounded >= 60) {
+        return formatMinutesFromMs(msVal);
+      }
+    }
+
+    return `${rounded.toFixed(decimals)}s`;
+  };
+
+  const formatMinutesFromMs = (msVal: number): string => {
+    const totalSec = msVal / 1000;
+    let minutes = Math.floor(totalSec / 60);
+    const rawSeconds = totalSec - minutes * 60;
+
+    let decimals: number;
+    if (minutes < 10) {
+      decimals = rawSeconds < 10 ? 3 : 2;
+    } else {
+      decimals = rawSeconds < 10 ? 2 : 1;
+    }
+
+    let seconds = roundTo(rawSeconds, decimals);
+
+    if (seconds >= 60) {
+      minutes += 1;
+      // after carry, seconds is 0 and decimals depend on new minutes value
+      decimals = minutes < 10 ? 3 : 2;
+      seconds = 0;
+    }
+
+    return `${minutes}m${seconds.toFixed(decimals)}s`;
+  };
+
+  if (absMs < 1000) {
+    // 0.0000ms - 999.99ms
+    let decimals = absMs < 10 ? 4 : absMs < 100 ? 3 : 2;
+    let val = roundTo(absMs, decimals);
+    if (val >= 1000) {
+      return sign + formatSecondsFromMs(absMs);
+    }
+    return sign + `${val.toFixed(decimals)}ms`;
+  } else if (absMs < 60000) {
+    // 0.0000s - 59.9999s (variable decimals based on magnitude)
+    return sign + formatSecondsFromMs(absMs);
+  } else {
+    // Minutes + seconds with precision based on minute/second magnitude
+    return sign + formatMinutesFromMs(absMs);
+  }
+}

package/templates/_author.html

@@ -0,0 +1,27 @@
+<aside class="author">
+  Written by
+  <% if (page.author.url) { %>
+  <a href="<%= applyBasePath(page.author.url) %>">
+  <% } %>
+  <span class="text"><%= page.author.name %></span>
+  <% if (page.author.avatar) { %>
+  <img
+    width="32"
+    height="32"
+    src="<%= applyBasePath(page.author.avatar) %>"
+    alt="Picture of <%= page.author.name %>"
+    class="avatar"
+  />
+  <% } else { %>
+  <img
+    width="32"
+    height="32"
+    src="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='32' height='32'><rect width='32' height='32'/></svg>"
+    alt=""
+    class="avatar"
+  />
+  <% } %>
+  <% if (page.author.url) { %>
+  </a>
+  <% } %>
+</aside>

package/templates/_bottom.html

@@ -0,0 +1,3 @@
+    </div>
+  </body>
+</html>

package/templates/_download.html

@@ -0,0 +1 @@
+<a class="button" href="<%= page.codeFilePath %>" download="<%= page.downloadName %>" data-pagefind-ignore>Download</a>

package/templates/_heading.html

@@ -0,0 +1,19 @@
+<div class="title-and-info" data-pagefind-body>
+  <% if (page.parent) { %>
+  <a class="breadcrumb" href="<%= applyBasePath(page.parent) %>" data-pagefind-ignore><%= page.parentLabel %></a>
+  <% } %>
+  <h1 data-pagefind-weight="10"><%= page.titleHtml %></h1>
+
+  <div class="info" data-pagefind-ignore>
+    <% if (page.published) { %>
+    <div class="publish-date">
+      <time datetime="<%= isoDate(page.published) %>">
+        <%= readableDate(page.published) %>
+      </time>
+    </div>
+    <% } %>
+    <% if (page.author) { %>
+      <%= render('_author.html') %>
+    <% } %>
+  </div>
+</div>

package/templates/_nav.html

@@ -0,0 +1,18 @@
+<nav>
+<% json('nav.json').forEach(function(section) { %>
+  <div>
+    <p><%= section.title %></p>
+    <ul>
+      <% section.links.forEach(function(link) { %>
+        <li>
+          <a
+            class="<%= cx({disabled: link.disabled, external: link.external}) %>"
+            <% if (!link.disabled) { %>href="<%= link.internal ? applyBasePath(link.internal) : link.external %>"<% } %>
+          >
+            <%= link.text %></a>
+        </li>
+      <% }) %>
+    </ul>
+  </div>
+<% }) %>
+</nav>

package/templates/_theme.scss

@@ -0,0 +1,97 @@
+:root {
+  --theme-hue: <%= themeHue %>deg;
+  --theme-saturation: <%= themeSaturation %>%;
+  --theme-lightness: <%= themeLightness %>%;
+  --theme-color: hsl(
+    var(--theme-hue) var(--theme-saturation) var(--theme-lightness)
+  );
+  --theme-color-text: hsl(
+    var(--theme-hue) clamp(30%, var(--theme-saturation), 70%)
+      clamp(25%, var(--theme-lightness), 42%)
+  );
+
+  // Background & foreground color tint
+  --tint-hue: <%= tintHue %>deg;
+  --tint-amount: <%= tintAmount / 100 %>;
+
+  --link-active-color: #000;
+
+  --warning-bg-color: hsl(36 95% 70%);
+  --note-bg-color: hsl(209 95% 75%);
+
+  // Main foreground color (the color of most text)
+  --fg-color: hsl(var(--tint-hue) calc(8% * var(--tint-amount)) 8%);
+  --fg-color-translucent: hsl(
+    var(--tint-hue) calc(70% * var(--tint-amount)) 8% / 33%
+  );
+
+  // Secondary foreground color (lighter)
+  --fg2-color: hsl(var(--tint-hue) calc(6% * var(--tint-amount)) 45%);
+
+  // Main background color (the color of the page background)
+  --bg-color: hsl(var(--tint-hue) calc(5% * var(--tint-amount)) 97%);
+  --bg-color-translucent: hsl(
+    var(--tint-hue) calc(30% * var(--tint-amount)) 95% / 66%
+  );
+
+  // Secondary background color (lighter)
+  --bg2-color: hsl(var(--tint-hue) calc(12% * var(--tint-amount)) 92%);
+  --bg2-color-translucent: hsl(
+    var(--tint-hue) calc(12% * var(--tint-amount)) 92% / 66%
+  );
+
+  --box-shadow: 0 2px 9px
+    hsl(var(--tint-hue) calc(85% * var(--tint-amount)) 10% / 25%);
+  --backdrop-filter: blur(10px);
+
+  --font:
+    'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica,
+    Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
+  --heading-font: var(--font);
+  --mono-font: 'Google Sans Code', Consolas, Courier, monospace;
+
+  --font-size: 16px;
+  --font-size-smaller: 15px;
+  --font-size-small: 13px;
+
+  --font-weight: 400;
+  --line-height: 1.7;
+
+  // Use em units to specify a size relative to normal body text
+  --mono-font-size: 0.94em;
+  --mono-line-height: 1.5;
+  --mono-border-radius: 0.375em;
+
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --theme-color-text: hsl(
+      var(--theme-hue) clamp(30%, var(--theme-saturation), 70%)
+        clamp(50%, calc(var(--theme-lightness) + 15%), 80%)
+    );
+
+    --fg-color: hsl(var(--tint-hue) calc(10% * var(--tint-amount)) 92%);
+    --fg-color-translucent: hsl(
+      var(--tint-hue) calc(85% * var(--tint-amount)) 90% / 33%
+    );
+    --fg2-color: hsl(var(--tint-hue) calc(6% * var(--tint-amount)) 60%);
+    --bg-color: hsl(var(--tint-hue) calc(3% * var(--tint-amount)) 5%);
+    --bg-color-translucent: hsl(
+      var(--tint-hue) calc(15% * var(--tint-amount)) 10% / 66%
+    );
+    --bg2-color: hsl(var(--tint-hue) calc(12% * var(--tint-amount)) 12%);
+    --bg2-color-translucent: hsl(
+      var(--tint-hue) calc(12% * var(--tint-amount)) 12% / 66%
+    );
+
+    --box-shadow: 0 3px 8px
+      hsl(var(--tint-hue) calc(33% * var(--tint-amount)) 8% / 70%);
+
+    --link-active-color: #fff;
+
+    --warning-bg-color: hsl(36 77% 27%);
+    --note-bg-color: hsl(209 90% 25%);
+  }
+}

package/templates/_top.html

@@ -0,0 +1,87 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <% if (site.features.favicon) { %>
+    <link rel="icon" href="<%= applyBasePath('/favicon.ico') %>" sizes="any" />
+    <link rel="icon" type="image/svg+xml" href="<%= applyBasePath('/favicon.svg') %>" />
+    <link rel="icon" type="image/png" sizes="512x512" href="<%= applyBasePath('/favicon-512.png') %>" />
+    <link rel="icon" type="image/png" sizes="256x256" href="<%= applyBasePath('/favicon-256.png') %>" />
+    <link rel="icon" type="image/png" sizes="192x192" href="<%= applyBasePath('/favicon-192.png') %>" />
+    <link rel="icon" type="image/png" sizes="128x128" href="<%= applyBasePath('/favicon-128.png') %>" />
+    <link rel="icon" type="image/png" sizes="64x64" href="<%= applyBasePath('/favicon-64.png') %>" />
+    <link rel="icon" type="image/png" sizes="48x48" href="<%= applyBasePath('/favicon-48.png') %>" />
+    <link rel="icon" type="image/png" sizes="32x32" href="<%= applyBasePath('/favicon-32.png') %>" />
+    <link rel="icon" type="image/png" sizes="16x16" href="<%= applyBasePath('/favicon-16.png') %>" />
+    <link rel="apple-touch-icon" sizes="512x512" href="<%= applyBasePath('/favicon-512.png') %>" />
+    <link rel="apple-touch-icon" sizes="256x256" href="<%= applyBasePath('/favicon-256.png') %>" />
+    <link rel="manifest" href="<%= applyBasePath('/manifest.json') %>" />
+    <meta name="apple-mobile-web-app-title" content="<%= site.symbol %>">
+    <meta name="mobile-web-app-capable" content="yes">
+    <% } %>
+    <meta charset="UTF-8" />
+    <meta http-equiv="cache-control" content="no-cache" />
+    <meta http-equiv="expires" content="0" />
+    <meta http-equiv="pragma" content="no-cache" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <% if (page.description) { %>
+    <meta name="description" content="<%= page.description %>" />
+    <% } %>
+    <meta property="og:title" content="<%= page.title %>" />
+    <% if (page.author) { %>
+    <meta name="author" content="<%= page.author.name %>" />
+    <meta property="og:author" content="<%= page.author.name %>" />
+    <% } %>
+    <title><%= page.title %><%= site.titlePostfix %></title>
+    <script type="speculationrules">
+    {
+      "prerender": [{
+        "where": {
+          "href_matches": "<%= applyBasePath('/') %>*"
+        },
+        "eagerness": "moderate"
+      }]
+    }
+  </script>
+  <noscript><style>
+    .question-a-body:not([data-revealed]) > * { color: unset; background-color: unset; }
+    .question-a-body:not([data-revealed]) > * * { color: unset; background-color: unset; }
+    .question-a-body::after { display: none; }
+    .question-a-body { cursor: unset; }
+  </style></noscript>
+  </head>
+
+  <body class="<%= page.template %><% if (page.tocHtml) { %> toc-is-active<% } %>">
+    <header data-pagefind-ignore>
+      <details>
+        <summary aria-label="Toggle site navigation">
+          <span class="logo" aria-hidden="true"><%= site.symbol %></span>
+          <span class="site-title" aria-hidden="true"><%= site.title %></span>
+          <div id="to-top-container" class="to-top-container"></div>
+          <% if (site.features.search) { %>
+          <div class="search-controls">
+            <input type="search" class="search quick-search"
+                   autocomplete="off" name="quick-search"
+                   placeholder="Search"
+                   role="combobox"
+                   aria-haspopup="listbox"
+                   aria-autocomplete="list"
+                   aria-expanded="false"
+                   aria-controls="quick-search-results"
+                   disabled />
+            <script>document.currentScript.previousElementSibling.disabled=false;</script>
+            <% if (site.features.search) { %>
+            <div class="results-container" role="region"
+                 aria-label="Search results"
+                 aria-live="polite" aria-hidden="true" inert>
+              <div class="results" style="display:none"></div>
+            </div>
+            <% } %>
+          </div>
+          <% } %>
+        </summary>
+        <div class="content">
+          <%= render('_nav.html') %>
+        </div>
+      </details>
+    </header>
+    <div class="container">

package/templates/authors.schema.json

@@ -0,0 +1,13 @@
+{
+  "type": "object",
+  "additionalProperties": {
+    "type": "object",
+    "required": ["name", "avatar"],
+    "properties": {
+      "name": { "type": "string" },
+      "avatar": { "type": "string", "pattern": "^\\/[-a-zA-Z0-9_./#]*$" },
+      "url": { "type": "string", "pattern": "^\\/[-a-zA-Z0-9_./#]*$" }
+    },
+    "additionalProperties": false
+  }
+}

package/templates/code.html

@@ -0,0 +1,31 @@
+<%= render('_top.html') %>
+
+<div class="main-content">
+  <main class="body" data-pagefind-body>
+    <div class="file-header">
+      <h1 data-pagefind-weight="10"><%= page.titleHtml %></h1>
+      <%= render('_download.html') %>
+    </div>
+    <div class="code-body">
+      <%= content %>
+    </div>
+    <div class="code-scrollbar" aria-hidden="true">
+      <div></div>
+    </div>
+    <% if (page.tocItems && page.tocItems.length > 0) { %>
+    <div class="code-search-index" aria-hidden="true" inert>
+      <% page.tocItems.forEach(function(item) { %>
+      <section>
+        <h2 id="L<%= item.line %>"><%= item.name %></h2>
+        <p><%= item.label %> defined at line <%= item.line %>.</p>
+      </section>
+      <% }); %>
+    </div>
+    <% } %>
+  </main>
+  <% if (page.tocHtml) { %>
+  <nav class="toc"><%= page.tocHtml %></nav>
+  <% } %>
+</div>
+
+<%= render('_bottom.html') %>

package/templates/default.html

@@ -0,0 +1,13 @@
+<%= render('_top.html') %>
+
+<div class="main-content">
+  <%= render('_heading.html') %>
+  <main class="body" data-pagefind-body>
+    <%= content %>
+  </main>
+  <% if (page.toc && page.tocHtml) { %>
+  <nav class="toc"><%= page.tocHtml %></nav>
+  <% } %>
+</div>
+
+<%= render('_bottom.html') %>

package/templates/literate.html

@@ -0,0 +1,16 @@
+<%= render('_top.html') %>
+
+<div class="main-content">
+  <%= render('_heading.html') %>
+  <main class="body" data-pagefind-body>
+    <div class="file-header">
+      <code><%= page.downloadName %></code><%= render('_download.html') %>
+    </div>
+    <%= content %>
+  </main>
+  <% if (page.toc && page.tocHtml) { %>
+  <nav class="toc"><%= page.tocHtml %></nav>
+  <% } %>
+</div>
+
+<%= render('_bottom.html') %>

package/templates/nav.schema.json

@@ -0,0 +1,27 @@
+{
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["title", "links"],
+    "properties": {
+      "title": { "type": "string" },
+      "links": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": ["text"],
+          "properties": {
+            "text": { "type": "string" },
+            "internal": { "type": "string", "pattern": "^\\/.*$" },
+            "external": { "type": "string", "pattern": "^https?:\\/\\/.*$" },
+            "disabled": { "type": "boolean" },
+            "keywords": { "type": "array", "items": { "type": "string" } }
+          },
+          "oneOf": [{ "required": ["internal"] }, { "required": ["external"] }],
+          "additionalProperties": false
+        }
+      }
+    },
+    "additionalProperties": false
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "@tsconfig/node23/tsconfig.json",
+  "compilerOptions": {
+    "target": "ES6",
+    "lib": ["es2024", "dom"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "outDir": "./dist/",
+    "resolveJsonModule": true,
+    "strict": true,
+    "noUnusedLocals": true
+  },
+  "include": ["src", "types"],
+  "exclude": ["node_modules", "**/*.spec.ts", "**/*.test.ts"]
+}

package/types/dev.ts

@@ -0,0 +1,3 @@
+interface Window {
+  IS_DEV: boolean | undefined;
+}

package/types/sass.d.ts

@@ -0,0 +1 @@
+declare module '*.scss';

package/types/site-variables.d.ts

@@ -0,0 +1,16 @@
+interface TimezoneDef {
+  value: string;
+  label: string;
+  abbreviation: string;
+  offsetMinutes?: number;
+}
+
+interface Window {
+  siteVariables: {
+    base: string;
+    basePath: string;
+    titlePostfix?: string;
+    defaultTimeZone: string;
+    timezones: TimezoneDef[];
+  };
+}

package/webpack/apply-base-path-plugin.js

@@ -0,0 +1,78 @@
+const { createApplyBasePath } = require('./utils/paths');
+const { makeLogger } = require('./log');
+
+const log = makeLogger(__filename);
+
+module.exports = function externalLinks(md, siteVariables, options = {}) {
+  const applyBasePath = createApplyBasePath(siteVariables);
+  const rewriteCodeLinks = siteVariables.features?.code !== false;
+
+  function rewriteInternalHref(href) {
+    const match = href.match(/^([^?#]*)(.*)$/);
+    const pathname = match ? match[1] : href;
+    const suffix = match ? match[2] : '';
+    let modifiedPath = pathname;
+
+    if (rewriteCodeLinks) {
+      // Rewrite code file links to .html links
+      for (const ext of Object.keys(siteVariables.codeLanguages)) {
+        if (modifiedPath.endsWith(`.${ext}`)) {
+          modifiedPath = modifiedPath.replace(
+            new RegExp(`\\.${ext}$`),
+            '.html',
+          );
+          break;
+        }
+      }
+    }
+
+    return modifiedPath + suffix;
+  }
+
+  function checkAndApplyBasePath(token) {
+    if (token.type === 'link_open') {
+      const href = token.attrGet('href');
+
+      if (href.startsWith('/')) {
+        const modifiedHref = rewriteInternalHref(href);
+        const afterApply = applyBasePath(modifiedHref);
+        log.debug`Applying base path: ${href} -> ${afterApply}`;
+        token.attrSet('href', afterApply);
+      } else if (
+        !href.startsWith('#') &&
+        !href.startsWith('//') &&
+        !/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(href)
+      ) {
+        // Relative link: only rewrite code extensions, don't apply base path
+        const modifiedHref = rewriteInternalHref(href);
+        if (modifiedHref !== href) {
+          log.debug`Rewriting internal link: ${href} -> ${modifiedHref}`;
+          token.attrSet('href', modifiedHref);
+        }
+      }
+    } else if (token.type === 'image') {
+      const src = token.attrGet('src');
+      if (src && src.startsWith('/')) {
+        const afterApply = applyBasePath(src);
+        log.debug`Applying base path to image: ${src} -> ${afterApply}`;
+        token.attrSet('src', afterApply);
+      }
+    } else if (token.type === 'html_block' || token.type === 'html_inline') {
+      token.content = token.content.replace(
+        /(<img\b[^>]*\bsrc=")(\/)([^"]*")/g,
+        (match, prefix, slash, rest) => {
+          const src = slash + rest.slice(0, -1);
+          const afterApply = applyBasePath(src);
+          log.debug`Applying base path to img tag src: ${src} -> ${afterApply}`;
+          return prefix + afterApply + '"';
+        },
+      );
+    }
+
+    token.children?.map(checkAndApplyBasePath);
+  }
+
+  md.core.ruler.push('apply_base_path', state => {
+    state.tokens.map(checkAndApplyBasePath);
+  });
+};