@devansharora18/tardisjs 0.0.7 → 0.0.9

package/README.md

@@ -0,0 +1,199 @@
+# tardisjs
+
+**Smaller on the outside.** A blueprint-first frontend framework that compiles `.tardis` files to vanilla JavaScript.
+
+## Quick Start
+
+```bash
+npx create-tardis-app my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Or initialize in an existing directory:
+
+```bash
+npx tardis init
+npx tardis dev
+```
+
+## What It Looks Like
+
+```
+blueprint Counter {
+  state {
+    count: number = 0
+  }
+  methods {
+    increment: () => $update(state.count, state.count + 1)
+    decrement: () => $update(state.count, state.count - 1)
+    reset: () => $update(state.count, 0)
+  }
+  style(tailwind) {
+    value: "text-6xl font-bold text-center"
+    actions: "flex gap-4 justify-center mt-8"
+    btn: "rounded-lg bg-cyan-400 px-5 py-2 text-black font-medium"
+  }
+  ui {
+    <main>
+      <p class={"value"}>{state.count}</p>
+      <div class={"actions"}>
+        <button class={"btn"} @click={methods.decrement}>-1</button>
+        <button class={"btn"} @click={methods.increment}>+1</button>
+        <button class={"btn"} @click={methods.reset}>Reset</button>
+      </div>
+    </main>
+  }
+}
+```
+
+## Features
+
+- **~5KB runtime** — ships minimal code to the browser
+- **No virtual DOM** — direct DOM updates with Proxy-based reactivity
+- **Blueprint syntax** — structured DSL with props, state, computed, methods, events, styles, and UI
+- **Compiler-driven** — lexer, parser, and code generator transform `.tardis` files to JavaScript modules
+- **File-based routing** — `pages/index.tardis` → `/`, `pages/[slug].tardis` → `/:slug`
+- **Built-in dev server** — HMR via WebSocket, auto port discovery
+- **Zero runtime dependencies** — the runtime has no external deps
+- **Tailwind integration** — style tokens map directly to Tailwind classes
+
+## Project Structure
+
+```
+my-app/
+  pages/
+    index.tardis        # Routes derived from file structure
+    about.tardis
+    blog/[id].tardis    # Dynamic route: /blog/:id
+  components/
+    Button.tardis       # Reusable components
+  public/               # Static assets (copied to dist)
+  tardis.config.js      # Project configuration
+  package.json
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `tardis init` | Scaffold a project in the current directory |
+| `tardis dev` | Dev server with hot reload |
+| `tardis build` | Production build to `dist/` |
+| `tardis preview` | Serve built output on port 4000 |
+| `create-tardis-app <name>` | Create a new project in a subdirectory |
+
+## Configuration
+
+```js
+// tardis.config.js
+export default {
+  pages: './pages',
+  components: './components',
+  outDir: './dist',
+  port: 3000,
+  title: 'my app',
+  head: [
+    '<script src="https://cdn.tailwindcss.com"></script>',
+  ],
+  staticDir: './public',
+}
+```
+
+## Blueprint Anatomy
+
+```
+blueprint ComponentName {
+  props { }       // Typed component inputs
+  state { }       // Reactive local state (Proxy-based)
+  computed { }    // Derived values from state
+  methods { }     // Event handlers and logic
+  events { }      // Lifecycle: onMount, onDestroy, onUpdate
+  style(tailwind) { }  // Named class tokens
+  ui { }          // HTML-like template with reactive bindings
+}
+```
+
+Every section is optional. Pages typically omit `props`; leaf components may omit `state`.
+
+## Runtime API
+
+| Function | Purpose |
+|----------|---------|
+| `$update(ref, value)` | Update state and trigger bindings |
+| `$toggle(ref)` | Toggle boolean state |
+| `$reset(state, initial)` | Reset state to defaults |
+| `$batch(fn)` | Batch updates into single render cycle |
+| `$navigate(path)` | Client-side navigation |
+| `$params` | Read dynamic route parameters |
+| `$back()` / `$forward()` | History traversal |
+| `$fetch(url, opts?)` | Network request helper |
+| `$if` / `$each` / `$show` | Conditional and list rendering |
+| `$portal(el, target)` | Render into external DOM target |
+| `$(selector)` | jQuery-inspired DOM query |
+
+## VS Code Extension
+
+Syntax highlighting for `.tardis` files is available in `vscode-extension/`. Install the `.vsix` file:
+
+1. Open VS Code
+2. Go to Extensions → `...` menu → Install from VSIX
+3. Select `vscode-extension/tardisjs-syntax-0.1.0.vsix`
+
+## Development
+
+```bash
+git clone https://github.com/devansharora18/tardisjs.git
+cd tardisjs
+npm install
+npm run build       # Build compiler + runtime + CLI
+npm test            # Run test suite
+npm run typecheck   # Type checking
+npm run dev         # Watch mode
+```
+
+### Build Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run build` | Full build (clean + lib + binaries) |
+| `npm run build:lib` | Compiler and runtime only |
+| `npm run build:bin` | CLI binaries only |
+| `npm run dev` | Rollup watch mode |
+| `npm test` | Vitest single run |
+| `npm run test:watch` | Vitest watch mode |
+| `npm run typecheck` | TypeScript check |
+| `npm run publish:check` | Full quality gate |
+
+## Examples
+
+Working examples are in `examples/`:
+
+- **`examples/counter/`** — Counter with increment, decrement, and reset
+- **`examples/todo/`** — Todo list application
+
+## How It Works
+
+```
+.tardis source
+  → lex()      Tokenize input
+  → parse()    Build AST
+  → compile()  Generate JavaScript
+  → TypeScript transpile
+  → Runtime import rewriting
+  → Browser-ready JS module
+```
+
+The compiler transforms blueprint sections into imperative DOM code that references the `$runtime` object. State uses JavaScript Proxies for fine-grained reactivity — only bindings that read a changed key are re-evaluated.
+
+## Contributing
+
+1. Create a branch scoped to one concern
+2. Add or update tests next to affected subsystem
+3. Run `npm run typecheck && npm test` before review
+4. Provide minimal reproduction for parser/compiler defects
+
+## License
+
+MIT

