@chilts/weave 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,178 @@
+# Changelog
+
+All notable changes to `@chilts/weave` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+While the version is below `1.0.0`, breaking changes may land in minor releases.
+
+## [Unreleased]
+
+## [0.7.0] - 2026-10-20
+
+### Added
+
+- **Escaped dots in class and id shorthand.** `.gap-1\.5` is the single class
+  `gap-1.5`, so Tailwind's fractional spacing classes work as shorthand.
+- **Multi-line parameter lists.** The parentheses after `template`, `mixin`,
+  `extends`, `for` and a mixin call may now wrap over several lines, staying
+  open until they balance, so a long destructured signature can be written
+  the way TypeScript is normally wrapped. Continuation lines must be indented
+  under the opening line (a closing line such as `}: Props)` may sit level with
+  it). A string inside must close on its own line, and `//` comments are
+  dropped from the output. The compiled code keeps the wrapped layout, adding
+  `attrs`/`blocks` on a line of their own when the `)` was on its own line.
+- **Emacs mode understands context.** `weave-mode` now follows multi-line
+  attribute and parameter lists and raw (`tag!`) blocks when highlighting and
+  indenting, highlights attribute names, aligns `else` with its `if`, and
+  cycles outwards on repeated TAB. An apostrophe in text no longer opens a
+  string, `//` in a URL is no longer a comment, and `.`/`#` are only coloured
+  as a class or id where they really are one.
+
+### Fixed
+
+- A dotted class such as `.gap-1.5` was silently split into `gap-1` plus a
+  stray class `5`. A shorthand class that is a bare number is now a
+  `LexerError` that names the split and suggests escaping the dot.
+- `include ./partials` imported a binding named after the file (`partials`)
+  instead of the mixins the template calls, so a file defining several
+  mixins, or one not named after its file, compiled to code that failed in
+  `tsc`. The compiler now reads the included file and imports only the mixins
+  called (`import { badge, chip } from './partials.js'`). Calling a mixin that
+  no include or local definition provides is a `CodegenError`. For API users,
+  `compile()`, `compileWithSourceMap()` and `generate()` take an optional
+  `resolveInclude`. Without it, a lone include provides every called mixin
+  that isn't defined locally, and several includes are an error.
+- Shorthand classes combined with a non-literal `class=` value leaked the
+  value's string form: `div.pt-4(class=undefined)` rendered
+  `class="pt-4 undefined"`, as did the usual conditional-class pattern
+  `class=(on ? "x" : undefined)` whenever it was off. Non-literal values are
+  now merged at render time by a new `mergeClass()` runtime helper, which
+  drops `undefined`, `null`, `false` and `""`. An attribute whose value is
+  `null` is now omitted instead of rendering as `"null"`.
+- A template literal with a `${...}` interpolation inside a mixin call's
+  arguments, or a `template`/`mixin` parameter list, failed with
+  "Unterminated parentheses". A string containing a brace inside the
+  interpolation is also handled.
+- Error locations and source maps now point at the start of a token rather
+  than just past its end — for example, a mixin call is located at its `+`
+  instead of its argument list.
+- In watch mode, changing an included file now recompiles the templates that
+  include it, so a newly added mixin is picked up without touching each page.
+  The start-up reconcile likewise recompiles a template whose include is
+  newer than its output.
+- Rebuilding with `--no-sourcemap` now removes a `.ts.map` left over from an
+  earlier build instead of leaving a map that no longer matches its `.ts`.
+
+## [0.6.0] - 2026-10-19
+
+### Added
+
+- **Multi-line attribute lists.** End a line with the opening `(` to spread an
+  element's attributes over several lines — one attribute per line, indented
+  under the element, closed by a `)` on a line of its own. Works for mixin call
+  attributes too. Anything after the closing `)` is read as trailing content.
+  Attribute values follow exactly the same rules as the inline form.
+
+### Changed
+
+- **Breaking: every attribute must have a value.** The Pug-style valueless
+  boolean shorthand has been removed — `input(disabled)` no longer compiles.
+  Boolean attributes are now written with an explicit boolean value:
+  `disabled=true`, `disabled=false`, or an expression `disabled=isActive`
+  (the runtime renders a bare attribute for `true` and omits it for `false`
+  or `undefined`). Do not use a quoted `disabled="false"` — in HTML any
+  attribute that is present counts as true.
+- A bare (unquoted) attribute value must be a single token. Multi-token
+  expressions such as a ternary or string concatenation must be wrapped in
+  parentheses (`class=(wide ? "a" : "b")`) or backticks
+  (``class=`${wide ? "a" : "b"}` ``), because a space separates one
+  attribute from the next.
+
+### Fixed
+
+- The lexer no longer hangs and aborts the process (SIGABRT) on a multi-token
+  bare attribute value; it now raises a clear `LexerError` with line and
+  column, pointing you to wrap the expression.
+- `main(class=a b)` is rejected with a message offering both readings
+  (`class="a b"` as one value, or `class=a b="..."` as two attributes)
+  instead of silently parsing as `class="a"` plus a boolean `b`.
+- An attribute list that ran off the end of its line was accepted as if it had
+  been closed, so the following lines were lexed as child elements — attribute
+  names became tags and their values rendered as visible text, and the stray
+  `)` could leak into the generated TypeScript. It is now a `LexerError`
+  anchored on the opening `(`.
+- Watch mode reconciles the output tree on start so edits made while the
+  watcher was down are not missed.
+- Watch mode on Linux stopped seeing a template after the first time an editor
+  saved it atomically (write a temp file, rename it over the original), so
+  later edits were never recompiled. Each directory now has its own watcher,
+  which survives atomic saves, and subdirectories created while watching are
+  picked up — including any templates already written into them.
+- Deleting a `.weave` template now removes its compiled `.ts` from the output
+  directory (in one-shot builds and in watch mode). The output directory is
+  treated as owned by Weave: any `.ts` with no matching `.weave` is removed.
+- A mixin, or a block's default content, with more than one root element
+  referenced `Fragment` without importing it, so the compiled file failed to
+  type-check. `Fragment` is now imported whenever it is used.
+
+### Removed
+
+- Source maps are no longer included in the published npm bundle.
+
+## [0.5.0] - 2026-06-11
+
+### Fixed
+
+- Multi-level `extends` and `doctype` now generate type-safe output.
+
+## [0.4.0] - 2026-04-05
+
+### Changed
+
+- Compiled templates return strings directly instead of arrays, simplifying
+  the generated output and how templates compose.
+
+## [0.3.0] - 2026-04-05
+
+### Added
+
+- Raw block syntax (`tag!`) for passing literal, unescaped content through to
+  the output (inline CSS, JavaScript, etc.).
+- Emacs major mode with syntax highlighting, indentation, and comment support.
+
+### Documentation
+
+- Added guidance on special characters and the single-pass escaping model to
+  the README.
+
+## [0.2.0] - 2026-04-05
+
+### Added
+
+- A bare `|` (pipe) on its own line emits a single space, for adding
+  whitespace between sibling elements.
+
+## [0.1.0] - 2026-04-05
+
+Initial release — the Weave compiler and runtime.
+
+### Added
+
+- Template syntax compiling `.weave` files to typed TypeScript functions:
+  templates, mixins, `extends`/`block` layouts, conditionals, iteration,
+  includes, interpolation, buffered expressions, and silent/pass-through
+  comments.
+- Runtime helpers: `h`, `doctype`, `Fragment`, `raw`, and single-pass escaping.
+- CLI `compile` command and a `--watch` mode for automatic recompilation.
+- Error messages with source code frames.
+- Source map generation.
+
+[Unreleased]: https://codeberg.org/chilts/weave/compare/v0.7.0...HEAD
+[0.7.0]: https://codeberg.org/chilts/weave/compare/v0.6.0...v0.7.0
+[0.6.0]: https://codeberg.org/chilts/weave/compare/v0.5.0...v0.6.0
+[0.5.0]: https://codeberg.org/chilts/weave/compare/v0.4.0...v0.5.0
+[0.4.0]: https://codeberg.org/chilts/weave/compare/v0.3.0...v0.4.0
+[0.3.0]: https://codeberg.org/chilts/weave/compare/v0.2.0...v0.3.0
+[0.2.0]: https://codeberg.org/chilts/weave/compare/v0.1.0...v0.2.0
+[0.1.0]: https://codeberg.org/chilts/weave/src/tag/v0.1.0

