@chilts/weave 0.5.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,104 @@ 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:
+
+```
+a(href="/about" class="nav-link") About
+input(type="email" name="email")
+```
+
+A value can be a quoted string, a template literal, or a bare TypeScript expression:
+
+```
+a(href=post.author.url)= post.author.title
+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`, `undefined` or `null`:
+
+```
+input(type="checkbox" checked=true)      →  <input type="checkbox" checked>
+input(type="checkbox" checked=false)     →  <input type="checkbox">
+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:
+
+```
+main(class=(wide ? "px-6" : "mx-auto px-6"))
+main(class=`${wide ? "" : "mx-auto "}px-6`)
+```
+
+An unwrapped multi-token value is a compile error rather than a silent mis-parse. This is also why `main(class=a b)` is rejected: `b` could be part of the value or a separate attribute, so Weave asks you to say which you meant — `class="a b"` or `class=a b="..."`.
+
+#### Long attribute lists
+
+An attribute list normally lives on one line. To split it over several lines, end
+the line with the opening `(`, put **one attribute per line**, and close with a `)`
+on a line of its own:
+
+```
+button.btn(
+    type="button"
+    class="rounded px-2"
+    aria-pressed=isActive
+    ...attrs
+)
+  | Toggle theme
+```
+
+The continuation lines have to be indented further than the element, and the
+closing `)` has to start its own line — `aria-pressed=isActive)` is an error. That
+strictness is what makes a forgotten `)` a local error instead of something that
+swallows the rest of the file. Anything after the closing `)` is read as trailing
+content, so `) Toggle theme` works too.
+
+Everything else is unchanged: this is a layout choice, not a different grammar.
+Bare values still have to be a single token here, so a ternary still needs its
+wrapping parentheses.
+
+A `(` that is *not* at the end of its line must still close on that line:
+
+```
+a(href="/about"
+  class="nav-link")     ← error: unterminated attribute list
+```
+
+#### Spread
+
+`...attrs` forwards a whole set of attributes, most often a mixin's implicit `attrs`:
+
+```
+button.btn(class=`btn-${variant}` ...attrs)= label
+```
+
 ### Conditionals
 
 ```
@@ -164,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:
@@ -178,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:
@@ -255,6 +385,20 @@ Weave is in early design. The `examples/` directory contains paired `.weave` and
 
 - **Emacs** — [`editors/emacs/`](editors/emacs/) — major mode with syntax highlighting, indentation, and comment support
 
+## Releases
+
+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 |
+| 0.3.0   | 2026-04-05 | Raw blocks (`tag!`); Emacs mode |
+| 0.2.0   | 2026-04-05 | Bare `\|` emits a space |
+| 0.1.0   | 2026-04-05 | Initial release |
+
 ## License
 
 ISC

package/dist/cli/index.d.ts

@@ -1,3 +1,4 @@
+import type { IncludeResolver } from '../codegen/index.js';
 interface CompileArgs {
     mode: 'compile';
     inputPath: string;
@@ -20,12 +21,29 @@ export declare class UsageError extends Error {
 export declare function parseArgs(argv: string[]): CliArgs;
 export declare function usage(): string;
 export declare function discoverFiles(inputDir: string): string[];
+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;
+export declare function watchDir(inputDir: string, outputDir: string, sourcemap?: boolean): () => void;
+export declare function reconcile(inputDir: string, outputDir: string, sourcemap: boolean, pending: Map<string, ReturnType<typeof setTimeout>>): void;
 export declare function main(argv: string[]): void;
 export {};
 //# sourceMappingURL=index.d.ts.map