package/dist/bin/create-tardis-app.js

@@ -869,7 +869,7 @@ function compileUI(raw, componentName, scriptCode) {
     const lines = [];
     lines.push(`  // ui`);
     lines.push(`  const _root = (() => {`);
-    lines.push(compileUINode(raw.trim(), 2));
+    lines.push(compileUINode(raw.trim(), 2, false));
     lines.push(`  })()`);
     if (scriptCode) {
         lines.push(``);
@@ -911,14 +911,14 @@ function compileScript(ast) {
     lines.push(`  })`);
     return lines.join('\n');
 }
-function compileUINode(raw, depth) {
+function compileUINode(raw, depth, preserveWs) {
     const indent = "  ".repeat(depth);
     const lines = [];
     // $if
     const ifMatch = raw.match(/^\$if\((.+?)\)\s*\{([\s\S]*)\}/);
     if (ifMatch) {
         const condition = rewriteRefs(ifMatch[1].trim());
-        const inner = compileUINode(ifMatch[2].trim(), depth + 1);
+        const inner = compileUINode(ifMatch[2].trim(), depth + 1, preserveWs);
         lines.push(`${indent}return $runtime.if(() => ${condition}, () => {`);
         lines.push(inner);
         lines.push(`${indent}})`);
@@ -929,7 +929,7 @@ function compileUINode(raw, depth) {
     if (eachMatch) {
         const arrayRef = rewriteRefs(eachMatch[1].trim());
         const itemVar = eachMatch[2];
-        const inner = compileUINode(eachMatch[3].trim(), depth + 1);
+        const inner = compileUINode(eachMatch[3].trim(), depth + 1, preserveWs);
         lines.push(`${indent}return $runtime.each(() => ${arrayRef}, (${itemVar}) => {`);
         lines.push(inner);
         lines.push(`${indent}})`);
@@ -939,7 +939,7 @@ function compileUINode(raw, depth) {
     const showMatch = raw.match(/^\$show\((.+?)\)\s*\{([\s\S]*)\}/);
     if (showMatch) {
         const condition = rewriteRefs(showMatch[1].trim());
-        const inner = compileUINode(showMatch[2].trim(), depth + 1);
+        const inner = compileUINode(showMatch[2].trim(), depth + 1, preserveWs);
         lines.push(`${indent}return $runtime.show(() => ${condition}, () => {`);
         lines.push(inner);
         lines.push(`${indent}})`);
@@ -950,7 +950,7 @@ function compileUINode(raw, depth) {
     if (chainMatch) {
         const innerEl = chainMatch[1].trim();
         const chainStr = chainMatch[2].trim();
-        const elCode = compileElement(innerEl, depth);
+        const elCode = compileElement(innerEl, depth, preserveWs);
         const chains = parseChains(chainStr);
         lines.push(`${indent}const _chained = (() => {`);
         lines.push(elCode);
@@ -961,9 +961,9 @@ function compileUINode(raw, depth) {
         lines.push(`${indent}return _chained`);
         return lines.join("\n");
     }
-    return compileElement(raw, depth);
+    return compileElement(raw, depth, preserveWs);
 }
-function compileElement(raw, depth) {
+function compileElement(raw, depth, preserveWs) {
     const indent = "  ".repeat(depth);
     const lines = [];
     const trimmed = raw.trim();
@@ -1011,22 +1011,34 @@ function compileElement(raw, depth) {
         lines.push(`${indent}return $runtime.component('${tag}', { ${compileComponentProps(attrsRaw)} })`);
         return lines.join("\n");
     }
+    // preserve whitespace inside <pre> elements
+    const childPreserveWs = preserveWs || tag === 'pre';
     const innerContent = findInnerContent(trimmed, tag, openTagEndIdx + 1);
     lines.push(`${indent}const _el_${depth} = document.createElement('${tag}')`);
     for (const attr of parseAttributes(attrsRaw)) {
         lines.push(...compileAttr(attr, depth, indent));
     }
-    const children = splitChildren(innerContent);
+    const children = splitChildren(innerContent, childPreserveWs);
     let childIndex = 0;
     for (let ci = 0; ci < children.length; ci++) {
         const child = children[ci];
-        // normalize whitespace: trim first child's leading, last child's trailing
-        // but preserve boundary spaces for middle children (e.g. "text " before <span>)
-        let ct = child.replace(/\s*\n\s*/g, ' ');
-        if (ci === 0)
-            ct = ct.replace(/^\s+/, '');
-        if (ci === children.length - 1)
-            ct = ct.replace(/\s+$/, '');
+        let ct;
+        const isChildElement = child.trimStart().startsWith('<') ||
+            child.trimStart().startsWith('$') ||
+            child.trimStart().startsWith('{<');
+        if (childPreserveWs || isChildElement) {
+            // preserve whitespace (inside <pre>, or element children that handle their own ws)
+            ct = child;
+        }
+        else {
+            // normalize whitespace: trim first child's leading, last child's trailing
+            // but preserve boundary spaces for middle children (e.g. "text " before <span>)
+            ct = child.replace(/\s*\n\s*/g, ' ');
+            if (ci === 0)
+                ct = ct.replace(/^\s+/, '');
+            if (ci === children.length - 1)
+                ct = ct.replace(/\s+$/, '');
+        }
         if (!ct)
             continue;
         if (ct.startsWith('{') && ct.endsWith('}') && !ct.startsWith('{<')) {
@@ -1047,7 +1059,7 @@ function compileElement(raw, depth) {
             }
             const childVar = `_child_${depth}_${childIndex}`;
             lines.push(`${indent}const ${childVar} = (() => {`);
-            lines.push(compileUINode(ct, depth + 1));
+            lines.push(compileUINode(ct, depth + 1, childPreserveWs));
             lines.push(`${indent}})()`);
             lines.push(`${indent}if (${childVar} instanceof Node) _el_${depth}.appendChild(${childVar})`);
         }
@@ -1293,18 +1305,22 @@ function normalizeWs(s) {
     // but preserve meaningful spaces at word/element boundaries
     return s.replace(/\s*\n\s*/g, ' ');
 }
-function splitChildren(raw) {
+function splitChildren(raw, preserveWs = false) {
     const parts = [];
     let depth = 0;
     let current = "";
     let i = 0;
+    // Only normalize text-only fragments; leave element children as-is
+    // so that <pre> and similar tags can preserve their internal whitespace
+    const ws = (s, isElement) => (preserveWs || isElement) ? s : normalizeWs(s);
     while (i < raw.length) {
         const ch = raw[i];
         if (ch === "<") {
             if (raw[i + 1] === "/") {
                 if (depth === 0) {
                     // closing tag for PARENT element — push current and skip tag
-                    const n = normalizeWs(current);
+                    const isEl = current.trimStart().startsWith('<');
+                    const n = ws(current, isEl);
                     if (n.trim())
                         parts.push(n);
                     current = "";
@@ -1325,7 +1341,8 @@ function splitChildren(raw) {
                         current += raw[i]; // the >
                         i++;
                     }
-                    const n = normalizeWs(current);
+                    const isEl = current.trimStart().startsWith('<');
+                    const n = ws(current, isEl);
                     if (n.trim())
                         parts.push(n);
                     current = "";
@@ -1349,14 +1366,20 @@ function splitChildren(raw) {
             if (next.startsWith("<") ||
                 next.startsWith("$") ||
                 next.startsWith("{")) {
-                const n = normalizeWs(current);
+                const isEl = current.trimStart().startsWith('<') ||
+                    current.trimStart().startsWith('$') ||
+                    current.trimStart().startsWith('{<');
+                const n = ws(current, isEl);
                 if (n.trim())
                     parts.push(n);
                 current = "";
             }
         }
     }
-    const n = normalizeWs(current);
+    const isEl = current.trimStart().startsWith('<') ||
+        current.trimStart().startsWith('$') ||
+        current.trimStart().startsWith('{<');
+    const n = ws(current, isEl);
     if (n.trim())
         parts.push(n);
     return parts.filter(p => p.trim().length > 0);
@@ -1833,11 +1856,12 @@ async function findAvailablePort(preferredPort) {
             tester.listen(port);
         });
     }
-    if (await check(preferredPort))
-        return preferredPort;
-    if (await check(preferredPort + 1))
-        return preferredPort + 1;
-    throw new CLIError(`TardisError: no open port found\n  Tried ${preferredPort} and ${preferredPort + 1}`);
+    const startPort = Math.max(1, preferredPort);
+    for (let port = startPort; port <= 65535; port++) {
+        if (await check(port))
+            return port;
+    }
+    throw new CLIError(`TardisError: no open port found\n  Tried ports ${startPort}-65535`);
 }
 async function buildProject(cwd = process.cwd()) {
     const start = Date.now();