package/ReadMe.md

@@ -12,7 +12,7 @@ Pug is great. Weave takes the same indentation-based syntax and makes it TypeScr
 
 - **Type-safe templates** — template parameters are real TypeScript types
 - **Type-safe mixins** — positional args with TS type annotations
-- **Tailwind-friendly** — class names with colons (`.md:flex`, `.hover:bg-blue-500`) just work
+- **Tailwind-friendly** — class names with colons (`.md:flex`, `.hover:bg-blue-500`) just work, and dots escape (`.gap-1\.5`)
 - **Single-pass escaping** — values are escaped once at render time, never pre-escaped
 - **No runtime template engine** — compiled output is plain TypeScript
 
@@ -97,6 +97,14 @@ p.intro This is a paragraph with a class
 a(href="/about" class="nav-link") About
 ```
 
+A `.` always starts a new class, so a class name that contains a dot — like Tailwind's `gap-1.5` — must escape it with a backslash:
+
+```pug
+.flex.gap-1\.5.px-2\.5
+```
+
+An unescaped `.gap-1.5` would split into `gap-1` and a stray `5`, so a class that is a bare number is rejected with an error pointing at the fix.
+
 ### Attributes
 
 Attributes live inside parentheses and are separated by spaces. **Every attribute must have a value** — there is no valueless shorthand:
@@ -115,7 +123,7 @@ button(class=`btn-${variant}`)= label
 
 #### Boolean attributes
 
-Write the boolean explicitly. The runtime renders `true` as a bare attribute and omits the attribute entirely when the value is `false` or `undefined`:
+Write the boolean explicitly. The runtime renders `true` as a bare attribute and omits the attribute entirely when the value is `false`, `undefined` or `null`:
 
 ```
 input(type="checkbox" checked=true)      →  <input type="checkbox" checked>
