coffeehaml 0.1.0

package/docs/grammar.md

@@ -0,0 +1,432 @@
+# CoffeeHaml Grammar
+
+## Notation
+
+```
+Rule         := Alternative1 | Alternative2
+X?            := zero or one X
+X*            := zero or more X
+X+            := one or more X
+X (sep Y)*    := X optionally followed by repeated (Y X)
+'literal'      := literal token
+[class]        := character class
+[^class]       := negated character class
+```
+
+Whitespace is **significant**: indentation determines nesting. The lexer
+emits `INDENT`/`DEDENT` tokens analogous to Python/CoffeeScript.
+
+---
+
+## Top-Level Production
+
+```
+Document       := (Node | BlankLine)* EOF
+
+BlankLine      := Whitespace* Newline
+
+Node           := Doctype
+               | Comment
+               | Filter
+               | ControlFlow
+               | Output
+               | Element
+               | ImplicitDiv
+               | RawText
+```
+
+---
+
+## Doctype
+
+```
+Doctype        := '!!!' Whitespace? DoctypeValue? Newline
+DoctypeValue   := [^\n]+
+```
+
+Examples: `!!!`, `!!! 5`, `!!! html`
+
+Emits nothing in React output (React renders into a DOM container, not a full
+document). Retained for Haml compatibility; may emit an HTML comment in
+non-React backends.
+
+---
+
+## Comments
+
+```
+Comment        := HamlComment | HTMLComment
+
+HamlComment    := '-#' Whitespace? CommentText? Newline
+                  (Indent Node* Dedent)?
+                // Removed entirely from output
+
+HTMLComment    := '/' Whitespace? CommentText? Newline
+                  (Indent Node* Dedent)?
+                // Emitted as <!-- ... --> in development
+```
+
+Haml comments (`-#`) are stripped. HTML comments (`/`) are preserved in the
+AST and emitted as `<!-- ... -->` (wrapped in a raw HTML insertion at
+runtime).
+
+---
+
+## Elements
+
+```
+Element        := '%' TagName TagModifiers? AttributeBlock? InlineContent? SelfClose? Newline
+                  (Indent Node* Dedent)?
+
+SelfClose      := '/' Whitespace?    // preceding newline
+                // %br/  →  <br />
+
+TagName        := Identifier (':' Identifier)*
+                // Allows SVG: %svg:circle, %math:mi
+
+TagModifiers   := (ClassModifier | IdModifier)+
+ClassModifier  := '.' ClassName
+IdModifier     := '#' IdName
+
+ClassName      := Identifier
+IdName         := Identifier
+
+Identifier     := [a-zA-Z_$] [a-zA-Z0-9_$]*
+```
+
+### Implicit Div
+
+When a line begins with `.class` or `#id` without a `%tag`, a `<div>` is
+implied — exactly as in Haml:
+
+```
+ImplicitDiv    := TagModifiers AttributeBlock? InlineContent? Newline
+                  (Indent Node* Dedent)?
+```
+
+```
+.container
+  %h1 Hello
+```
+
+Is equivalent to:
+
+```
+%div.container
+  %h1 Hello
+```
+
+---
+
+## Attributes
+
+```
+AttributeBlock := AttrBraces | AttrParens
+
+AttrBraces     := '{' AttrContent? '}'
+AttrParens     := '(' AttrContent? ')'
+
+AttrContent    := Arbitrary CoffeeScript until matching delimiter.
+                // Parsed as a CoffeeScript object literal.
+                // Comma-optional, supports splats, nested objects,
+                // function expressions, destructuring.
+```
+
+The content between `{...}` or `(...)` is extracted verbatim and parsed
+by the CoffeeScript compiler as an object literal. This means:
+
+```haml
+%div{class: "container", id: if active then "on" else "off"}
+%Button{onClick: (e) -> handleClick(e), disabled: !ready}
+%Panel{
+  style: {color: "red", margin: 10}
+  "aria-label": "Close"
+}
+```
+
+All CoffeeScript expression forms are valid inside attribute values:
+strings, numbers, bools, functions (`->`), conditionals, existential
+operator (`?.`), destructuring, splats (`...`).
+
+---
+
+## Inline Content
+
+```
+InlineContent  := Whitespace InlineText? OutputSuffix?
+
+InlineText     := ( [^\n%=] [^\n%]* )?
+                // Text up to newline, '%', or '='
+
+OutputSuffix   := '=' Whitespace? Expression
+                // Mixed text + output on same line:
+                // %p Hello, = user.name
+```
+
+Inline content follows the tag and attributes on the same line:
+
+```haml
+%h1 Welcome, = user.name
+%p This is a paragraph with inline content.
+%span.status{class: status} = statusText
+```
+
+---
+
+## Output
+
+```
+Output         := '='  Whitespace? Expression Newline   // escaped
+               | '==' Whitespace? Expression Newline   // unescaped (raw)
+```
+
+`=` inserts the result of a CoffeeScript expression as a child node.
+`==` inserts without HTML escaping (for raw HTML — use cautiously).
+
+```haml
+%h1
+  = pageTitle
+%div
+  = formatMarkdown(content)
+  == user.bioHTML
+```
+
+---
+
+## Control Flow
+
+```
+ControlFlow    := '-' Whitespace? ControlExpression
+
+ControlExpression := IfChain
+                  | UnlessBlock
+                  | ForBlock
+                  | WhileBlock
+                  | CoffeeStatement
+
+IfChain        := IfBlock (ElseIfBlock | ElseBlock)*
+
+IfBlock        := 'if' Whitespace Expression Newline
+                  (Indent Node* Dedent)?
+UnlessBlock    := 'unless' Whitespace Expression Newline
+                  (Indent Node* Dedent)?
+ElseIfBlock    := 'else' Whitespace 'if' Whitespace Expression Newline
+                  (Indent Node* Dedent)?
+ElseBlock      := 'else' Newline
+                  (Indent Node* Dedent)?
+
+ForBlock       := 'for' Whitespace ForClause Newline
+                  (Indent Node* Dedent)?
+ForClause      := ForIn | ForOf
+ForIn          := Pattern 'in' Expression
+ForOf          := Pattern 'of' Expression
+Pattern        := Identifier (',' Identifier)*
+               | '[' Pattern (',' Pattern)* ']'
+               | '{' Pattern (',' Pattern)* '}'
+
+WhileBlock     := 'while' Whitespace Expression Newline
+                  (Indent Node* Dedent)?
+
+CoffeeStatement := Any valid CoffeeScript statement.
+                 // Arbitrary CoffeeScript code inserted verbatim.
+```
+
+Control flow bodies contain CoffeeHaml nodes (elements, output, nested
+control flow) and compile to JavaScript that produces child arrays.
+
+```haml
+- if user
+  %WelcomeBanner{user: user}
+- else
+  %LoginPrompt
+
+- for item, index in items
+  %ItemCard{item: item, key: index}
+
+- unless loading
+  %Content{data: data}
+```
+
+### Semantics
+
+Control flow bodies compile to expressions that evaluate to arrays of
+React elements:
+
+```
+- for x in xs          →  ...xs.map((x) => jsx(...))
+- if cond              →  ...(cond ? [jsx(...)] : [])
+```
+
+---
+
+## Filters
+
+```
+Filter         := ':' FilterName Newline
+                  (Indent FilterContent Dedent)?
+
+FilterName     := Identifier
+FilterContent  := Lines of text at increased indentation.
+```
+
+Haml-style filters for embedded content. Common filters:
+
+| Filter | Purpose |
+|--------|---------|
+| `:css` | Embedded CSS block |
+| `:javascript` | Embedded JS block |
+| `:coffeescript` | Embedded CoffeeScript block |
+| `:markdown` | Markdown content → compiled at build time |
+| `:plain` | Pass-through text (no processing) |
+
+```haml
+%head
+  :css
+    body { margin: 0; }
+  :javascript
+    console.log("loaded");
+```
+
+Filters are compiled at build time. `:css` may be extracted or inlined
+depending on configuration.
+
+---
+
+## Raw Text / Passthrough
+
+```
+RawText        := [^%#\-=/:!. \t\n] [^\n]* Newline
+               // Any line not matching a recognized pattern.
+               // Treated as literal text (wrapped in a text node).
+```
+
+Lines that don't start with a special character (`%`, `.`, `#`, `-`, `=`,
+`/`, `:`, `!`) are treated as raw text. This enables "plain text" regions
+within templates.
+
+---
+
+## Expression Reference
+
+All `Expression` productions delegate to the CoffeeScript parser. Any
+valid CoffeeScript expression is accepted — the CoffeeHaml parser does not
+re-invent CoffeeScript's expression grammar.
+
+Key CoffeeScript expression forms used in CoffeeHaml:
+
+```
+// Functions
+->                   // zero-arg arrow
+(x) ->               // single-arg arrow
+(x, y) ->            // multi-arg arrow
+=>                   // bound arrow (fat arrow)
+
+// Conditionals (expression form)
+if cond then a else b
+unless cond then a
+
+// Existential
+obj?.prop
+obj?[key]
+
+// Comprehensions
+(x for x in arr)
+(x for x in arr when x > 0)
+
+// Splats
+arr...
+{obj..., newKey: val}
+
+// String interpolation
+"Hello, #{name}"
+
+// Heregex
+/// pattern /g
+
+// Destructuring
+{a, b} = obj
+[first, rest...] = arr
+```
+
+---
+
+## Tokens (Lexer)
+
+The lexer produces these token types:
+
+| Token | Pattern | Notes |
+|-------|---------|-------|
+| `TAG` | `%[a-zA-Z_$]` | Element tag |
+| `CLASS` | `\.[a-zA-Z_$]` | Class modifier |
+| `ID` | `#[a-zA-Z_$]` | ID modifier |
+| `ATTR_OPEN_BRACE` | `{` | Attribute block start |
+| `ATTR_OPEN_PAREN` | `(` | Attribute block start (alt) |
+| `ATTR_CLOSE_BRACE` | `}` | Attribute block end |
+| `ATTR_CLOSE_PAREN` | `)` | Attribute block end (alt) |
+| `OUTPUT` | `=` | Inline expression output |
+| `OUTPUT_RAW` | `==` | Unescaped output |
+| `CONTROL` | `-` | Control flow prefix |
+| `COMMENT` | `-#` | Haml comment |
+| `HTML_COMMENT` | `/` | HTML comment |
+| `FILTER` | `:` | Filter prefix |
+| `DOCTYPE` | `!!!` | Doctype declaration |
+| `SELF_CLOSE` | `/` | Self-closing tag |
+| `TEXT` | (fallback) | Literal text |
+| `NEWLINE` | `\n`, `\r\n` | Line terminator |
+| `INDENT` | (virtual) | Increased indentation |
+| `DEDENT` | (virtual) | Decreased indentation |
+| `WHITESPACE` | `[ \t]` | Spaces/tabs (handled by indenter) |
+| `EOF` | (virtual) | End of file |
+
+The lexer is **context-aware** after certain tokens:
+- After `{` or `(`, scan for matching closing delimiter, extracting the
+  contained source as a raw string for CoffeeScript parsing.
+- After `=`, scan to end of line for expression source.
+- After `-`, scan to end of line for control expression source.
+- After `:`, scan for filter name.
+
+---
+
+## Indentation Rules
+
+CoffeeHaml uses **significant indentation** exactly like Haml and
+CoffeeScript:
+
+1. The first non-blank line of a document establishes the base indent
+   level (typically 0).
+2. A line with **more** indentation than the current line opens a new
+   nesting level → emit `INDENT`.
+3. A line with **less** indentation closes one or more nesting levels →
+   emit `DEDENT` for each closed level.
+4. Tabs and spaces **cannot** be mixed. The indent character is detected
+   from the first indented line.
+5. Blank lines are ignored for indentation purposes.
+6. Multi-line expressions (attribute blocks, expressions) defer the
+   `NEWLINE` token until the construct is complete.
+
+```
+%div           // indent 0
+  %p           // indent 2 → INDENT
+    Hello      // indent 4 → INDENT
+  %p           // indent 2 → DEDENT
+    World      // indent 4 → INDENT
+               // EOF → DEDENT, DEDENT
+```
+
+---
+
+## Precedence of Line-Level Patterns
+
+When the lexer encounters the start of a line (after optional whitespace),
+it checks patterns in this order:
+
+1. `!!!` → Doctype
+2. `%` + identifier → Element
+3. `.` + identifier → ImplicitDiv (class)
+4. `#` + identifier → ImplicitDiv (id)
+5. `-#` → HamlComment
+6. `/` → HTMLComment (unless followed by `/` or `*`)
+7. `-` → ControlFlow
+8. `=` / `==` → Output
+9. `:` + identifier → Filter
+10. anything else → RawText

