@abreen/tada 1.0.2 → 1.1.0

package/bin/validators.ts

@@ -0,0 +1,83 @@
+import type { SiteConfigInput, SiteVariables } from '../build/types.js';
+
+export function validateSymbol(value: string): string | null {
+  if (!value) {
+    return 'Symbol is required';
+  }
+  if (value.length > 5) {
+    return 'Symbol must be 5 characters or fewer';
+  }
+  if (!/^[A-Z0-9\- ]{1,5}$/.test(value)) {
+    return 'Symbol must contain only uppercase letters, digits, hyphens, and spaces';
+  }
+  return null;
+}
+
+export function validateColor(value: string): string | null {
+  if (!value) {
+    return 'Color is required';
+  }
+  try {
+    if (!Bun.color(value)) {
+      throw new Error();
+    }
+  } catch {
+    return 'Must be a valid CSS color, e.g. "tomato", "#c04040", or "hsl(195 70% 40%)"';
+  }
+  return null;
+}
+
+export function validateHue(value: string): string | null {
+  if (!value) {
+    return 'Hue is required';
+  }
+  const n = Number(String(value).replace(/deg$/, ''));
+  if (!Number.isInteger(n) || n < 0 || n > 360) {
+    return 'Must be an integer from 0 to 360, with or without "deg"';
+  }
+  return null;
+}
+
+export function validateUrl(value: string): string | null {
+  if (!value) {
+    return 'URL is required';
+  }
+  if (!/^https?:\/\/[-.:a-zA-Z0-9]+$/.test(value)) {
+    return 'Must be a valid URL like https://example.edu (no trailing slash or path)';
+  }
+  return null;
+}
+
+export function validateBasePath(value: string): string | null {
+  if (!/^\/[-a-zA-Z0-9]*$/.test(value)) {
+    return 'Must start with / and contain only letters, digits, and hyphens';
+  }
+  return null;
+}
+
+export function createSiteConfig({
+  title,
+  symbol,
+  themeColor,
+  tintHue,
+  tintAmount,
+  defaultTimeZone,
+  base,
+  basePath,
+  internalDomains,
+}: SiteConfigInput): SiteVariables {
+  return {
+    title,
+    symbol,
+    features: { search: true, code: true, favicon: true },
+    base,
+    basePath,
+    internalDomains,
+    defaultTimeZone,
+    codeLanguages: { java: 'java', py: 'python' },
+    themeColor,
+    tintHue: Number(tintHue),
+    tintAmount: Number(tintAmount),
+    vars: {},
+  };
+}

package/{webpack/apply-base-path-plugin.js → build/apply-base-path-plugin.ts}

@@ -1,13 +1,19 @@
-const { createApplyBasePath } = require('./utils/paths');
-const { makeLogger } = require('./log');
+import type MarkdownIt from 'markdown-it';
+import type Token from 'markdown-it/lib/token.mjs';
+import { createApplyBasePath } from './utils/paths.js';
+import { makeLogger } from './log.js';
+import type { SiteVariables } from './types.js';
 
 const log = makeLogger(__filename);
 