@@ -125,6 +133,16 @@ input(type="checkbox" checked=isActive)  →  omitted when isActive is false
 
 Avoid a quoted `checked="false"` — in HTML any attribute that is present counts as true, so that renders as checked.
 
+#### Combining shorthand classes with `class=`
+
+Shorthand classes and a `class=` value are merged into one attribute. The shorthand classes are always kept; a value of `undefined`, `null`, `false` or `""` just adds nothing:
+
+```
+div.pt-4(class="mt-2")                         →  <div class="pt-4 mt-2">
+div.pt-4(class=undefined)                      →  <div class="pt-4">
+div.btn(class=(active ? "active" : undefined)) →  <div class="btn"> when active is false
+```
+
 #### Multi-token values must be wrapped
 
 Because a space separates one attribute from the next, a bare (unquoted) value has to be a single token. Wrap anything longer in parentheses or backticks:
@@ -244,6 +262,32 @@ template home({ title, welcomeMessage }: HomeProps)
 
 Blocks can have default content in the layout. If a page doesn't override a block, the default renders.
 
+### Long parameter lists
+
+The parentheses after `template`, `mixin`, `extends`, `for` and a mixin call hold
+TypeScript, which Weave copies through untouched. They can wrap over several lines
+however TypeScript usually wraps: the group simply stays open until its parentheses
+balance.
+
+```
+template dashboard({
+    title,
+    user,
+}: DashboardProps)
+  h1= title
+
++card(
+    post.title,
+    post.summary,
+)(class="mt-4")
+```
+
+Unlike a long attribute list there is no required shape, but continuation lines must
+be indented under the line that opens the group. The closing line may sit level with
+it if it starts with a closing bracket, as `}: DashboardProps)` does. So a forgotten
+`)` is reported where the indentation drops back. A string must close on the line it
+starts on, and `//` comments are allowed but left out of the compiled output.
+
 ### Includes
 
 Include another `.weave` file to use its mixins:
