tkeron 4.0.0-beta.8 → 4.0.0

package/docs/testing.md

@@ -0,0 +1,331 @@
+# Testing Tkeron Projects
+
+## Overview
+
+Tkeron provides a `getBuildResult()` function that lets you test your built projects programmatically. This is useful for verifying that your components, pre-rendering scripts, and build output work correctly.
+
+**Important:** These tests validate YOUR project's build output — not tkeron internals. You're testing that your HTML, components, and scripts produce the expected result after the build.
+
+## Setup
+
+Install tkeron as a dependency in your project:
+
+```bash
+bun add -d tkeron
+```
+
+## API
+
+```typescript
+import { getBuildResult, type BuildResult } from "tkeron";
+
+const result: BuildResult = await getBuildResult("./websrc");
+```
+
+### BuildResult
+
+`getBuildResult()` returns a `Record<string, FileInfo>` indexed by relative path:
+
+```typescript
+type BuildResult = Record<string, FileInfo>;
+
+interface FileInfo {
+  fileName: string; // "index.html"
+  filePath: string; // "styles" or "" for root files
+  path: string; // "styles/main.css" (the key)
+  type: string; // MIME type: "text/html", "text/css", etc.
+  size: number; // size in bytes
+  fileHash: string; // SHA-256 hash
+  getContentAsString?: () => string; // text files only
+  dom?: Document; // HTML files only - parsed DOM
+}
+```
+
+- `dom` is only present on `.html` files. It provides full DOM API: `querySelector()`, `getElementById()`, `querySelectorAll()`, etc.
+- `getContentAsString()` is only present on text files (html, css, js, json, txt, svg, xml, ts, mjs, cjs, md, map).
+- Binary files (images, fonts) only have metadata — no `dom` or `getContentAsString`.
+
+## Test Structure
+
+### Single Build with beforeAll
+
+**Always** build once and share the result across tests. This is:
+
+- Concurrent-safe (`bun test --concurrent`)
+- Efficient (1 build instead of N builds)
+- Reliable (no race conditions)
+
+```typescript
+import { describe, it, expect, beforeAll } from "bun:test";
+import { getBuildResult, type BuildResult } from "tkeron";
+import { join } from "path";
+
+describe("my project", () => {
+  const sourcePath = join(import.meta.dir, "src");
+  let result: BuildResult;
+
+  beforeAll(async () => {
+    result = await getBuildResult(sourcePath);
+  });
+
+  it("should generate index.html", () => {
+    expect(result?.["index.html"]).toBeDefined();
+  });
+});
+```
+
+**Never** call `getBuildResult()` inside each `it()` — this causes race conditions in concurrent mode.
+
+## Testing Patterns
+
+### 1. Verify File Existence
+
+Check that expected output files exist:
+
+```typescript
+it("should generate expected files", () => {
+  expect(result?.["index.html"]).toBeDefined();
+  expect(result?.["index.js"]).toBeDefined();
+  expect(result?.["styles/main.css"]).toBeDefined();
+});
+```
+
+### 2. Verify Element Existence (Always Check First)
+
+**Rule:** Always verify an element exists BEFORE checking its properties.
+
+```typescript
+// ✅ CORRECT: check existence first, then properties
+it("should have login button", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const button = dom?.querySelector("#login-button");
+  expect(button).toBeDefined();
+  expect(button!.textContent).toBe("Log In");
+});
+
+// ❌ WRONG: accessing properties without checking existence
+it("should have login button", () => {
+  const dom = result?.["index.html"]?.dom;
+  expect(dom!.querySelector("#login-button")!.textContent).toBe("Log In");
+});
+```
+
+### 3. Verify Bounded Content
+
+Test specific, short, predictable values — not full output strings.
+
+```typescript
+// ✅ GOOD: specific, bounded values
+it("should have correct title", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const title = dom?.querySelector("title");
+  expect(title).toBeDefined();
+  expect(title!.textContent).toBe("My App");
+});
+
+// ✅ GOOD: keyword presence in compiled JS
+it("should contain event handling logic", () => {
+  const js = result?.["index.js"]?.getContentAsString!();
+  expect(js).toContain("addEventListener");
+});
+
+// ❌ BAD: comparing full minified JS output (fragile, breaks on any optimization change)
+it("should match exact JS", () => {
+  const js = result?.["index.js"]?.getContentAsString!();
+  expect(js).toBe('var t=0,e=document.querySelector("button")...');
+});
+
+// ❌ BAD: comparing full HTML output
+it("should match exact HTML", () => {
+  const html = result?.["index.html"]?.getContentAsString!();
+  expect(html).toBe("<!doctype html><html>...");
+});
+```
+
+**Why bounded:** Build output changes with optimizations, minification, and bundling. Test the **meaning**, not the **exact format**.
+
+### 4. Verify DOM Elements (Specific Queries)
+
+Test specific elements that matter to your project:
+
+```typescript
+it("should have navigation with correct links", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const homeLink = dom?.querySelector('nav a[href="/"]');
+  expect(homeLink).toBeDefined();
+  expect(homeLink!.textContent).toBe("Home");
+
+  const aboutLink = dom?.querySelector('nav a[href="/about"]');
+  expect(aboutLink).toBeDefined();
+});
+
+it("should have user profile section", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const profile = dom?.querySelector("#user-profile");
+  expect(profile).toBeDefined();
+
+  const avatar = profile?.querySelector("img.avatar");
+  expect(avatar).toBeDefined();
+  expect(avatar!.getAttribute("alt")).toBe("User avatar");
+});
+```
+
+### 5. Verify Tkeron Transformations
+
+Test that tkeron's build features work correctly in your project:
+
+**Script injection (TypeScript → JavaScript):**
+
+```typescript
+it("should have compiled script in head", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const script = dom?.querySelector('script[type="module"]');
+  expect(script).toBeDefined();
+  expect(script!.getAttribute("src")).toBe("./index.js");
+  expect(script!.parentElement!.tagName).toBe("HEAD");
+});
+```
+
+**Component substitution (.com.html):**
+
+```typescript
+it("should have processed nav component", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  // The <nav-menu> tag should be replaced by its .com.html content
+  const nav = dom?.querySelector("nav");
+  expect(nav).toBeDefined();
+
+  const links = dom?.querySelectorAll("nav a");
+  expect(links).toBeDefined();
+  expect(links!.length).toBeGreaterThan(0);
+});
+```
+
+**TypeScript component (.com.ts):**
+
+```typescript
+it("should have dynamically generated list", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const list = dom?.querySelector("#item-list");
+  expect(list).toBeDefined();
+
+  const items = list?.querySelectorAll("li");
+  expect(items).toBeDefined();
+  expect(items!.length).toBe(5);
+});
+```
+
+**Pre-rendering (.pre.ts):**
+
+```typescript
+it("should have pre-rendered content", () => {
+  const dom = result?.["index.html"]?.dom;
+
+  const generated = dom?.querySelector("#generated-content");
+  expect(generated).toBeDefined();
+  expect(generated!.textContent).not.toBe("");
+});
+```
+
+### 6. Verify File Metadata
+
+```typescript
+it("should have correct metadata", () => {
+  expect(result?.["index.html"]?.type).toBe("text/html");
+  expect(result?.["index.html"]?.size).toBeGreaterThan(0);
+  expect(result?.["index.html"]?.fileHash).toBeDefined();
+});
+
+it("should not have DOM on non-HTML files", () => {
+  expect(result?.["index.js"]?.dom).toBeUndefined();
+});
+
+it("should have correct path info for nested files", () => {
+  expect(result?.["pages/about.html"]?.fileName).toBe("about.html");
+  expect(result?.["pages/about.html"]?.filePath).toBe("pages");
+});
+```
+
+## Complete Example
+
+Here's a complete test file for a tkeron project with components:
+
+```typescript
+import { describe, it, expect, beforeAll } from "bun:test";
+import { getBuildResult, type BuildResult } from "tkeron";
+import { join } from "path";
+
+describe("my-website build", () => {
+  const sourcePath = join(import.meta.dir, "websrc");
+  let result: BuildResult;
+
+  beforeAll(async () => {
+    result = await getBuildResult(sourcePath);
+  });
+
+  it("should generate expected files", () => {
+    expect(result?.["index.html"]).toBeDefined();
+    expect(result?.["index.js"]).toBeDefined();
+    expect(result?.["about.html"]).toBeDefined();
+  });
+
+  it("should have page title", () => {
+    const dom = result?.["index.html"]?.dom;
+
+    const title = dom?.querySelector("title");
+    expect(title).toBeDefined();
+    expect(title!.textContent).toBe("My Website");
+  });
+
+  it("should have navigation from component", () => {
+    const dom = result?.["index.html"]?.dom;
+
+    const nav = dom?.querySelector("nav");
+    expect(nav).toBeDefined();
+
+    const homeLink = dom?.querySelector('nav a[href="/"]');
+    expect(homeLink).toBeDefined();
+    expect(homeLink!.textContent).toBe("Home");
+  });
+
+  it("should have footer from component", () => {
+    const dom = result?.["index.html"]?.dom;
+
+    const footer = dom?.querySelector("footer");
+    expect(footer).toBeDefined();
+  });
+
+  it("should have compiled JavaScript", () => {
+    const js = result?.["index.js"]?.getContentAsString!();
+
+    expect(js).toBeDefined();
+    expect(js!.length).toBeGreaterThan(0);
+  });
+
+  it("should have script injected in head", () => {
+    const dom = result?.["index.html"]?.dom;
+
+    const script = dom?.querySelector('head script[type="module"]');
+    expect(script).toBeDefined();
+    expect(script!.getAttribute("src")).toBe("./index.js");
+  });
+});
+```
+
+## Rules Summary
+
+1. **Build once** with `beforeAll()` — never inside individual tests
+2. **Check existence first** — always `expect(element).toBeDefined()` before accessing properties
+3. **Use optional chaining** (`?.`) for safe property access on result entries
+4. **Test bounded content** — specific values, keywords, attributes; not full output strings
+5. **Test specific elements** — query for elements that matter to your project
+6. **Verify transformations** — components processed, scripts injected, pre-rendering applied
+7. **Don't test the parser** — you're testing your project, not tkeron internals
+8. **Concurrent-safe** — tests must work with `bun test --concurrent`

