gofront 0.0.7 → 0.0.9

package/README.md

@@ -7,6 +7,8 @@ quite felt like home either.
 So I built GoFront. Go syntax and type safety, compiling to plain ES modules. One language
 front and back, no runtime, no framework, no tsconfig.json.
 
+With built-in support for declarative DOM rendering via the [`gom`](https://www.gomponents.com) standard library, JSX-like [`.templ`](https://templ.guide/) files, and seamless integration with external JavaScript libraries through TypeScript definition files (`.d.ts`), GoFront is designed specifically as a frontend development target. Build complex, reactive user interfaces entirely in Go.
+
 Probably not useful. Definitely fun to build.
 
 ```go
@@ -61,6 +63,12 @@ source text (.go files)
   → Parser         recursive-descent → AST
   → Type Checker   annotate AST with types + collect errors
   → Code Gen       AST → JavaScript string
+
+source text (.templ files)
+  → TemplLexer     dual-mode: Go mode for declarations, HTML mode inside templ bodies
+  → TemplParser    extends Parser; produces TemplDecl AST nodes with TemplNode children
+  → Type Checker   registers each templ component as func(...) gom.Node
+  → Code Gen       TemplDecl → direct DOM calls (createElement / setAttribute / appendChild)
 ```
 
 ### 1. Lexer (`src/lexer.js`)
@@ -101,8 +109,8 @@ Walks the typed AST and emits clean, readable JavaScript. No intermediate repres
 — the codegen writes directly to an output buffer with indentation tracking.
 
 Runtime helpers (`__len`, `__append`, `__s`, `__sprintf`, `__cmul`, `__cdiv`, `__error`,
-`__errorIs`) are tree-shaken: only emitted when actually used. Optional inline source
-maps are supported via VLQ-encoded mappings.
+`__errorIs`, `__timeFmt`, `__timeParse`, `__pathClean`) are tree-shaken: only emitted
+when actually used. Optional inline source maps are supported via VLQ-encoded mappings.
 
 ---
 
@@ -184,7 +192,7 @@ The type checker enforces correctness; JavaScript doesn't need to know.
 
 ## Examples — Todo App
 
-There are three example apps — all implement the same todo app to show different aspects
+There are four example apps — all implement the same todo app to show different aspects
 of GoFront.
 
 ### Simple (vanilla DOM)
@@ -244,6 +252,60 @@ The reactive example covers the full reactive.js API surface:
 | Component instance | `signal`, `effect`, `on` (auto-cleanup event listeners) |
 | Scan attributes | `data-model`, `data-text`, `data-html`, `data-if`, `data-visible`, `data-class-*`, `data-attr-*`, `data-bool-*`, `data-on-*`, `data-ref` |
 
+### templ (template files + direct DOM codegen)
+
+Same todo app using GoFront's `.templ` file format — a JSX-like syntax embedded directly
+in `.go` packages. `templ` declarations compile to direct `document.createElement` calls
+with no intermediate representation, producing `{Mount(p){}}` objects that are fully
+compatible with the `gom.Node` interface.
+
+```
+example/templ/
+  src/
+    render.templ  ← UI as templ declarations: TodoItem, TodoList, Header, InputRow, StatsBar, AppView, …
+    render.go     ← helper functions (todoItemClass, filterLabel, …) + render() entry point
+    types.go      ← Todo struct, filter/priority constants
+    store.go      ← state, mutations, localStorage persistence
+    styles.go     ← appStyles() CSS string
+    main.go       ← event setup, entry point
+    utils/        ← Filter[T], Plural, HasText
+  app.js          ← generated output
+  index.html      ← HTML shell
+```
+
+`.templ` syntax at a glance:
+
+```go
+templ TodoItem(t Todo) {
+    <li class={ todoItemClass(t) } draggable="true" data-id={ t.id }>
+        <input type="checkbox" checked?={ t.done }/>
+        <span class="todo-text">{ t.text }</span>
+        if t.isUrgent() {
+            <span class="badge">urgent</span>
+        }
+    </li>
+}
+
+templ AppView() {
+    <div class="card">
+        @Header(highCount(), syncMsg, syncCls)
+        @TodoList(visibleTodos())
+    </div>
+}
+```
+
+Key syntax features:
+- `{ expr }` — interpolate any Go expression (strings auto-cast, others use `String()`)
+- `attr={ expr }` — dynamic attribute value (expression)
+- `attr?={ expr }` — boolean attribute (present/absent based on truthiness)
+- `@Component(args)` — call another templ component and mount it as a child
+- `if cond { } else if cond { } else { }` — conditional rendering (arbitrary depth)
+- `for _, v := range slice { }` — loop rendering inside template bodies
+- `switch expr { case v: ... default: ... }` — switch rendering inside template bodies
+- `@templ.Raw(htmlStr)` — inject raw/trusted HTML (uses `insertAdjacentHTML`)
+- Components are called like regular functions (`AppView()`, `TodoItem(t)`) and return
+  a `gom.Node`-compatible object, so `gom.Mount("#app", AppView())` works directly.
+
 ### gom (stdlib component library + todo app)
 
 Browser-native declarative DOM components inspired by