@@ -258,6 +302,12 @@ template actionsPage({ title }: ActionsPageProps)
       +button("Save", "primary")
 ```
 
+An included file can define any number of mixins. Weave reads it and imports
+only the ones the template calls, so `include ./partials` followed by
+`+badge(...)` and `+chip(...)` compiles to
+`import { badge, chip } from './partials.js'`. Calling a mixin that is neither
+defined in the file nor provided by an include is a compile error.
+
 ### Text content
 
 Use `|` (pipe) to add literal text as a child of an element:
@@ -341,6 +391,7 @@ See [CHANGELOG.md](CHANGELOG.md) for the full details of each release.
 
 | Version | Date       | Highlights |
 |---------|------------|------------|
+| 0.7.0   | 2026-10-20 | Multi-line parameter lists; escaped dots in class shorthand; `include` imports the mixins it provides; context-aware Emacs mode |
 | 0.6.0   | 2026-10-19 | Multi-line attribute lists; every attribute requires a value (breaking); watch-mode fixes |
 | 0.5.0   | 2026-06-11 | Type-safe multi-level `extends` and `doctype` |
 | 0.4.0   | 2026-04-05 | Templates return strings directly |

package/dist/cli/index.d.ts

@@ -1,3 +1,4 @@
+import type { IncludeResolver } from '../codegen/index.js';
 interface CompileArgs {
     mode: 'compile';
     inputPath: string;
@@ -24,6 +25,21 @@ export declare function pruneOrphans(inputDir: string, outputDir: string): void;
 export declare function formatElapsed(ms: number): string;
 export declare function formatCodeFrame(source: string, line: number, col: number): string;
 export declare function formatError(filePath: string, err: unknown, source?: string): string;
+/** Resolves `include` paths against the including file and reads their mixins. */
+export declare function includeResolver(inputFile: string): IncludeResolver;
+/**
+ * Absolute paths of the .weave files a template includes. A template that does
+ * not lex or parse includes nothing as far as the watcher is concerned — its
+ * own compile reports the error.
+ */
+export declare function includedFiles(inputFile: string, source: string): string[];
+/**
+ * Templates under inputDir (relative paths) that include relPath. An includer's
+ * import line is built from the mixins its includes define, so it must be
+ * recompiled when one of them changes. Includes do not re-export, so only
+ * direct includers are affected.
+ */
+export declare function findIncluders(inputDir: string, relPath: string): string[];
 export declare function compileFile(inputFile: string, outputFile: string, sourcemap?: boolean): void;
 export declare function compileDir(inputDir: string, outputDir: string, sourcemap?: boolean): boolean;
 export declare function watchDir(inputDir: string, outputDir: string, sourcemap?: boolean): () => void;

package/dist/cli/index.js

@@ -1,8 +1,8 @@
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync, unlinkSync, rmdirSync, watch, } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync, unlinkSync, rmdirSync, rmSync, watch, } from 'node:fs';
 import path from 'node:path';
-import { compile, compileWithSourceMap } from '../codegen/index.js';
-import { LexerError } from '../lexer/index.js';
-import { ParserError } from '../parser/index.js';
+import { compile, compileWithSourceMap, definedMixins } from '../codegen/index.js';
+import { lex, LexerError } from '../lexer/index.js';
+import { parse, ParserError } from '../parser/index.js';
 import { CodegenError } from '../codegen/index.js';
 export class UsageError extends Error {
     constructor(message) {
@@ -173,6 +173,69 @@ export function formatError(filePath, err, source) {
     }
     return result;
 }
+/** Resolves `include` paths against the including file and reads their mixins. */
+export function includeResolver(inputFile) {
+    return includePath => {
+        const file = path.resolve(path.dirname(inputFile), includePath + '.weave');
+        let source;
+        try {
+            source = readFileSync(file, 'utf-8');
+        }
+        catch (err) {
+            if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+                throw new Error(`${path.relative(process.cwd(), file)}: no such file`);
+            }
+            throw err;
+        }
+        return definedMixins(parse(lex(source)));
+    };
+}
+/**
+ * Absolute paths of the .weave files a template includes. A template that does
+ * not lex or parse includes nothing as far as the watcher is concerned — its
+ * own compile reports the error.
+ */
+export function includedFiles(inputFile, source) {
+    if (!/^include\s/m.test(source))
+        return [];
+    let doc;
+    try {
+        doc = parse(lex(source));
+    }
+    catch {
+        return [];
+    }
+    return doc.children.flatMap(c => c.type === 'Include' ? [path.resolve(path.dirname(inputFile), c.path + '.weave')] : []);
+}
+/**
+ * Templates under inputDir (relative paths) that include relPath. An includer's
+ * import line is built from the mixins its includes define, so it must be
+ * recompiled when one of them changes. Includes do not re-export, so only
+ * direct includers are affected.
+ */
+export function findIncluders(inputDir, relPath) {
+    const target = path.resolve(inputDir, relPath);
+    let files;
+    try {
+        files = discoverFiles(inputDir);
+    }
+    catch {
+        return [];
+    }
+    return files.filter(file => {
+        if (file === relPath)
+            return false;
+        const inFile = path.join(inputDir, file);
+        let source;
+        try {
+            source = readFileSync(inFile, 'utf-8');
+        }
+        catch {
+            return false;
+        }
+        return includedFiles(inFile, source).includes(target);
+    });
+}
 function writeCompiled(inputFile, outputFile, source, sourcemap) {
     const start = performance.now();
     if (sourcemap) {
@@ -181,15 +244,19 @@ function writeCompiled(inputFile, outputFile, source, sourcemap) {
         const { code, sourceMap } = compileWithSourceMap(source, {
             file: basename,
             sourceFile: sourceRelPath,
+            resolveInclude: includeResolver(inputFile),
         });
         mkdirSync(path.dirname(outputFile), { recursive: true });
         writeFileSync(outputFile, code + `//# sourceMappingURL=${basename}.map\n`);
         writeFileSync(outputFile + '.map', JSON.stringify(sourceMap));
     }
     else {
-        const result = compile(source);
+        const result = compile(source, { resolveInclude: includeResolver(inputFile) });
         mkdirSync(path.dirname(outputFile), { recursive: true });
         writeFileSync(outputFile, result);
+        // A map from an earlier sourcemap build no longer matches this .ts,
+        // and pruning keeps it because the .weave still exists.
+        rmSync(outputFile + '.map', { force: true });
     }
     return performance.now() - start;
 }