package/examples/basic_build/src/index.ts

@@ -1,10 +1,10 @@
 // Simple click counter
 let clickCount = 0;
 
-const button = document.querySelector('button') as HTMLButtonElement;
-const heading = document.querySelector('h1') as HTMLHeadingElement;
+const button = document.querySelector("button") as HTMLButtonElement;
+const heading = document.querySelector("h1") as HTMLHeadingElement;
 
-button.addEventListener('click', () => {
-    clickCount++;
-    heading.textContent = `Clicks: ${clickCount}`;
+button.addEventListener("click", () => {
+  clickCount++;
+  heading.textContent = `Clicks: ${clickCount}`;
 });

package/examples/with_assets/src/index.ts

@@ -1,10 +1,10 @@
 // Simple click counter
 let clickCount = 0;
 
-const button = document.querySelector('button') as HTMLButtonElement;
-const heading = document.querySelector('h1') as HTMLHeadingElement;
+const button = document.querySelector("button") as HTMLButtonElement;
+const heading = document.querySelector("h1") as HTMLHeadingElement;
 
-button.addEventListener('click', () => {
-    clickCount++;
-    heading.textContent = `Clicks: ${clickCount}`;
+button.addEventListener("click", () => {
+  clickCount++;
+  heading.textContent = `Clicks: ${clickCount}`;
 });

package/examples/with_com_html_priority/src/admin/admin-panel.com.html

@@ -1,4 +1,4 @@
-<div style="border: 3px solid #e74c3c; padding: 1rem; margin: 1rem 0;">
+<div style="border: 3px solid #e74c3c; padding: 1rem; margin: 1rem 0">
   <h4>Admin Panel</h4>
   <p>This component only exists in admin directory</p>
   <nested-stat></nested-stat>

package/examples/with_com_html_priority/src/admin/dashboard.html

@@ -1,18 +1,18 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Admin Dashboard</title>
-</head>
-<body>
-  <h1>Admin Dashboard</h1>
-  
-  <section>
-    <h2>Local Components Override Root</h2>
-    <site-header></site-header>
-    <info-box></info-box>
-    <admin-panel></admin-panel>
-  </section>
-</body>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Admin Dashboard</title>
+  </head>
+  <body>
+    <h1>Admin Dashboard</h1>
+
+    <section>
+      <h2>Local Components Override Root</h2>
+      <site-header></site-header>
+      <info-box></info-box>
+      <admin-panel></admin-panel>
+    </section>
+  </body>
 </html>

package/examples/with_com_html_priority/src/admin/nested-stat.com.html

@@ -1,4 +1,4 @@
-<div style="background: #f39c12; padding: 0.5rem; margin-top: 0.5rem;">
+<div style="background: #f39c12; padding: 0.5rem; margin-top: 0.5rem">
   <strong>Nested Stat Component</strong>
   <p>Total Users: 1,234 | Active: 567</p>
 </div>

package/examples/with_com_html_priority/src/admin/site-header.com.html

@@ -1,4 +1,4 @@
-<header style="background: #e74c3c; color: white; padding: 1rem;">
+<header style="background: #e74c3c; color: white; padding: 1rem">
   <h3>🔐 Admin Header (Local Override)</h3>
   <p>This header is from the admin directory - overrides root!</p>
 </header>

package/examples/with_com_html_priority/src/blog/comment-item.com.html

@@ -1,3 +1,3 @@
-<div style="background: #ecf0f1; padding: 0.5rem; margin: 0.5rem 0;">
+<div style="background: #ecf0f1; padding: 0.5rem; margin: 0.5rem 0">
   <strong>User123:</strong> Great article!
 </div>

package/examples/with_com_html_priority/src/blog/comment-section.com.html

@@ -1,4 +1,4 @@
-<div style="border: 2px solid #27ae60; padding: 1rem; margin: 1rem 0;">
+<div style="border: 2px solid #27ae60; padding: 1rem; margin: 1rem 0">
   <h4>Comments</h4>
   <p>This component is specific to the blog directory</p>
   <comment-item></comment-item>

package/examples/with_com_html_priority/src/blog/post.html

@@ -1,21 +1,24 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Blog Post</title>
-</head>
-<body>
-  <h1>Blog Post</h1>
-  
-  <site-header></site-header>
-  
-  <article>
-    <h2>Using Root Components</h2>
-    <info-box></info-box>
-    <p>This page uses components from the root directory since there are no local overrides.</p>
-    
-    <comment-section></comment-section>
-  </article>
-</body>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Blog Post</title>
+  </head>
+  <body>
+    <h1>Blog Post</h1>
+
+    <site-header></site-header>
+
+    <article>
+      <h2>Using Root Components</h2>
+      <info-box></info-box>
+      <p>
+        This page uses components from the root directory since there are no
+        local overrides.
+      </p>
+
+      <comment-section></comment-section>
+    </article>
+  </body>
 </html>

package/examples/with_com_html_priority/src/index.html

@@ -1,17 +1,17 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Component Priority - HTML Components</title>
-</head>
-<body>
-  <h1>HTML Component Priority Demo</h1>
-  
-  <section>
-    <h2>Root Level Components</h2>
-    <site-header></site-header>
-    <info-box></info-box>
-  </section>
-</body>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Component Priority - HTML Components</title>
+  </head>
+  <body>
+    <h1>HTML Component Priority Demo</h1>
+
+    <section>
+      <h2>Root Level Components</h2>
+      <site-header></site-header>
+      <info-box></info-box>
+    </section>
+  </body>
 </html>

package/examples/with_com_html_priority/src/info-box.com.html

@@ -1,4 +1,4 @@
-<div style="border: 2px solid #4a90e2; padding: 1rem; margin: 1rem 0;">
+<div style="border: 2px solid #4a90e2; padding: 1rem; margin: 1rem 0">
   <strong>Root Info Box</strong>
   <p>This is the default info box from root</p>
 </div>

package/examples/with_com_html_priority/src/site-header.com.html

@@ -1,4 +1,4 @@
-<header style="background: #4a90e2; color: white; padding: 1rem;">
+<header style="background: #4a90e2; color: white; padding: 1rem">
   <h3>Root Header Component</h3>
   <p>This header is from the root directory</p>
 </header>

package/examples/with_com_mixed_priority/src/dashboard/main.html

@@ -1,19 +1,19 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Dashboard - Mixed Priority</title>
-</head>
-<body>
-  <h1>Dashboard with Mixed Priorities</h1>
-  
-  <section>
-    <h2>Local Overrides and .com.ts Priority</h2>
-    <page-header></page-header>
-    <feature-card title="Dashboard Feature"></feature-card>
-    <stats-widget></stats-widget>
-    <footer-info></footer-info>
-  </section>
-</body>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Dashboard - Mixed Priority</title>
+  </head>
+  <body>
+    <h1>Dashboard with Mixed Priorities</h1>
+
+    <section>
+      <h2>Local Overrides and .com.ts Priority</h2>
+      <page-header></page-header>
+      <feature-card title="Dashboard Feature"></feature-card>
+      <stats-widget></stats-widget>
+      <footer-info></footer-info>
+    </section>
+  </body>
 </html>

package/examples/with_com_mixed_priority/src/dashboard/stats-widget.com.ts

@@ -1,7 +1,7 @@
 const stats = {
   users: 1523,
   revenue: 45230,
-  growth: 23.5
+  growth: 23.5,
 };
 
 com.innerHTML = `

package/examples/with_com_mixed_priority/src/footer-info.com.html

@@ -1,3 +1,5 @@
-<footer style="background: #34495e; color: white; padding: 1rem; text-align: center;">
+<footer
+  style="background: #34495e; color: white; padding: 1rem; text-align: center"
+>
   <p>© 2025 - Root Footer (HTML Component)</p>
 </footer>

package/examples/with_com_mixed_priority/src/index.html

@@ -1,18 +1,18 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Mixed Component Priority Demo</title>
-</head>
-<body>
-  <h1>Mixed Component Priority (.com.html + .com.ts)</h1>
-  
-  <section>
-    <h2>Root Level - Both Component Types</h2>
-    <page-header></page-header>
-    <feature-card title="Feature 1"></feature-card>
-    <footer-info></footer-info>
-  </section>
-</body>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Mixed Component Priority Demo</title>
+  </head>
+  <body>
+    <h1>Mixed Component Priority (.com.html + .com.ts)</h1>
+
+    <section>
+      <h2>Root Level - Both Component Types</h2>
+      <page-header></page-header>
+      <feature-card title="Feature 1"></feature-card>
+      <footer-info></footer-info>
+    </section>
+  </body>
 </html>

package/examples/with_com_mixed_priority/src/page-header.com.html

@@ -1,4 +1,11 @@
-<header style="background: linear-gradient(90deg, #667eea 0%, #764ba2 100%); color: white; padding: 2rem; text-align: center;">
+<header
+  style="
+    background: linear-gradient(90deg, #667eea 0%, #764ba2 100%);
+    color: white;
+    padding: 2rem;
+    text-align: center;
+  "
+>
   <h2>Root Header (HTML Component)</h2>
   <p>This is a static HTML component from root</p>
 </header>

package/examples/with_com_mixed_priority/src/settings/config.html

@@ -1,18 +1,18 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Settings - Priority Showcase</title>
-</head>
-<body>
-  <h1>Settings Page</h1>
-  
-  <section>
-    <h2>Both .com.ts and .com.html in Same Directory</h2>
-    <priority-test></priority-test>
-    <feature-card title="Settings Feature"></feature-card>
-    <footer-info></footer-info>
-  </section>
-</body>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Settings - Priority Showcase</title>
+  </head>
+  <body>
+    <h1>Settings Page</h1>
+
+    <section>
+      <h2>Both .com.ts and .com.html in Same Directory</h2>
+      <priority-test></priority-test>
+      <feature-card title="Settings Feature"></feature-card>
+      <footer-info></footer-info>
+    </section>
+  </body>
 </html>