package/docs/index.html

@@ -0,0 +1,129 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>CoffeeHaml — Haml structure. CoffeeScript semantics. React runtime.</title>
+  <meta name="description" content="CoffeeHaml compiles Haml-inspired indentation syntax with CoffeeScript expressions directly to React's JSX runtime. Zero runtime. Vite-native. 50% fewer tokens than JSX.">
+  <meta property="og:title" content="CoffeeHaml">
+  <meta property="og:description" content="Haml structure. CoffeeScript semantics. React runtime. Zero overhead.">
+  <meta property="og:url" content="https://dantiel.github.io/CoffeeHaml/">
+  <meta property="og:type" content="website">
+  <meta name="twitter:card" content="summary">
+  <style>
+    :root {
+      --bg: #1a1a1a;
+      --fg: #e0d8c8;
+      --accent: #c8a45c;
+      --code-bg: #0d0d0d;
+      --muted: #888;
+      --border: #333;
+    }
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      background: var(--bg);
+      color: var(--fg);
+      line-height: 1.6;
+      max-width: 800px;
+      margin: 0 auto;
+      padding: 3rem 1.5rem;
+    }
+    h1 { font-size: 2.5rem; margin-bottom: 0.25rem; color: var(--accent); }
+    .tagline { font-size: 1.2rem; color: var(--muted); margin-bottom: 2rem; font-style: italic; }
+    h2 { font-size: 1.4rem; margin: 2rem 0 0.75rem; color: var(--accent); }
+    pre {
+      background: var(--code-bg);
+      padding: 1.25rem;
+      border-radius: 8px;
+      overflow-x: auto;
+      font-family: 'SF Mono', 'Fira Code', monospace;
+      font-size: 0.9rem;
+      line-height: 1.5;
+      border: 1px solid var(--border);
+    }
+    code { font-family: 'SF Mono', 'Fira Code', monospace; }
+    a { color: var(--accent); }
+    .btn {
+      display: inline-block;
+      padding: 0.6rem 1.4rem;
+      background: var(--accent);
+      color: var(--bg);
+      border-radius: 6px;
+      text-decoration: none;
+      font-weight: 600;
+      margin-right: 0.75rem;
+      margin-top: 0.5rem;
+    }
+    .btn-outline {
+      background: transparent;
+      color: var(--accent);
+      border: 1px solid var(--accent);
+    }
+    .stats {
+      display: flex;
+      gap: 2rem;
+      margin: 1.5rem 0;
+    }
+    .stat { text-align: center; }
+    .stat-num { font-size: 2rem; color: var(--accent); font-weight: bold; }
+    .stat-label { font-size: 0.8rem; color: var(--muted); text-transform: uppercase; }
+    footer { margin-top: 3rem; padding-top: 1rem; border-top: 1px solid var(--border); color: var(--muted); font-size: 0.85rem; }
+  </style>
+</head>
+<body>
+  <h1>☕ CoffeeHaml</h1>
+  <p class="tagline">Haml structure. CoffeeScript semantics. React runtime. <br>Zero overhead. 50% fewer tokens than JSX.</p>
+
+  <p>
+    <a class="btn" href="https://github.com/dantiel/CoffeeHaml">GitHub</a>
+    <a class="btn btn-outline" href="https://www.npmjs.com/package/coffeehaml">npm</a>
+  </p>
+
+  <div class="stats">
+    <div class="stat"><div class="stat-num">0</div><div class="stat-label">Runtime KB</div></div>
+    <div class="stat"><div class="stat-num">~50%</div><div class="stat-label">Token Reduction</div></div>
+    <div class="stat"><div class="stat-num">3</div><div class="stat-label">Extensions</div></div>
+  </div>
+
+  <h2>Write This</h2>
+  <pre>.card
+  %h2= post.title
+  - if showBody
+    .body= post.content</pre>
+
+  <h2>Get This</h2>
+  <pre>import { jsx, jsxs } from "react/jsx-runtime";
+
+jsxs("div", { className: "card" },
+  jsx("h2", null, post.title),
+  ...(showBody ? [
+    jsx("div", { className: "body" }, post.content)
+  ] : [])
+);</pre>
+
+  <h2>Quick Start</h2>
+  <pre>npm install coffeehaml</pre>
+
+  <h3>Vite</h3>
+  <pre>// vite.config.ts
+import coffeehaml from 'coffeehaml/vite';
+
+export default {
+  plugins: [coffeehaml()],
+};</pre>
+
+  <h3>CLI</h3>
+  <pre>npx coffeehaml compile app.coffeehaml</pre>
+
+  <p style="margin-top:1.5rem;">
+    Supports <code>.chaml</code>, <code>.coffeehaml</code>, and <code>.cohaml</code> extensions.
+    Full documentation on <a href="https://github.com/dantiel/CoffeeHaml">GitHub</a>.
+  </p>
+
+  <footer>
+    MIT License · Created by <a href="https://github.com/dantiel">dantiel</a><br>
+    CoffeeHaml replaces JSX — not React. No runtime. No framework. Just a compiler.
+  </footer>
+</body>
+</html>

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "coffeehaml",
+  "version": "0.1.0",
+  "description": "Haml structure. CoffeeScript semantics. React runtime.",
+  "type": "module",
+  "license": "MIT",
+  "author": "dantiel <dantiel@proton.me>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dantiel/CoffeeHaml.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dantiel/CoffeeHaml/issues"
+  },
+  "homepage": "https://github.com/dantiel/CoffeeHaml#readme",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "coffeehaml": "./dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./vite": "./dist/vite-plugin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "coffeehaml",
+    "haml",
+    "coffeescript",
+    "react",
+    "jsx",
+    "compiler",
+    "vite",
+    "template-language",
+    "indentation-based",
+    "jsx-runtime"
+  ],
+  "peerDependencies": {
+    "coffeescript": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "dependencies": {
+    "source-map": "^0.7.4"
+  }
+}