@abreen/tada 1.4.1 → 1.5.0

package/init/content/index.md

@@ -18,9 +18,14 @@ if you won't use the `author` front matter field.
 See the [Markdown examples page](/markdown.html) for syntax examples.
 
 !!! note
-For more documentation, see the [GitHub page][github].
+For more documentation, see the [GitHub page](https://github.com/abreen/Tada).
+<% if (vars.testCoveragePercent) { %>
+- <%= vars.testCoveragePercent %>% of <%= page.toolName %>'s code is covered by
+  automated tests (unit tests, [Playwright](https://playwright.dev/) browser
+  tests, and functional, black-box tests which exercise functionality using the
+  CLI). See [the test coverage metrics](<%= vars.testCoverageUrl %>).
+- <%= page.toolName %>'s features and behavior are
+  [documented in Markdown](https://github.com/abreen/Tada/tree/main/spec) for
+  easy reading by people and LLMs.
+<% } %>
 !!!
-
-
-
-[github]: https://github.com/abreen/Tada

package/init/content/labs/00/index.md

@@ -4,7 +4,7 @@ title: Lab 0
 author: alex
 description: An example lab page for <%= site.title %>.
 
-In this lab, we'll explore the [`VowelCounter` program](./VowelCounter.html).
+In this lab, we'll explore the [`VowelCounter` program](./VowelCounter.java.html).
 
 ## Review questions
 

package/init/content/labs/01/SearchTreeDemo.java

@@ -0,0 +1,31 @@
+public class SearchTreeDemo {
+    static class Node {
+        String data;
+        Node left;
+        Node right;
+        Node parent; // @trace-ignore
+    }
+
+    static Node insert(Node node, Node parent, String val) {
+        if (node == null) {
+            Node n = new Node();
+            n.data = val;
+            n.parent = parent;
+            return n;
+        }
+        if (val.compareTo(node.data) < 0)
+            node.left = insert(node.left, node, val);
+        else
+            node.right = insert(node.right, node, val);
+        return node;
+    }
+
+    public static void main(String[] args) {
+        Node root = null;
+        root = insert(root, null, "fig");
+        root = insert(root, null, "cherry");
+        root = insert(root, null, "kiwi");
+        root = insert(root, null, "apple");
+        root = insert(root, null, "date");
+    }
+}

package/init/content/labs/01/TraceDemo.java

@@ -0,0 +1,22 @@
+public class TraceDemo {
+    private static int sum(int n) {
+        if (n <= 0) {
+            return 0;
+        }
+        return n + sum(n - 1);
+    }
+    public static void main(String[] args) {
+        int[] arr = new int[7];
+        for (int i = 0; i < arr.length; i++) {
+            int n = (int)Math.pow(2, i);
+            arr[i] = n;
+        }
+
+        int total = sum(4);
+
+        String str = "hello";
+        for (int i = 0; i < str.length(); i++) {
+            System.out.println(str.charAt(i));
+        }
+    }
+}

package/init/content/labs/01/index.md

@@ -0,0 +1,27 @@
+parent: /labs/index.html
+parentLabel: Labs
+title: Lab 1
+author: alex
+description: A lab page for <%= site.title %> demonstrating the trace feature.
+
+In this lab, we'll examine memory diagrams.
+
+## A simple trace
+
+A simple program with an array, recursion, and a string.
+
+<%= renderTrace('TraceDemo.java') %>
+
+## Binary search tree
+
+Building a binary search tree with parent references.
+
+!!! note
+The `@trace-ignore` hint (used in a comment next to the `parent` field,
+see [`SearchTreeDemo.java`](./SearchTreeDemo.java)) allows
+[d3-flextree](https://www.npmjs.com/package/d3-flextree) to visually arrange
+the nodes as a standard binary tree. Without the hint, the parent references
+confuse the algorithm and lead to a more awkward layout.
+!!!
+
+<%= renderTrace('SearchTreeDemo.java') %>

package/init/content/labs/index.md

@@ -7,3 +7,5 @@ to apply the concepts we learned in lecture to solve real-world problems and
 write full-length programs.
 
 0. [`VowelCounter` and user input](/labs/00/index.html)
+
+1. [Memory diagrams](/labs/01/index.html)

package/init/content/lectures/01/Rectangle.java

@@ -2,6 +2,8 @@
 ///
 /// Objects of this class may be mutated (changed after construction)
 /// by scaling using a _scale factor_ (a floating-point number between 0 and 1).
+///
+/// See [`rectangle.py`](./rectangle.py) for a Python version of this class.
 public class Rectangle {
     private int width;
     private int height;

package/init/content/lectures/01/index.md

@@ -23,7 +23,8 @@ you should see a result for page 2 of `lecture1.pdf`.
 
 * [`Rectangle.java`](./Rectangle.java) (an example of a code page)
 * [`demo.py`](./demo.py) (another example of a code page)
-* [`Pair.java`](./Pair.java) (an example literate Java page)
+* [`Pair.java`](./Pair.java.html) (an example literate Java page)
+  - [A direct link](./Pair.java) to the source code
 
 !!! note
 Syntax highlighting is controlled by the `codeLanguages` configuration object

package/init/content/lectures/01/rectangle.py

@@ -0,0 +1,45 @@
+class Rectangle:
+    """A rectangle with integer side lengths.
+
+    Objects may be mutated by scaling using a scale factor
+    (a float between 0 and 1).
+    """
+
+    def __init__(self, width: int, height: int):
+        self._set_width(width)
+        self._set_height(height)
+
+    def _set_width(self, new_width: int):
+        if new_width <= 0:
+            raise ValueError("width must be positive")
+        self._width = new_width
+
+    def _set_height(self, new_height: int):
+        if new_height <= 0:
+            raise ValueError("height must be positive")
+        self._height = new_height
+
+    @property
+    def width(self) -> int:
+        return self._width
+
+    @property
+    def height(self) -> int:
+        return self._height
+
+    @property
+    def area(self) -> int:
+        return self.width * self.height
+
+    def scale_horizontally(self, scale_factor: float):
+        self._check_scale_factor(scale_factor)
+        self._set_width(round(self.width * scale_factor))
+
+    def scale_vertically(self, scale_factor: float):
+        self._check_scale_factor(scale_factor)
+        self._set_height(round(self.height * scale_factor))
+
+    @staticmethod
+    def _check_scale_factor(scale_factor: float):
+        if scale_factor < 0 or scale_factor > 1:
+            raise ValueError("scale factor must be between zero and one")

package/init/content/lectures/02/_pr1.md

@@ -0,0 +1,5 @@
+## Problem 1 # The first example problem
+
+Here's the `_pr1.md` partial. From this partial we can use the page-level
+front matter fields from the page that includes us. The page that called
+`include()` has a title of: <%= page.title %>

package/init/content/lectures/02/index.md

@@ -0,0 +1,11 @@
+parentLabel: Lectures
+parent: /lectures/index.html
+title: Lecture 2
+description: An example lecture page demonstrating partials.
+author: alex
+
+Here is a page constructed from multiple partials.
+
+<%= include('_pr1.md') %>
+
+<%= include('subdir/_pr2.md') %>

package/init/content/lectures/02/subdir/_foobar.html

@@ -0,0 +1,3 @@
+<p>Here's an HTML partial in a subdirectory.</p>
+
+<p>Here's the title of the page including this partial: <%= page.title %></p>

package/init/content/lectures/02/subdir/_pr2.md

@@ -0,0 +1,6 @@
+## Problem 2 # The second example problem
+
+Here's the `_pr2.md` partial. If we use `include()` here, the path is resolved
+relative to this file, **not** the page or partial that included us.
+
+<%= include('_foobar.html') %>

package/init/content/lectures/index.md

@@ -23,3 +23,6 @@ and other relevant information.
 
 [Lecture 1](/lectures/01/index.html)
 :   Introduction, computation, models of a computer
+
+[Lecture 2](/lectures/02/index.html)
+:   Algorithms

package/init/content/markdown.md

@@ -307,6 +307,7 @@ Here are the steps to follow when you are ready to submit your work for
 this problem set.
 
 ...
+
 :::
 ```
 
@@ -328,6 +329,35 @@ Email the files you changed to the course staff.
 
 :::
 
+### Two-column layout
+
+Use
+
+```markdown
++++
+Content in the first column (on the left)...
++++
+Content in the second column (on the right)...
++++
+```
+
+to arrange Markdown content in two columns:
+
++++
+Here is a paragraph in the first column. It can contain any Markdown you want,
+including lists:
+1. One
+2. Two
+3. Three
++++
+Here's a paragraph in the second column. We'll use a code block on this side:
+```java
+static boolean isOdd(int n) {
+  return n % 2 == 1;
+}
+```
++++
+
 ---
 
 ## Additional features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abreen/tada",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "type": "module",
   "description": "A static site generator",
   "license": "MIT",
@@ -26,11 +26,14 @@
   "scripts": {
     "prepare": "husky && bun run scripts/check-deps.ts",
     "prepack": "bun run scripts/prepack.ts",
-    "init-example": "bun run bin/tada.ts init example --no-interactive",
     "lint": "eslint src/ build/ bin/",
     "typecheck": "tsc --noEmit",
     "test:functional": "python3 -m pip install -q -r functional_tests/requirements.txt && python3 -m pytest functional_tests/ -v -n auto --durations=10",
-    "test:all": "bun test && bun run test:functional"
+    "test:all": "bun test && bun run test:playwright && bun run test:functional",
+    "test:coverage": "rm -rf coverage/unit coverage/functional && bun test --coverage && TADA_COVERAGE=1 python3 -m pip install -q -r functional_tests/requirements.txt && TADA_COVERAGE=1 python3 -m pytest functional_tests/ -v -n auto --durations=10 && bun run scripts/coverage-report.ts",
+    "test:playwright": "bunx playwright test",
+    "init-example": "bun run bin/tada.ts init example --no-interactive",
+    "iew": "if [ -d example ]; then cd example; else bun run init-example && cd example; fi && ../bin/tada.ts watch"
   },
   "engines": {
     "bun": ">=1.0.0"
@@ -44,6 +47,8 @@
     "ajv": "^8.17.1",
     "chokidar": "^4.0.0",
     "culori": "^4.0.2",
+    "d3-flextree": "^2.1.2",
+    "d3-hierarchy": "^3.1.2",
     "fontkit": "^2.0.4",
     "front-matter": "^4.0.2",
     "java-parser": "^3.0.1",
@@ -71,14 +76,26 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.59.1",
+    "@saintedlama/lcov-parse": "^1.0.1",
     "@types/bun": "^1.3.10",
     "@types/culori": "^4.0.1",
+    "@types/d3-flextree": "^2.1.4",
+    "@types/d3-hierarchy": "^3.1.7",
     "@types/fontkit": "^2.0.8",
+    "@types/istanbul-lib-coverage": "^2.0.6",
+    "@types/istanbul-lib-instrument": "^1.7.8",
+    "@types/istanbul-lib-report": "^3.0.3",
+    "@types/istanbul-reports": "^3.0.4",
     "@types/lodash": "^4.17.24",
     "@types/markdown-it-container": "^4.0.0",
     "@types/ws": "^8.18.1",
     "eslint": "^10.0.3",
     "husky": "^9.1.7",
+    "istanbul-lib-coverage": "^3.2.2",
+    "istanbul-lib-instrument": "^6.0.3",
+    "istanbul-lib-report": "^3.0.1",
+    "istanbul-reports": "^3.2.0",
     "lint-staged": "^16.4.0",
     "prettier": "^3.6.2",
     "prettier-plugin-curly": "^0.4.1",

package/src/_base.scss

@@ -7,7 +7,7 @@
   --border-radius: 12px;
   --control-border-width: 2px;
   --label-border-width: 2px;
-  --focus-border-width: 3px;
+
   --table-padding: 12px;
   --details-padding: 12px;
   --section-padding: 64px;
@@ -104,7 +104,9 @@ pre {
   background: var(--bg2-color);
   border-radius: var(--mono-border-radius);
   line-height: var(--mono-line-height);
-  overflow: auto;
+  overflow-x: auto;
+  overflow-y: hidden;
+  overscroll-behavior-x: none;
   padding: var(--gap);
 
   code {
@@ -126,6 +128,15 @@ details summary {
   padding: var(--details-padding);
 }
 
+main details summary:focus {
+  outline: none;
+}
+
+main details:focus-within {
+  outline: 2px solid var(--theme-color);
+  outline-offset: 1px;
+}
+
 details .content {
   padding: 0 var(--details-padding) var(--details-padding)
     var(--details-padding);

package/src/_layout.scss

@@ -45,6 +45,10 @@ body.default .title-and-info {
   border-bottom: 1px solid var(--fg2-color);
 }
 
+body.default main > *:first-child {
+  margin-top: 0;
+}
+
 body.default main table,
 body.literate main table {
   width: 100%;
@@ -169,9 +173,6 @@ body.literate main table {
 
 .columns {
   display: grid;
-  grid-template-columns: max-content auto;
-  gap: 1rem;
-  &.split {
-    grid-template-columns: repeat(auto-fit, minmax(300px, auto));
-  }
+  grid-template-columns: 1fr 1fr;
+  gap: var(--gap);
 }

package/src/anchor/index.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from 'bun:test';
+import { JSDOM } from 'jsdom';
+import mount from './index';
+
+function create(html: string) {
+  const dom = new JSDOM(`<body>${html}</body>`);
+  return dom.window;
+}
+
+describe('anchor', () => {
+  test('wraps heading content in an anchor link', () => {
+    const win = create('<h2 id="intro">Introduction</h2>');
+    mount(win);
+
+    const h2 = win.document.querySelector('h2')!;
+    const link = h2.querySelector('a.heading-anchor')!;
+    expect(link).not.toBeNull();
+    expect(link.getAttribute('href')).toBe('#intro');
+    expect(link.textContent).toBe('Introduction');
+  });
+
+  test('sets title on anchor link', () => {
+    const win = create('<h3 id="setup">Setup</h3>');
+    mount(win);
+
+    const link = win.document.querySelector('a.heading-anchor')!;
+    expect(link.getAttribute('title')).toBe('Link to this heading');
+  });
+
+  test('skips headings without an id', () => {
+    const win = create('<h2>No ID</h2>');
+    mount(win);
+
+    const link = win.document.querySelector('a.heading-anchor');
+    expect(link).toBeNull();
+  });
+
+  test('handles multiple headings', () => {
+    const win = create('<h1 id="a">A</h1><h2 id="b">B</h2><h3>C</h3>');
+    mount(win);
+
+    const links = win.document.querySelectorAll('a.heading-anchor');
+    expect(links.length).toBe(2);
+    expect(links[0].getAttribute('href')).toBe('#a');
+    expect(links[1].getAttribute('href')).toBe('#b');
+  });
+
+  test('preserves child elements inside heading', () => {
+    const win = create('<h2 id="x"><em>Bold</em> text</h2>');
+    mount(win);
+
+    const link = win.document.querySelector('a.heading-anchor')!;
+    expect(link.querySelector('em')).not.toBeNull();
+    expect(link.textContent).toBe('Bold text');
+  });
+
+  test('does nothing when no headings exist', () => {
+    const win = create('<p>No headings here</p>');
+    mount(win);
+
+    const links = win.document.querySelectorAll('a.heading-anchor');
+    expect(links.length).toBe(0);
+  });
+});

package/src/code/index.test.ts

@@ -0,0 +1,71 @@
+import { beforeAll, describe, expect, test } from 'bun:test';
+import { JSDOM } from 'jsdom';
+import mount from './index';
+
+beforeAll(() => {
+  // jsdom does not provide ResizeObserver
+  if (typeof globalThis.ResizeObserver === 'undefined') {
+    (globalThis as Record<string, unknown>).ResizeObserver = class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    };
+  }
+});
+
+function create(html: string) {
+  const dom = new JSDOM(`<body class="code">${html}</body>`);
+  return dom.window;
+}
+
+describe('code', () => {
+  test('returns early when body does not have code class', async () => {
+    const dom = new JSDOM('<body><div>No code</div></body>');
+    await mount(dom.window);
+  });
+
+  test('returns early when no code-body or scrollbar', async () => {
+    const win = create('<div>Code page with no code body</div>');
+    await mount(win);
+  });
+
+  test('registers a copy event listener on code page', async () => {
+    const win = create(
+      '<div class="code-body"><div class="code-row"><code>hello</code></div></div>' +
+        '<div class="code-scrollbar"><div></div></div>',
+    );
+    await mount(win);
+
+    // Dispatch a copy event to exercise the listener (jsdom has limited
+    // ClipboardEvent support, so the handler exits early at getSelection)
+    const event = new win.Event('copy', { bubbles: true });
+    win.document.dispatchEvent(event);
+  });
+
+  test('sets up scrollbar syncing between code-body and scrollbar', async () => {
+    const win = create(
+      '<div class="code-body"><div class="code-row"><code>x</code></div></div>' +
+        '<div class="code-scrollbar"><div></div></div>',
+    );
+    await mount(win);
+
+    const codeBody = win.document.querySelector('.code-body') as HTMLElement;
+    const scrollbar = win.document.querySelector(
+      '.code-scrollbar',
+    ) as HTMLElement;
+    expect(codeBody).not.toBeNull();
+    expect(scrollbar).not.toBeNull();
+  });
+
+  test('handles download link when present', async () => {
+    const win = create(
+      '<div class="file-header"><a download="test.py" href="/test.py">Download</a></div>' +
+        '<div class="code-body"><div class="code-row"><code>x</code></div></div>' +
+        '<div class="code-scrollbar"><div></div></div>',
+    );
+    await mount(win);
+
+    const link = win.document.querySelector('a[download]');
+    expect(link).not.toBeNull();
+  });
+});

package/src/code/style.scss

@@ -10,6 +10,7 @@ body.code .file-header {
 body.code .code-body {
   background: var(--bg2-color);
   border-radius: var(--border-radius);
+  clip-path: inset(0 round var(--border-radius));
   display: grid;
   grid-template-columns: minmax(100%, max-content);
   overflow-x: auto;
@@ -38,6 +39,24 @@ body.code .code-body > pre {
   margin: 0;
 }
 
+body.code .code-body > pre:first-child {
+  *:first-child {
+    .line-number,
+    code {
+      padding-top: 0.5rem;
+    }
+  }
+}
+
+body.code .code-body > pre:last-child {
+  *:last-child {
+    .line-number,
+    code {
+      padding-bottom: 0.5rem;
+    }
+  }
+}
+
 body.code pre {
   display: block;
   padding: 0;
@@ -69,6 +88,10 @@ body.code .code-prose {
     padding: var(--gap) var(--gap) var(--gap)
       calc(var(--prose-indent, 0ch) - 0.2em);
 
+    *:first-of-type {
+      margin-top: 0;
+    }
+
     *:last-of-type {
       margin-bottom: 0;
     }

package/src/code.scss

@@ -1,7 +1,6 @@
 @use 'mixins' as *;
 
-body.code,
-body.literate {
+body.code {
   --code-gutter-width: 4rem;
 }
 
@@ -28,7 +27,6 @@ body.literate {
 }
 
 .line-number {
-  cursor: pointer;
   display: block;
   padding: 0 0.75em 0 0.75em;
   text-align: right;
@@ -42,6 +40,10 @@ body.literate {
   background: var(--bg2-color);
   border-right: 1px solid var(--fg2-color);
   margin-right: var(--gap);
+}
+
+a.line-number {
+  cursor: pointer;
 
   &:hover {
     color: var(--fg-color);