@@ -259,6 +326,13 @@ export function watchDir(inputDir, outputDir, sourcemap = true) {
         pending.set(relPath, setTimeout(() => {
             pending.delete(relPath);
             compileWatchedFile(inputDir, outputDir, relPath, sourcemap);
+            // Compiled directly rather than scheduled, so an include cycle
+            // cannot keep re-triggering itself. One with its own pending
+            // timer will be compiled by that.
+            for (const includer of findIncluders(inputDir, relPath)) {
+                if (!pending.has(includer))
+                    compileWatchedFile(inputDir, outputDir, includer, sourcemap);
+            }
         }, 50));
     };
     const isDir = (relPath) => {
@@ -355,9 +429,9 @@ export function watchDir(inputDir, outputDir, sourcemap = true) {
     };
 }
 // Walk the input dir and recompile any .weave whose .ts output is missing or
-// older than the source. Files with a pending debounce timer are skipped so we
-// never race an edit the watcher is already handling — this only catches
-// changes whose fs.watch event was dropped.
+// older than the source or any file it includes. Files with a pending debounce
+// timer are skipped so we never race an edit the watcher is already handling —
+// this only catches changes whose fs.watch event was dropped.
 export function reconcile(inputDir, outputDir, sourcemap, pending) {
     let files;
     try {
@@ -386,9 +460,6 @@ export function reconcile(inputDir, outputDir, sourcemap, pending) {
         catch {
             outMtime = undefined;
         }
-        // Up to date — the watcher already handled this file.
-        if (outMtime !== undefined && outMtime >= sourceMtime)
-            continue;
         let source;
         try {
             source = readFileSync(inFile, 'utf-8');
@@ -396,6 +467,20 @@ export function reconcile(inputDir, outputDir, sourcemap, pending) {
         catch {
             continue;
         }
+        // The output also depends on the mixins each include defines, so an
+        // include edited since the last compile makes it stale too.
+        let newestMtime = sourceMtime;
+        for (const included of includedFiles(inFile, source)) {
+            try {
+                newestMtime = Math.max(newestMtime, statSync(included).mtimeMs);
+            }
+            catch {
+                // A missing include is reported when the template compiles.
+            }
+        }
+        // Up to date — the watcher already handled this file.
+        if (outMtime !== undefined && outMtime >= newestMtime)
+            continue;
         try {
             const elapsed = writeCompiled(inFile, outFile, source, sourcemap);
             console.log(`${outFile} (reconciled, ${formatElapsed(elapsed)})`);

package/dist/codegen/index.d.ts

@@ -5,22 +5,36 @@ export interface GenerateResult {
     code: string;
     mappings: Mapping[];
 }
+/**
+ * Lists the mixins defined by the `.weave` file an `include` path names.
+ * The path is exactly as written after `include`; throw if it cannot be read.
+ */
+export type IncludeResolver = (includePath: string) => string[];
+export interface GenerateOptions {
+    /**
+     * Without a resolver, a lone `include` is assumed to provide every called
+     * mixin not defined in this file, and more than one `include` is an error.
+     */
+    resolveInclude?: IncludeResolver;
+}
 export declare class CodegenError extends Error {
     readonly line: number;
     readonly col: number;
     constructor(message: string, line: number, col: number);
 }
+/** Names of the mixins a document defines at top level. */
+export declare function definedMixins(doc: DocumentNode): string[];
 /** Generate a TypeScript expression from a single AST node. */
 export declare function generateExpr(node: AstNode): string;
 /** Generate TypeScript source from a DocumentNode. */
-export declare function generate(doc: DocumentNode): GenerateResult;
+export declare function generate(doc: DocumentNode, options?: GenerateOptions): GenerateResult;
 /** Full pipeline: source string → TypeScript source. */
-export declare function compile(source: string): string;
+export declare function compile(source: string, options?: GenerateOptions): string;
 /** Full pipeline with source map generation. */
 export declare function compileWithSourceMap(source: string, opts: {
     file: string;
     sourceFile: string;
-}): {
+} & GenerateOptions): {
     code: string;
     sourceMap: SourceMap;
 };