@@ -299,12 +361,19 @@ declarative node-tree pattern (no `innerHTML`, no `querySelector`), and full fea
 parity with the other examples (priority mode, validation, localStorage persistence,
 sync status, drag-and-drop reordering).
 
+The templ example additionally demonstrates: **`.templ` file compilation**, template
+components with parameters, `{ expr }` interpolation, `attr?={}` conditional boolean
+attributes, `@Component()` calls inside templates, `if / else if / else` chains,
+`switch` blocks, `for range` loops, and `@templ.Raw()` for trusted HTML injection —
+all inside template bodies.
+
 ### Build and run
 
 ```sh
 npm run build:simple      # → example/simple/app.js
 npm run build:reactive    # → example/reactive/app.js
 npm run build:gom         # → example/gom/app.js
+npm run build:templ       # → example/templ/app.js
 # open the respective index.html in a browser
 ```
 
@@ -377,7 +446,10 @@ func greet(name string) {
     console.log("Hello, " + name)
 }
 
-greet(42)   // → Type error in src/main.go at line 5: cannot use int as string
+greet(42)
+// → Type error in src/main.go at line 5:7: cannot use int as string
+//     5 | greet(42)
+//           ^
 ```
 
 External TypeScript type definitions are supported via `js:` imports:
@@ -464,21 +536,24 @@ signatures into GoFront's internal type representation.
 
 | Package | Functions |
 |---|---|
-| `fmt` | `Sprintf`, `Printf`, `Println`, `Print`, `Errorf`, `Fprintf`, `Fprintln`, `Fprint` — format verbs: `%v`, `%d`, `%s`, `%t`, `%x`, `%o`, `%b`, `%q`, `%e`, `%g`, `%w`, width/precision |
-| `strings` | `Contains`, `HasPrefix`, `HasSuffix`, `Index`, `LastIndex`, `Count`, `Repeat`, `Replace`, `ReplaceAll`, `ToUpper`, `ToLower`, `TrimSpace`, `Trim`, `TrimPrefix`, `TrimSuffix`, `TrimLeft`, `TrimRight`, `Split`, `Join`, `EqualFold`; **`Builder`** type (`WriteString`, `WriteByte`, `WriteRune`, `Write`, `String`, `Len`, `Reset`, `Grow`) |
-| `bytes` | `Contains`, `HasPrefix`, `HasSuffix`, `Index`, `Join`, `Split`, `Replace`, `ToUpper`, `ToLower`, `TrimSpace`, `Equal`, `Count`, `Repeat`; **`Buffer`** type (`WriteString`, `WriteByte`, `Write`, `String`, `Bytes`, `Len`, `Reset`) |
-| `strconv` | `Itoa`, `Atoi`, `FormatBool`, `FormatInt`, `FormatFloat`, `ParseFloat`, `ParseInt`, `ParseBool` |
-| `sort` | `Ints`, `Float64s`, `Strings`, `Slice`, `SliceStable`, `SliceIsSorted` |
-| `math` | `Abs`, `Floor`, `Ceil`, `Round`, `Sqrt`, `Cbrt`, `Pow`, `Log`, `Log2`, `Log10`, trig functions + `Pi`, `E`, `MaxFloat64`, `MaxInt`, `MinInt` |
+| `fmt` | `Sprintf`, `Printf`, `Println`, `Print`, `Errorf`, `Fprintf`, `Fprintln`, `Fprint` — format verbs: `%v`, `%d`, `%s`, `%t`, `%x`, `%o`, `%b`, `%q`, `%e`, `%g`, `%w`, width/precision; **scanning**: `Sscan`, `Sscanln`, `Sscanf` |
+| `strings` | `Contains`, `HasPrefix`, `HasSuffix`, `Index`, `LastIndex`, `Count`, `Repeat`, `Replace`, `ReplaceAll`, `ToUpper`, `ToLower`, `TrimSpace`, `Trim`, `TrimPrefix`, `TrimSuffix`, `TrimLeft`, `TrimRight`, `Split`, `Join`, `EqualFold`, `Fields`, `Cut`, `CutPrefix`, `CutSuffix`, `SplitN`, `SplitAfter`, `SplitAfterN`, `IndexAny`, `LastIndexAny`, `ContainsAny`, `ContainsRune`, `IndexRune`, `IndexByte`, `LastIndexByte`, `Map`, `Title`, `ToTitle`, `TrimFunc`, `TrimLeftFunc`, `TrimRightFunc`, `IndexFunc`, `LastIndexFunc`, `NewReplacer`; **`Builder`** type; **`NewReader`** → reader shim |
+| `bytes` | `Contains`, `HasPrefix`, `HasSuffix`, `Index`, `Join`, `Split`, `Replace`, `ToUpper`, `ToLower`, `TrimSpace`, `Equal`, `Count`, `Repeat`, `ReplaceAll`, `TrimPrefix`, `TrimSuffix`, `TrimLeft`, `TrimRight`, `TrimFunc`, `IndexByte`, `LastIndex`, `LastIndexByte`, `Fields`, `Cut`, `ContainsAny`, `ContainsRune`, `Map`, `SplitN`; **`Buffer`** type; **`NewReader`** → reader shim |
+| `strconv` | `Itoa`, `Atoi`, `FormatBool`, `FormatInt`, `FormatFloat`, `ParseFloat`, `ParseInt`, `ParseBool`, `Quote`, `Unquote`, `AppendInt`, `AppendFloat` |
+| `sort` | `Ints`, `Float64s`, `Strings`, `Slice`, `SliceStable`, `SliceIsSorted`, `Search`, `IntsAreSorted`, `Float64sAreSorted`, `StringsAreSorted` |
+| `math` | `Abs`, `Floor`, `Ceil`, `Round`, `Sqrt`, `Cbrt`, `Pow`, `Log`, `Log2`, `Log10`, `Sin`, `Cos`, `Tan`, `Atan`, `Atan2`, `Asin`, `Acos`, `Exp`, `Exp2`, `Trunc`, `Hypot`, `Signbit`, `Copysign`, `Dim`, `Remainder`, `Min`, `Max`, `Mod`, `Inf`, `IsNaN`, `IsInf`, `NaN` + `Pi`, `E`, `MaxFloat64`, `SmallestNonzeroFloat64`, `MaxInt`, `MinInt` |
+| `math/rand` | `Intn`, `Float64`, `Float32`, `Int`, `Int63`, `Int63n`, `Int31`, `Int31n`, `Seed` (no-op), `Shuffle`, `Perm` |
 | `errors` | `New`, `Is`, `Unwrap` — custom error types via interface satisfaction |
-| `time` | `Now`, `Since`, `Sleep` + `Millisecond`, `Second`, `Minute`, `Hour` constants |
+| `time` | `Now` → `time.Time`, `Since`, `Sleep`, `Parse`, `Unix`, `Date`; **`time.Time`** methods: `Format`, `String`, `Year`, `Month`, `Day`, `Hour`, `Minute`, `Second`, `Weekday`, `Unix`, `UnixMilli`, `Add`, `Sub`, `Before`, `After`, `Equal`; layout constants: `RFC3339`, `RFC3339Nano`, `DateOnly`, `TimeOnly`, `DateTime`; duration constants: `Millisecond`, `Second`, `Minute`, `Hour`; month/weekday constants |
 | `html` | `EscapeString`, `UnescapeString` |
 | `maps` | `Keys`, `Values`, `Clone`, `Copy`, `Equal`, `EqualFunc`, `Delete`, `DeleteFunc` |
 | `slices` | `Contains`, `Index`, `Equal`, `Compare`, `Sort`, `SortFunc`, `SortStableFunc`, `IsSorted`, `IsSortedFunc`, `Reverse`, `Max`, `Min`, `MaxFunc`, `MinFunc`, `Clone`, `Compact`, `CompactFunc`, `Concat`, `Delete`, `DeleteFunc`, `Insert`, `Replace`, `Grow`, `Clip` |
 | `regexp` | `MustCompile`, `Compile`, `MatchString`, `QuoteMeta`; **`*Regexp`** methods: `MatchString`, `FindString`, `FindStringIndex`, `FindAllString`, `FindStringSubmatch`, `FindAllStringSubmatch`, `ReplaceAllString`, `ReplaceAllLiteralString`, `Split`, `String`. Inline flags (`(?i)`, `(?m)`, `(?s)`) are extracted automatically into the JS `RegExp` constructor. |
 | `unicode` | `IsLetter`, `IsDigit`, `IsSpace`, `IsUpper`, `IsLower`, `IsPunct`, `IsControl`, `IsPrint`, `IsGraphic`, `ToUpper`, `ToLower` |
+| `unicode/utf8` | `RuneCountInString`, `RuneLen`, `ValidString`, `ValidRune`, `DecodeRuneInString`, `DecodeLastRuneInString`, `FullRuneInString`; constants `RuneError`, `MaxRune`, `UTFMax` |
+| `path` | `Base`, `Dir`, `Ext`, `Join`, `Clean`, `IsAbs`, `Split`, `Match`; `"path/filepath"` is an alias |
 | `os` | `Exit`, `Args`, `Getenv` |
-| `io` | `Writer`, `Reader`, `ReadWriter`, `Closer` interface types — used for accepting `*strings.Builder`, `*bytes.Buffer`, or any compatible writer/reader |
+| `io` | `Writer`, `Reader`, `ReadWriter`, `Closer` interface types; `ReadAll`, `EOF`, `Discard`, `WriteString` |
 | `gom` | Browser-native declarative DOM component library. **Types**: `Node` (interface), `NodeFunc`, `Group`. **Core**: `El(tag, children...)`, `Text(s)`, `Mount(sel, node)`, `MountTo(sel, node)`. **Attributes**: `Attr`, `Class`, `Href`, `Type`, `Src`, `Placeholder`, `DataAttr`, `Style`, `For`, `Name`, `Value`, `Target`, `Rel`, `Alt`, `Title`, `Draggable`, `Role`, `AriaLabel`, `StyleAttr`; boolean: `Disabled`, `Checked`, `Selected`, `Readonly`. **Logic**: `If(cond, node)`, `Map(slice, fn)`. **Elements**: full HTML element set (`Div`, `Span`, `Button`, `Input`, `Ul`, `Li`, `Table`, `Form`, `Img`, `A`, `H1`–`H6`, …) |
 
 ### Packages & imports
@@ -493,6 +568,7 @@ signatures into GoFront's internal type representation.
 | Unused import detection | ✓ |
 | External `.d.ts` types | ✓ |
 | npm package type resolution | ✓ |
+| `.templ` files in packages | ✓ — mix `.go` and `.templ` files freely; templ components visible across the whole package |
 
 ---
 
@@ -558,11 +634,21 @@ Design documents for planned features are organised by release under `docs/v*/`
 ## Tests
 
 ```sh