-module.exports = function externalLinks(md, siteVariables, options = {}) {
+export default function applyBasePathPlugin(
+  md: MarkdownIt,
+  siteVariables: SiteVariables,
+): void {
   const applyBasePath = createApplyBasePath(siteVariables);
   const rewriteCodeLinks = siteVariables.features?.code !== false;
 
-  function rewriteInternalHref(href) {
+  function rewriteInternalHref(href: string): string {
     const match = href.match(/^([^?#]*)(.*)$/);
     const pathname = match ? match[1] : href;
     const suffix = match ? match[2] : '';
@@ -15,7 +21,7 @@ module.exports = function externalLinks(md, siteVariables, options = {}) {
 
     if (rewriteCodeLinks) {
       // Rewrite code file links to .html links
-      for (const ext of Object.keys(siteVariables.codeLanguages)) {
+      for (const ext of Object.keys(siteVariables.codeLanguages ?? {})) {
         if (modifiedPath.endsWith(`.${ext}`)) {
           modifiedPath = modifiedPath.replace(
             new RegExp(`\\.${ext}$`),
@@ -29,9 +35,12 @@ module.exports = function externalLinks(md, siteVariables, options = {}) {
     return modifiedPath + suffix;
   }
 
-  function checkAndApplyBasePath(token) {
+  function checkAndApplyBasePath(token: Token): void {
     if (token.type === 'link_open') {
       const href = token.attrGet('href');
+      if (!href) {
+        return;
+      }
 
       if (href.startsWith('/')) {
         const modifiedHref = rewriteInternalHref(href);
@@ -75,4 +84,4 @@ module.exports = function externalLinks(md, siteVariables, options = {}) {
   md.core.ruler.push('apply_base_path', state => {
     state.tokens.map(checkAndApplyBasePath);
   });
-};
+}

package/build/bundle.ts

@@ -0,0 +1,117 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import _ from 'lodash';
+import * as sass from 'sass';
+import { getPackageDir, getProjectDir, getDistDir } from './utils/paths.js';
+import { deriveTheme } from './utils/derive-theme.js';
+import type { PluginBuilder } from 'bun';
+import type { SiteVariables } from './types.js';
+import timezones from '../src/timezone/timezones.json' with { type: 'json' };
+
+function renderThemeScss(siteVariables: SiteVariables): string {
+  const templatePath = path.join(getPackageDir(), 'templates/_theme.scss');
+  const template = fs.readFileSync(templatePath, 'utf-8');
+  const theme = deriveTheme(siteVariables.themeColor!);
+  const tintHue = siteVariables.tintHue ?? 20;
+  const tintAmount = siteVariables.tintAmount ?? 100;
+
+  const iconColor = `hsl(${tintHue}deg ${(8 * tintAmount) / 100}% 8%)`;
+  const iconColorHover = `hsl(${tintHue}deg ${(6 * tintAmount) / 100}% 60%)`;
+  const iconColorDark = `hsl(${tintHue}deg ${(20 * tintAmount) / 100}% 90%)`;
+  const iconColorHoverDark = `hsl(${tintHue}deg ${(6 * tintAmount) / 100}% 55%)`;
+  const iconColorTranslucentDark = `hsl(${tintHue}deg ${(85 * tintAmount) / 100}% 90%)`;
+
+  const rendered = _.template(template)({
+    ...theme,
+    tintHue,
+    tintAmount,
+    iconColor,
+    iconColorHover,
+    iconColorDark,
+    iconColorHoverDark,
+    iconColorTranslucentDark,
+  });
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tada-'));
+  const configDir = path.join(tmpDir, 'config');
+  fs.mkdirSync(configDir);
+  fs.writeFileSync(path.join(configDir, '_theme.scss'), rendered);
+
+  return tmpDir;
+}
+
+function createDefine(
+  siteVariables: SiteVariables,
+  isDev = false,
+): Record<string, string> {
+  return {
+    'window.siteVariables.base': JSON.stringify(siteVariables.base),
+    'window.siteVariables.basePath': JSON.stringify(siteVariables.basePath),
+    'window.siteVariables.titlePostfix': JSON.stringify(
+      siteVariables.titlePostfix,
+    ),
+    'window.siteVariables.defaultTimeZone': JSON.stringify(
+      siteVariables.defaultTimeZone,
+    ),
+    'window.siteVariables.timezones': JSON.stringify(timezones),
+    'window.IS_DEV': JSON.stringify(isDev),
+  };
+}
+
+function createScssPlugin(siteVariables: SiteVariables) {
+  const themeDir = renderThemeScss(siteVariables);
+
+  return {
+    name: 'scss',
+    setup(build: PluginBuilder) {
+      build.onLoad({ filter: /\.scss$/ }, args => {
+        const result = sass.compile(args.path, {
+          loadPaths: [themeDir, getProjectDir()],
+        });
+        return { contents: result.css, loader: 'css' as const };
+      });
+    },
+  };
+}
+
+export async function bundle(
+  siteVariables: SiteVariables,
+  { mode = 'development' }: { mode?: string } = {},
+): Promise<string[]> {
+  const packageDir = getPackageDir();
+  const distDir = getDistDir();
+  const isDev = mode === 'development';
+
+  const entrypoints = [
+    path.resolve(packageDir, 'src/index.ts'),
+    path.resolve(packageDir, 'src/critical.scss'),
+  ];
+
+  const result = await Bun.build({
+    entrypoints,
+    outdir: distDir,
+    naming: '[name].bundle.[ext]',
+    minify: mode === 'production',
+    sourcemap: isDev ? 'inline' : 'none',
+    define: createDefine(siteVariables, isDev),
+    external: ['*.woff2'],
+    plugins: [createScssPlugin(siteVariables)],
+  });
+
+  if (!result.success) {
+    const messages = result.logs
+      .filter(log => log.level === 'error')
+      .map(log => log.message || String(log));
+    throw new Error(`Bundle failed:\n${messages.join('\n')}`);
+  }
+
+  // Return the output filenames for asset tag injection
+  const assetFiles = result.outputs.map(output =>
+    path.relative(distDir, output.path).split(path.sep).join(path.posix.sep),
+  );
+
+  return assetFiles;
+}
+
+export { renderThemeScss, createDefine };

package/{webpack/code.test.js → build/code.test.ts}

@@ -1,9 +1,7 @@
-const { describe, expect, test, beforeAll } = require('bun:test');
-const { initHighlighter } = require('./utils/shiki-highlighter');
-const {
-  renderCodeWithComments,
-  extractJavaMethodToc,
-} = require('./utils/code');
+import { describe, expect, test, beforeAll } from 'bun:test';
+import { initHighlighter } from './utils/shiki-highlighter.js';
+import { renderCodeWithComments, extractJavaMethodToc } from './utils/code.js';
+import type { SiteVariables } from './types.js';
 
 beforeAll(async () => {
   await initHighlighter(['java', 'text', 'plaintext']);
@@ -148,9 +146,10 @@ public interface Greeter {
 describe('renderCodeWithComments', () => {
   test('renders build-time line rows for code segments', () => {
     const html = renderCodeWithComments('alpha\n\nbeta\n', 'java', {
+      base: '',
       basePath: '/',
       internalDomains: [],
-    });
+    } as SiteVariables);
 
     expect(html).toContain('<span class="code-row">');
     expect(html).toContain('id="L1" href="#L1"');

package/build/colors.ts

@@ -0,0 +1,25 @@
+import util from 'util';
+
+export const R = (str: TemplateStringsArray, ...args: unknown[]): string =>
+  util.styleText(['red'], String.raw(str, ...args));
+export const G = (str: TemplateStringsArray, ...args: unknown[]): string =>
+  util.styleText(['green'], String.raw(str, ...args));
+export const B = (str: TemplateStringsArray, ...args: unknown[]): string =>
+  util.styleText(['blue'], String.raw(str, ...args));
+export const Y = (str: TemplateStringsArray, ...args: unknown[]): string =>
+  util.styleText(['yellow'], String.raw(str, ...args));
+export const L = (str: TemplateStringsArray, ...args: unknown[]): string =>
+  util.styleText(['blackBright'], String.raw(str, ...args));
+export const P = (str: TemplateStringsArray, ...args: unknown[]): string =>
+  util.styleText(['magenta'], String.raw(str, ...args));
+export const I = (str: TemplateStringsArray, ...args: unknown[]): string =>
+  util.styleText(['italic', 'bold'], String.raw(str, ...args));
+
+export const Ri = (str: TemplateStringsArray, ...args: unknown[]): string =>
+  util.styleText(['inverse', 'red'], String.raw(str, ...args));
+export const Gi = (str: TemplateStringsArray, ...args: unknown[]): string =>
+  util.styleText(['inverse', 'green'], String.raw(str, ...args));
+export const Yi = (str: TemplateStringsArray, ...args: unknown[]): string =>
+  util.styleText(['inverse', 'yellow'], String.raw(str, ...args));
+export const Li = (str: TemplateStringsArray, ...args: unknown[]): string =>
+  util.styleText(['inverse', 'blackBright'], String.raw(str, ...args));

package/build/content-watch.ts

@@ -0,0 +1,107 @@
+import path from 'path';
+import type { SiteVariables } from './types.js';
+import { getContentDir, getBuildContentFiles } from './util.js';
+import {
+  compileTemplates,
+  getHtmlTemplatesDir,
+  getJsonDataDir,
+  JSON_DATA_FILES,
+} from './templates.js';
+import { getProjectDir } from './utils/paths.js';
+import { B } from './colors.js';
+import { makeLogger } from './log.js';
+
+const log = makeLogger(__filename);
+
+interface ChangeDetectionResult {
+  templateError: Error | null;
+  needsRestart: boolean;
+  changedContentFiles?: Set<string>;
+  templatesChanged?: boolean;
+}
+
+export class ContentChangeDetector {
+  private siteVariables: SiteVariables;
+  private siteConfigPath: string;
+  private lastSig: string | null;
+
+  constructor(siteVariables: SiteVariables) {
+    this.siteVariables = siteVariables;
+    this.siteConfigPath = path.resolve(getProjectDir(), 'site.dev.json');
+    this.lastSig = null;
+  }
+
+  detectChanges(modifiedFiles: Iterable<string>): ChangeDetectionResult {
+    const resolvedFiles = new Set(
+      [...(modifiedFiles || [])].map(filePath => path.resolve(filePath)),
+    );
+
+    const htmlTemplatesDir = getHtmlTemplatesDir();
+    const jsonDataDir = getJsonDataDir();
+
+    // Try to recompile templates
+    let templateError: Error | null = null;
+    try {
+      compileTemplates(this.siteVariables);
+    } catch (err) {
+      templateError = err as Error;
+    }
+
+    if (templateError) {
+      return { templateError, needsRestart: false };
+    }
+
+    const contentDir = getContentDir();
+    const normalizedContentDir = path.resolve(contentDir) + path.sep;
+    const normalizedHtmlDir = path.resolve(htmlTemplatesDir) + path.sep;
+    const buildContentFiles = getBuildContentFiles(
+      contentDir,
+      Object.keys(this.siteVariables.codeLanguages || {}),
+    );
+
+    // Detect structural changes (files added or deleted)
+    const sig = buildContentFiles.slice().sort().join('\0');
+    let needsRestart = false;
+    if (this.lastSig !== null && sig !== this.lastSig) {
+      needsRestart = true;
+    }
+    this.lastSig = sig;
+
+    const changedContentFiles = new Set(
+      [...resolvedFiles].filter(filePath =>
+        filePath.startsWith(normalizedContentDir),
+      ),
+    );
+
+    // Check if any HTML template or JSON data file changed
+    const jsonDataPaths = JSON_DATA_FILES.map(f =>
+      path.resolve(jsonDataDir, f),
+    );
+    const changedTemplatePaths = [...resolvedFiles].filter(
+      filePath =>
+        filePath === path.resolve(htmlTemplatesDir) ||
+        filePath.startsWith(normalizedHtmlDir) ||
+        jsonDataPaths.includes(filePath),
+    );
+    const templatesChanged = changedTemplatePaths.length > 0;
+
+    for (const filePath of changedTemplatePaths) {
+      log.event`${B`${path.basename(filePath)}`} changed, rebuilding`;
+    }
+
+    // Check if site config changed
+    const siteConfigChanged = resolvedFiles.has(
+      path.resolve(this.siteConfigPath),
+    );
+    if (siteConfigChanged) {
+      needsRestart = true;
+    }
+
+    return {
+      templateError: null,
+      needsRestart,
+      changedContentFiles,
+      templatesChanged,
+    };
+  }
+}

package/build/copy.ts

@@ -0,0 +1,118 @@
+import fs from 'fs';
+import path from 'path';
+import { makeLogger } from './log.js';
+import { B } from './colors.js';
+
+const log = makeLogger(__filename);
+
+interface CollectedFile {
+  abs: string;
+  rel: string;
+}
+
+function collectFiles(dir: string): CollectedFile[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true, recursive: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter(entry => entry.isFile())
+    .map(entry => {
+      const abs = path.join(entry.parentPath, entry.name);
+      const rel = path.relative(dir, abs);
+      return { abs, rel: rel.split(path.sep).join(path.posix.sep) };
+    });
+}
+
+export function copyPublicFiles(
+  publicDir: string,
+  distDir: string,
+): Set<string> {
+  const files = collectFiles(publicDir);
+  const publicRelPaths = new Set<string>();
+  for (const { abs, rel } of files) {
+    const dest = path.join(distDir, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(abs, dest);
+    publicRelPaths.add(rel);
+    log.info`Copying public file ${B`${rel}`}`;
+  }
+  return publicRelPaths;
+}
+
+export function copyContentAssets(
+  contentDir: string,
+  distDir: string,
+  processedExtensions: string[],
+  publicRelPaths: Set<string>,
+): Set<string> {
+  const processedExtSet = new Set(processedExtensions);
+  const files = collectFiles(contentDir);
+  const contentAssetRelPaths = new Set<string>();
+  const conflicts: string[] = [];
+  for (const { abs, rel } of files) {
+    const ext = path.extname(abs).slice(1).toLowerCase();
+    if (processedExtSet.has(ext)) {
+      continue;
+    }
+    contentAssetRelPaths.add(rel);
+    if (publicRelPaths && publicRelPaths.has(rel)) {
+      conflicts.push(rel);
+    }
+    const dest = path.join(distDir, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(abs, dest);
+  }
+  if (conflicts.length > 0) {
+    for (const rel of conflicts) {
+      log.error`content/${B`${rel}`} conflicts with public/${B`${rel}`}`;
+    }
+    const noun = conflicts.length === 1 ? 'file' : 'files';
+    throw new Error(
+      `${conflicts.length} ${noun} in content/ and public/ have the same path`,
+    );
+  }
+  return contentAssetRelPaths;
+}
+
+export function copyPublicFile(
+  publicDir: string,
+  distDir: string,
+  filePath: string,
+  contentAssetRelPaths?: Set<string>,
+): void {
+  const rel = path
+    .relative(publicDir, filePath)
+    .split(path.sep)
+    .join(path.posix.sep);
+  if (contentAssetRelPaths && contentAssetRelPaths.has(rel)) {
+    log.error`public/${B`${rel}`} conflicts with content/${B`${rel}`}`;
+    throw new Error(`public/${rel} and content/${rel} have the same path`);
+  }
+  const dest = path.join(distDir, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(filePath, dest);
+  log.info`Copying public file ${B`${rel}`}`;
+}
+
+export function copyContentFile(
+  contentDir: string,
+  distDir: string,
+  filePath: string,
+  publicRelPaths?: Set<string>,
+): void {
+  const rel = path
+    .relative(contentDir, filePath)
+    .split(path.sep)
+    .join(path.posix.sep);
+  if (publicRelPaths && publicRelPaths.has(rel)) {
+    log.error`content/${B`${rel}`} conflicts with public/${B`${rel}`}`;
+    throw new Error(`content/${rel} and public/${rel} have the same path`);
+  }
+  const dest = path.join(distDir, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(filePath, dest);
+  log.info`Copying content file ${B`${rel}`}`;
+}

package/{webpack/deflist-id-plugin.js → build/deflist-id-plugin.ts}

@@ -1,11 +1,12 @@
-const textToId = require('./text-to-id');
+import type MarkdownIt from 'markdown-it';
+import textToId from './text-to-id.js';
 
-module.exports = function deflistIdPlugin(md) {
+export default function deflistIdPlugin(md: MarkdownIt): void {
   md.core.ruler.push('deflist_id_injector', function (state) {
     const tokens = state.tokens;
-    const used = new Map();
+    const used = new Map<string, number>();
 
-    function slugify(str) {
+    function slugify(str: string): string {
       let slug = textToId(str);
 
       if (!slug) {
@@ -13,7 +14,7 @@ module.exports = function deflistIdPlugin(md) {
       }
 
       if (used.has(slug)) {
-        const n = used.get(slug) + 1;
+        const n = (used.get(slug) as number) + 1;
         used.set(slug, n);
         slug = `${slug}-${n}`;
       } else {
@@ -59,4 +60,4 @@ module.exports = function deflistIdPlugin(md) {
       i++;
     }
   });
-};
+}

package/{webpack/external-links-plugin.js → build/external-links-plugin.ts}

@@ -1,15 +1,24 @@
-const { makeLogger } = require('./log');
+import type MarkdownIt from 'markdown-it';
+import type Token from 'markdown-it/lib/token.mjs';
+import { makeLogger } from './log.js';
+import type { SiteVariables } from './types.js';
 
 const log = makeLogger(__filename);
 
-module.exports = function externalLinks(md, siteVariables) {
-  function addClass(token) {
+export default function externalLinks(
+  md: MarkdownIt,
+  siteVariables: SiteVariables,
+): void {
+  function addClass(token: Token): void {
     if (token.type === 'link_open') {
       const href = token.attrGet('href');
+      if (!href) {
+        return;
+      }
 
       if (href.match(/^https?:\/\/.*$/)) {
         const url = new URL(href);
-        if (!siteVariables.internalDomains.includes(url.host)) {
+        if (!siteVariables.internalDomains?.includes(url.host)) {
           const classAttr = token.attrGet('class');
           let newClassAttr;
 
@@ -34,4 +43,4 @@ module.exports = function externalLinks(md, siteVariables) {
   md.core.ruler.push('external_links', state => {
     state.tokens.map(addClass);
   });
-};
+}

package/build/features.ts

@@ -0,0 +1,11 @@
+import type { SiteVariables } from './types.js';
+
+export function isFeatureEnabled(
+  siteVariables: SiteVariables,
+  featureName: string,
+): boolean {
+  return (
+    siteVariables.features?.[featureName as keyof SiteVariables['features']] !==
+    false
+  );
+}