-npm test
+npm run test:unit   # unit tests only (~1100 tests, no browser required)
+npm run test:e2e    # E2E tests (Playwright, headless Chromium)
+npm test            # both
 ```
 
-990 tests covering language features, type errors, edge cases, DOM (jsdom), external
-`.d.ts`, npm resolver, multi-file compilation, embedded structs, string formatting, map
-iteration order, integer overflow semantics, unused variable detection, unused import
-detection, semantic difference verification, stdlib shim packages, generics (type params,
-inference, constraints), and both example apps.
+**Unit tests** (~1100) cover language features, type errors, edge cases, DOM (jsdom),
+external `.d.ts`, npm resolver, multi-file compilation, embedded structs, string
+formatting, map iteration order, integer overflow semantics, unused variable detection,
+unused import detection, semantic difference verification, stdlib shim packages, generics,
+and `.templ` file compilation (element rendering, interpolation, boolean attrs, component
+calls, `if/else/else-if` chains, `for range`, `switch/case/default`, `@templ.Raw()` raw
+HTML injection, mixed `.go`+`.templ` packages).
+
+**E2E tests** (~104, Playwright) run all four example apps in a real browser and verify
+CRUD, filtering, priority mode, persistence (reload), drag-and-drop reordering, and sync
+status. Per-app suites check app-specific behaviour: scoped styles, stats bar, loading
+placeholder, `gom.If` conditional rendering, and templ-specific features (`if/else`
+priority hint, `for` loop rendering, conditional bool attributes).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gofront",
-	"version": "0.0.7",
+	"version": "0.0.9",
 	"author": "Luuk van Venrooij",
 	"license": "MIT",
 	"repository": {
@@ -34,14 +34,19 @@
 		"build:simple": "node src/index.js example/simple/src -o example/simple/app.js",
 		"build:reactive": "node src/index.js example/reactive/src -o example/reactive/app.js",
 		"build:gom": "node src/index.js example/gom/src -o example/gom/app.js",
-		"test": "node test/unit/run.js",
+		"build:templ": "node src/index.js example/templ/src -o example/templ/app.js",
+		"test": "npm run test:unit && npm run test:e2e",
+		"test:unit": "node test/unit/run.js",
+		"test:e2e": "playwright test",
 		"format": "biome format --write .",
-		"check": "biome check .",
+		"check": "biome check . && node src/index.js example/simple/src --check && node src/index.js example/reactive/src --check && node src/index.js example/gom/src --check && node src/index.js example/templ/src --check",
 		"prepare": "husky"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.12",
+		"@playwright/test": "^1.59.1",
 		"husky": "^9.1.7",
-		"jsdom": "^29.0.2"
+		"jsdom": "^29.0.2",
+		"serve": "^14.2.6"
 	}
 }