@fluixi/template-parser 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fluixi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @fluixi/template-parser
+
+The parser for Fluixi `` html`...` `` templates: a dependency-free tokenizer +
+recursive-descent parser that produces a **located, recoverable Template AST**.
+
+It is the shared foundation for everything that needs to understand a template —
+the compiler, the language server, the TypeScript plugin, and the Biome plugin —
+so they all agree on one grammar, one node model, and one set of diagnostics.
+
+## Why a separate parser
+
+The compiler used to scan template text straight into codegen IR in one pass.
+That was fine for emitting code but useless for tooling: no source spans, no
+diagnostics, no error recovery, and hard-wired to Babel. This package is the
+parse layer split out so every tool can reuse it:
+
+```
+pieces → Reader (lexing + holes) → parseTemplate → Template AST
+                                                      │
+             ┌────────────────────────────────────────┼───────────────┐
+        compiler (→ IR)      language server      Biome / formatter   TS plugin
+```
+
+The parser never resolves the JavaScript inside `${…}`. Each hole is recorded as
+an **opaque slot** (an index + a source span). Downstream, each tool binds slots
+to its own representation — a Babel node in the compiler, a `ts.Expression` in the
+LSP, raw text in Biome. That single seam is what keeps the parser host-agnostic.
+
+## Usage
+
+```ts
+import { parse } from '@fluixi/template-parser';
+
+const { root, diagnostics } = parse([
+  '<button @click=',        // static segment 0
+  '>',                      // hole 0 sits between segment 0 and 1
+  '</button>',              // static segment 1
+]); // → <button @click=${…}>${…}</button>
+```
+
+`parse(statics)` takes the static string segments (one more than the number of
+holes) and returns `{ root, diagnostics }`. Hosts with real source positions
+build `Piece[]` directly (via `parseTemplate`) so every span maps back to the
+original file.
+
+## What it parses
+
+Standard HTML, components (`<Button/>`, `<Ctx.Provider>`), fragments (`<>`),
+comments, SVG, raw-text elements, void elements, and the full binding surface:
+
+| Syntax | Node |
+| --- | --- |
+| `name`, `name="x"`, `name=${x}`, `name="a ${x} b"` | `AttributeNode` |
+| `?disabled` | `AttributeNode` (boolean) |
+| `.currentTime=${t}` | `PropertyBindingNode` |
+| `@click=${h}` / `onClick=${h}` | `EventBindingNode` |
+| `ref=${el}` | `RefBindingNode` |
+| `...${props}` / `${obj}` | `SpreadNode` |
+| `if=${c}` / `else` | `IfDirectiveNode` / `ElseDirectiveNode` |
+| `each=${xs}` (+ `key`) | `EachDirectiveNode` |
+| `bind:value=${sig}` | `BindDirectiveNode` |
+| `class:active=${on}` | `ClassDirectiveNode` |
+| `style:color=${c}` | `StyleDirectiveNode` |
+| `use=${d}` / `use:tooltip` | `UseDirectiveNode` |
+
+## Extensibility
+
+Adding a directive is a new entry in the directive **registry**, never a change
+to the core parser:
+
+```ts
+import { CORE_DIRECTIVES, parseTemplate, type DirectiveDescriptor } from '@fluixi/template-parser';
+
+const highlight: DirectiveDescriptor = {
+  id: 'highlight',
+  match: (name) => name === 'highlight',
+  build: (raw) => ({ kind: 'Attribute', name: 'data-highlight', value: raw.value, boolean: false, loc: raw.loc }),
+};
+
+parseTemplate(pieces, { directives: [highlight, ...CORE_DIRECTIVES] });
+```
+
+## Diagnostics
+
+The parser never throws and never stalls. It recovers from malformed input and
+reports located diagnostics: unclosed / mismatched / stray tags, unterminated
+comments, duplicate directives, and invalid bindings. Every diagnostic carries a
+`SourceSpan`.
+
+## License
+
+MIT

package/dist/ast.cjs

@@ -0,0 +1 @@
+"use strict";var r=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var l=Object.getOwnPropertyNames;var c=Object.prototype.hasOwnProperty;var p=(e,t)=>{for(var n in t)r(e,n,{get:t[n],enumerable:!0})},N=(e,t,n,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of l(t))!c.call(e,i)&&i!==n&&r(e,i,{get:()=>t[i],enumerable:!(o=s(t,i))||o.enumerable});return e};var m=e=>N(r({},"__esModule",{value:!0}),e);var u={};p(u,{childrenOf:()=>d,setParents:()=>x});module.exports=m(u);function x(e){let t=(n,o)=>{n.parent=o;let i=d(n);for(let a of i)t(a,n)};return t(e,null),e}function d(e){switch(e.kind){case"Root":case"Element":case"Component":case"Fragment":return e.children;default:return[]}}

package/dist/ast.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The Template AST — the stable, host-agnostic contract this package exists to
+ * produce. It is deliberately NOT the compiler's codegen IR: it models the
+ * template *as written* (every directive is an explicit node, every node keeps
+ * a source span, whitespace is preserved) so it can power the compiler AND the
+ * language server, TypeScript plugin, and Biome/formatter alike.
+ *
+ * Design rules baked into these types:
+ *  - Expression holes (`${…}`) are OPAQUE SLOTS. A node stores the hole's
+ *    integer `index` (its position in the template's `expressions[]`) and its
+ *    source span — never resolved JS. Each consumer binds a slot to its own
+ *    representation afterward (a Babel node in the compiler, a `ts.Expression`
+ *    in the LSP, raw text in Biome). This single seam is what lets one parser
+ *    serve every downstream tool.
+ *  - Directives are explicit node kinds, never stringly-typed attributes.
+ *  - Every node carries `loc`, `kind`, and (via the tree walk) a `parent`.
+ */
+/** A half-open source span `[start, end)` in template-coordinate space. */
+export interface SourceSpan {
+    start: number;
+    end: number;
+}
+/** Namespaces the parser tracks so SVG (and foreign content) lower correctly. */
+export type Namespace = 'html' | 'svg' | 'mathml';
+export type NodeKind = 'Root' | 'Element' | 'Component' | 'Fragment' | 'Text' | 'Comment' | 'Expression';
+export type AttrKind = 'Attribute' | 'PropertyBinding' | 'EventBinding' | 'RefBinding' | 'Spread' | 'IfDirective' | 'ElseDirective' | 'EachDirective' | 'BindDirective' | 'ClassDirective' | 'StyleDirective' | 'UseDirective' | 'Slot';
+/** Fields shared by every node. `parent` is wired by {@link setParents}. */
+export interface NodeBase {
+    loc: SourceSpan;
+    parent?: TemplateNode | null;
+    /** Free-form bag for downstream passes (binding results, type info, etc.). */
+    metadata?: Record<string, unknown>;
+}
+export type TemplateNode = RootNode | ElementNode | ComponentNode | FragmentNode | TextNode | CommentNode | ExpressionNode;
+/** Anything that can attach to an element/component opening tag. */
+export type AttributeLikeNode = AttributeNode | PropertyBindingNode | EventBindingNode | RefBindingNode | SpreadNode | IfDirectiveNode | ElseDirectiveNode | EachDirectiveNode | BindDirectiveNode | ClassDirectiveNode | StyleDirectiveNode | UseDirectiveNode | SlotNode;
+export interface RootNode extends NodeBase {
+    kind: 'Root';
+    children: TemplateNode[];
+}
+export interface ElementNode extends NodeBase {
+    kind: 'Element';
+    tag: string;
+    namespace: Namespace;
+    attributes: AttributeLikeNode[];
+    children: TemplateNode[];
+    selfClosing: boolean;
+    /** Raw-text element (`script`/`style`/`textarea`/`title`) — children kept verbatim. */
+    rawText: boolean;
+}
+export interface ComponentNode extends NodeBase {
+    kind: 'Component';
+    /** Capitalized name or member path (`Ctx.Provider`) as written; '' for a dynamic tag. */
+    tag: string;
+    /**
+     * Dynamic tag `<${Comp} />`: the hole index of the component expression. When
+     * set, `tag` is '' and the component identity comes from this hole — which
+     * also means the referenced binding is visible to TypeScript (no "unused").
+     */
+    tagHole: number | null;
+    attributes: AttributeLikeNode[];
+    children: TemplateNode[];
+    selfClosing: boolean;
+}
+export interface FragmentNode extends NodeBase {
+    kind: 'Fragment';
+    children: TemplateNode[];
+}
+/** Preserved verbatim (raw); whitespace normalization is a lowering concern. */
+export interface TextNode extends NodeBase {
+    kind: 'Text';
+    value: string;
+    /** Inside a raw-text element — do not whitespace-normalize when lowering. */
+    raw: boolean;
+}
+export interface CommentNode extends NodeBase {
+    kind: 'Comment';
+    value: string;
+}
+/** A `${…}` in child/text position. */
+export interface ExpressionNode extends NodeBase {
+    kind: 'Expression';
+    hole: number;
+}
+/** A single interpolation part of an attribute value. */
+export type ValuePart = {
+    text: string;
+} | {
+    hole: number;
+};
+/**
+ * `name`, `name="static"`, `name=${x}`, `name="a ${x} b"`, `?bool`, `?bool=${x}`.
+ * `value === null` is a valueless attribute (boolean true). `boolean` marks the
+ * lit `?name` prefix.
+ */
+export interface AttributeNode extends NodeBase {
+    kind: 'Attribute';
+    name: string;
+    value: AttrValue | null;
+    boolean: boolean;
+}
+export type AttrValue = {
+    kind: 'static';
+    value: string;
+} | {
+    kind: 'hole';
+    hole: number;
+} | {
+    kind: 'mixed';
+    parts: ValuePart[];
+};
+/** `.prop=${x}` — DOM property binding. */
+export interface PropertyBindingNode extends NodeBase {
+    kind: 'PropertyBinding';
+    name: string;
+    hole: number;
+}
+/**
+ * `@click=${h}`, `onClick=${h}`, or `on:click=${h}`, with optional dotted
+ * modifiers (`@click.capture.once`, `on:input.passive`). `syntax` is `'colon'`
+ * for the `on:name` form (a native listener), `'at'` for `@name`, `'on'` for the
+ * `onName` camelCase form.
+ */
+export interface EventBindingNode extends NodeBase {
+    kind: 'EventBinding';
+    /** Lowercased DOM event name (`click`). */
+    name: string;
+    syntax: 'at' | 'on' | 'colon';
+    /** Dotted modifiers: capture/once/passive (listener options) + prevent/stop/self. */
+    modifiers: string[];
+    hole: number;
+}
+/** `ref=${el}`. */
+export interface RefBindingNode extends NodeBase {
+    kind: 'RefBinding';
+    hole: number;
+}
+/** `...${props}`. */
+export interface SpreadNode extends NodeBase {
+    kind: 'Spread';
+    hole: number;
+}
+/** `if=${cond}`. */
+export interface IfDirectiveNode extends NodeBase {
+    kind: 'IfDirective';
+    hole: number;
+}
+/** `else` (valueless). */
+export interface ElseDirectiveNode extends NodeBase {
+    kind: 'ElseDirective';
+}
+/** `each=${items}` with optional `key="id"` / `key=${…}`. */
+export interface EachDirectiveNode extends NodeBase {
+    kind: 'EachDirective';
+    hole: number;
+    key: {
+        static: string;
+    } | {
+        hole: number;
+    } | null;
+}
+/** `bind:value=${signal}`. */
+export interface BindDirectiveNode extends NodeBase {
+    kind: 'BindDirective';
+    name: string;
+    hole: number;
+}
+/** `class:active=${flag}`. */
+export interface ClassDirectiveNode extends NodeBase {
+    kind: 'ClassDirective';
+    name: string;
+    hole: number;
+}
+/** `style:color=${c}`. */
+export interface StyleDirectiveNode extends NodeBase {
+    kind: 'StyleDirective';
+    name: string;
+    hole: number;
+}
+/** `use=${directive}` or `use:tooltip` (optionally `use:tooltip=${opts}`). */
+export interface UseDirectiveNode extends NodeBase {
+    kind: 'UseDirective';
+    /** Named form `use:tooltip` carries the name; bare `use=${d}` leaves it null. */
+    name: string | null;
+    hole: number | null;
+}
+/** `<slot>` element or `slot="name"` marker (reserved; wired in a later phase). */
+export interface SlotNode extends NodeBase {
+    kind: 'Slot';
+    name: string | null;
+}
+export type Severity = 'error' | 'warning';
+export interface Diagnostic {
+    code: DiagnosticCode;
+    message: string;
+    severity: Severity;
+    loc: SourceSpan;
+}
+export type DiagnosticCode = 'unclosed-tag' | 'mismatched-close-tag' | 'stray-close-tag' | 'unclosed-comment' | 'duplicate-directive' | 'else-without-if' | 'invalid-directive' | 'invalid-binding' | 'unsupported-combination';
+/** The full result of a parse: the tree plus any recovered-from problems. */
+export interface ParseResult {
+    root: RootNode;
+    diagnostics: Diagnostic[];
+}
+/** Wire every node's `parent` pointer by walking the tree once. */
+export declare function setParents(root: RootNode): RootNode;
+/** The content children of a node (attributes are not content children). */
+export declare function childrenOf(node: TemplateNode): TemplateNode[];
+//# sourceMappingURL=ast.d.ts.map

package/dist/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"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"}

package/dist/ast.js

@@ -0,0 +1,43 @@
+/**
+ * The Template AST — the stable, host-agnostic contract this package exists to
+ * produce. It is deliberately NOT the compiler's codegen IR: it models the
+ * template *as written* (every directive is an explicit node, every node keeps
+ * a source span, whitespace is preserved) so it can power the compiler AND the
+ * language server, TypeScript plugin, and Biome/formatter alike.
+ *
+ * Design rules baked into these types:
+ *  - Expression holes (`${…}`) are OPAQUE SLOTS. A node stores the hole's
+ *    integer `index` (its position in the template's `expressions[]`) and its
+ *    source span — never resolved JS. Each consumer binds a slot to its own
+ *    representation afterward (a Babel node in the compiler, a `ts.Expression`
+ *    in the LSP, raw text in Biome). This single seam is what lets one parser
+ *    serve every downstream tool.
+ *  - Directives are explicit node kinds, never stringly-typed attributes.
+ *  - Every node carries `loc`, `kind`, and (via the tree walk) a `parent`.
+ */
+// ---------------------------------------------------------------------------
+// Tree helpers
+// ---------------------------------------------------------------------------
+/** Wire every node's `parent` pointer by walking the tree once. */
+export function setParents(root) {
+    const visit = (node, parent) => {
+        node.parent = parent;
+        const kids = childrenOf(node);
+        for (const child of kids)
+            visit(child, node);
+    };
+    visit(root, null);
+    return root;
+}
+/** The content children of a node (attributes are not content children). */
+export function childrenOf(node) {
+    switch (node.kind) {
+        case 'Root':
+        case 'Element':
+        case 'Component':
+        case 'Fragment':
+            return node.children;
+        default:
+            return [];
+    }
+}

package/dist/ast.mjs

@@ -0,0 +1 @@
+function a(e){let n=(t,i)=>{t.parent=i;let o=d(t);for(let r of o)n(r,t)};return n(e,null),e}function d(e){switch(e.kind){case"Root":case"Element":case"Component":case"Fragment":return e.children;default:return[]}}export{d as childrenOf,a as setParents};

package/dist/directives.cjs

@@ -0,0 +1 @@
+"use strict";var c=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var v=Object.prototype.hasOwnProperty;var h=(e,t)=>{for(var i in t)c(e,i,{get:t[i],enumerable:!0})},b=(e,t,i,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of m(t))!v.call(e,o)&&o!==i&&c(e,o,{get:()=>t[o],enumerable:!(n=u(t,o))||n.enumerable});return e};var p=e=>b(c({},"__esModule",{value:!0}),e);var D={};h(D,{CORE_DIRECTIVES:()=>a,EVENT_MODIFIERS:()=>d,resolveAttribute:()=>f});module.exports=p(D);var d=new Set(["capture","once","passive","prevent","stop","self"]);function l(e,t){return e.value&&e.value.kind==="hole"?e.value.hole:(e.report("invalid-binding",`${t} requires an expression value: ${e.name}=\${…}`),-1)}var s=(e,t)=>({kind:"Attribute",name:t?e.name.slice(1):e.name,value:e.value,boolean:t,loc:e.loc}),a=[{id:"event",match:e=>e[0]==="@"||e.startsWith("on:")||/^on[A-Z]/.test(e),build:e=>{let t,i;e.name[0]==="@"?(t="at",i=e.name.slice(1)):e.name.startsWith("on:")?(t="colon",i=e.name.slice(3)):(t="on",i=e.name.slice(2));let[n,...o]=i.split(".");for(let r of o)d.has(r)||e.report("invalid-directive",`Unknown event modifier ".${r}" — expected one of ${[...d].join(", ")}`);return{kind:"EventBinding",name:n,syntax:t,modifiers:o,hole:l(e,"event binding"),loc:e.loc}}},{id:"bind",elementOnly:!0,match:e=>e.startsWith("bind:"),build:e=>({kind:"BindDirective",name:e.name.slice(5),hole:l(e,"two-way binding"),loc:e.loc})},{id:"class-directive",elementOnly:!0,match:e=>e.startsWith("class:"),build:e=>({kind:"ClassDirective",name:e.name.slice(6),hole:l(e,"class directive"),loc:e.loc})},{id:"style-directive",elementOnly:!0,match:e=>e.startsWith("style:"),build:e=>({kind:"StyleDirective",name:e.name.slice(6),hole:l(e,"style directive"),loc:e.loc})},{id:"use",match:e=>e==="use"||e.startsWith("use:"),build:e=>({kind:"UseDirective",name:e.name.startsWith("use:")?e.name.slice(4):null,hole:e.value&&e.value.kind==="hole"?e.value.hole:null,loc:e.loc})},{id:"if",elementOnly:!0,match:e=>e==="if",build:e=>({kind:"IfDirective",hole:l(e,"if directive"),loc:e.loc})},{id:"each",elementOnly:!0,match:e=>e==="each",build:e=>({kind:"EachDirective",hole:l(e,"each directive"),key:null,loc:e.loc})},{id:"else",elementOnly:!0,match:e=>e==="else",build:e=>(e.value!==null&&e.report("invalid-directive","`else` takes no value"),{kind:"ElseDirective",loc:e.loc})},{id:"ref",match:e=>e==="ref",build:e=>({kind:"RefBinding",hole:l(e,"ref binding"),loc:e.loc})},{id:"property",match:e=>e[0]===".",build:e=>({kind:"PropertyBinding",name:e.name.slice(1),hole:l(e,"property binding"),loc:e.loc})},{id:"boolean",match:e=>e[0]==="?",build:e=>s(e,!0)}];function f(e,t=a,i={component:!1}){for(let n of t)if(!(n.elementOnly&&i.component)&&n.match(e.name))return n.build(e);return s(e,!1)}

package/dist/directives.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The directive registry — the extensibility seam.
+ *
+ * The core parser never hard-codes what `if`, `each`, `bind:value`, `@click`,
+ * `.prop` etc. mean. It parses a raw `name[=value]` pair, then asks the registry
+ * to turn it into a typed node. Adding future syntax is therefore a new
+ * descriptor here (or registered by a downstream tool), never a change to the
+ * parser's control flow. Descriptors are tried in order; the first whose
+ * `match` returns true owns the attribute. Anything unmatched falls back to a
+ * plain {@link AttributeNode}.
+ */
+import type { AttributeLikeNode, AttrValue, Diagnostic, DiagnosticCode, SourceSpan } from './ast.js';
+/** Recognized event modifiers (`@click.capture.once`, `on:input.passive`, …). */
+export declare const EVENT_MODIFIERS: Set<string>;
+/** A parsed-but-unclassified attribute handed to the registry. */
+export interface RawAttribute {
+    /** Name exactly as written (`class`, `@click`, `bind:value`, `?disabled`). */
+    name: string;
+    nameLoc: SourceSpan;
+    /** null = valueless attribute. */
+    value: AttrValue | null;
+    loc: SourceSpan;
+    /** Emit a located diagnostic from inside a descriptor. */
+    report(code: DiagnosticCode, message: string): void;
+}
+export interface DirectiveDescriptor {
+    /** Stable id (for docs/debugging). */
+    id: string;
+    /** DOM-only sugar (`if`/`each`/`class:`…) is ignored on component tags. */
+    elementOnly?: boolean;
+    match(name: string): boolean;
+    build(raw: RawAttribute): AttributeLikeNode;
+}
+/** Where an attribute sits — a native element or a component tag. */
+export interface AttrContext {
+    component: boolean;
+}
+/**
+ * The built-in directives. Order matters: prefix forms are matched before the
+ * plain-attribute fallback. Downstream tools can prepend their own.
+ */
+export declare const CORE_DIRECTIVES: DirectiveDescriptor[];
+/**
+ * Resolve a raw attribute to a typed node using `directives` (defaults to the
+ * core set). `each`/`key` are handled by the parser afterward because `key` is
+ * a sibling attribute that folds into the preceding `each` node.
+ */
+export declare function resolveAttribute(raw: RawAttribute, directives?: DirectiveDescriptor[], ctx?: AttrContext): AttributeLikeNode;
+export type { Diagnostic };
+//# sourceMappingURL=directives.d.ts.map

package/dist/directives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../src/directives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EACV,iBAAiB,EAEjB,SAAS,EAGT,UAAU,EACV,cAAc,EAOd,UAAU,EAGX,MAAM,UAAU,CAAC;AAElB,iFAAiF;AACjF,eAAO,MAAM,eAAe,aAAqE,CAAC;AAElG,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,CAAC;IACpB,kCAAkC;IAClC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,GAAG,EAAE,UAAU,CAAC;IAChB,0DAA0D;IAC1D,MAAM,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,iBAAiB,CAAC;CAC7C;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,OAAO,CAAC;CACpB;AAkBD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,mBAAmB,EA2IhD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,YAAY,EACjB,UAAU,GAAE,mBAAmB,EAAoB,EACnD,GAAG,GAAE,WAAkC,GACtC,iBAAiB,CAMnB;AAED,YAAY,EAAE,UAAU,EAAE,CAAC"}

package/dist/directives.js

@@ -0,0 +1,185 @@
+/** Recognized event modifiers (`@click.capture.once`, `on:input.passive`, …). */
+export const EVENT_MODIFIERS = new Set(['capture', 'once', 'passive', 'prevent', 'stop', 'self']);
+/** Pull the single hole out of a value, or report if the shape is wrong. */
+function requireHole(raw, what) {
+    if (raw.value && raw.value.kind === 'hole')
+        return raw.value.hole;
+    raw.report('invalid-binding', `${what} requires an expression value: ${raw.name}=\${…}`);
+    // Recovery: -1 marks a missing hole so the tree stays well-formed.
+    return -1;
+}
+const attribute = (raw, boolean) => ({
+    kind: 'Attribute',
+    name: boolean ? raw.name.slice(1) : raw.name,
+    value: raw.value,
+    boolean,
+    loc: raw.loc,
+});
+/**
+ * The built-in directives. Order matters: prefix forms are matched before the
+ * plain-attribute fallback. Downstream tools can prepend their own.
+ */
+export const CORE_DIRECTIVES = [
+    // Events: `@click=${h}`, `on:click=${h}` (native), `onClick=${h}`, each with
+    // optional dotted modifiers (`@click.capture.once`, `on:input.passive`).
+    {
+        id: 'event',
+        match: (n) => n[0] === '@' || n.startsWith('on:') || /^on[A-Z]/.test(n),
+        build: (raw) => {
+            let syntax;
+            let rest;
+            if (raw.name[0] === '@') {
+                syntax = 'at';
+                rest = raw.name.slice(1);
+            }
+            else if (raw.name.startsWith('on:')) {
+                syntax = 'colon';
+                rest = raw.name.slice(3);
+            }
+            else {
+                syntax = 'on';
+                rest = raw.name.slice(2);
+            }
+            // Dotted modifiers apply to the @/on: forms; the camelCase name has no dots.
+            const [name, ...modifiers] = rest.split('.');
+            for (const m of modifiers) {
+                if (!EVENT_MODIFIERS.has(m)) {
+                    raw.report('invalid-directive', `Unknown event modifier ".${m}" — expected one of ${[...EVENT_MODIFIERS].join(', ')}`);
+                }
+            }
+            return {
+                kind: 'EventBinding',
+                name,
+                syntax,
+                modifiers,
+                hole: requireHole(raw, 'event binding'),
+                loc: raw.loc,
+            };
+        },
+    },
+    // Two-way binding: `bind:value=${signal}`.
+    {
+        id: 'bind',
+        elementOnly: true,
+        match: (n) => n.startsWith('bind:'),
+        build: (raw) => ({
+            kind: 'BindDirective',
+            name: raw.name.slice('bind:'.length),
+            hole: requireHole(raw, 'two-way binding'),
+            loc: raw.loc,
+        }),
+    },
+    // Dynamic class toggle: `class:active=${flag}`.
+    {
+        id: 'class-directive',
+        elementOnly: true,
+        match: (n) => n.startsWith('class:'),
+        build: (raw) => ({
+            kind: 'ClassDirective',
+            name: raw.name.slice('class:'.length),
+            hole: requireHole(raw, 'class directive'),
+            loc: raw.loc,
+        }),
+    },
+    // Dynamic style: `style:color=${c}`.
+    {
+        id: 'style-directive',
+        elementOnly: true,
+        match: (n) => n.startsWith('style:'),
+        build: (raw) => ({
+            kind: 'StyleDirective',
+            name: raw.name.slice('style:'.length),
+            hole: requireHole(raw, 'style directive'),
+            loc: raw.loc,
+        }),
+    },
+    // Custom directive: `use=${d}` or `use:tooltip[=${opts}]`.
+    {
+        id: 'use',
+        match: (n) => n === 'use' || n.startsWith('use:'),
+        build: (raw) => {
+            const named = raw.name.startsWith('use:');
+            return {
+                kind: 'UseDirective',
+                name: named ? raw.name.slice('use:'.length) : null,
+                hole: raw.value && raw.value.kind === 'hole' ? raw.value.hole : null,
+                loc: raw.loc,
+            };
+        },
+    },
+    // Conditional rendering: `if=${cond}`.
+    {
+        id: 'if',
+        elementOnly: true,
+        match: (n) => n === 'if',
+        build: (raw) => ({
+            kind: 'IfDirective',
+            hole: requireHole(raw, 'if directive'),
+            loc: raw.loc,
+        }),
+    },
+    // Loop rendering: `each=${items}` (a sibling `key` folds in at parse time).
+    {
+        id: 'each',
+        elementOnly: true,
+        match: (n) => n === 'each',
+        build: (raw) => ({
+            kind: 'EachDirective',
+            hole: requireHole(raw, 'each directive'),
+            key: null,
+            loc: raw.loc,
+        }),
+    },
+    // `else` (valueless).
+    {
+        id: 'else',
+        elementOnly: true,
+        match: (n) => n === 'else',
+        build: (raw) => {
+            if (raw.value !== null)
+                raw.report('invalid-directive', '`else` takes no value');
+            return { kind: 'ElseDirective', loc: raw.loc };
+        },
+    },
+    // Ref binding: `ref=${el}`.
+    {
+        id: 'ref',
+        match: (n) => n === 'ref',
+        build: (raw) => ({
+            kind: 'RefBinding',
+            hole: requireHole(raw, 'ref binding'),
+            loc: raw.loc,
+        }),
+    },
+    // Property binding: `.currentTime=${t}`.
+    {
+        id: 'property',
+        match: (n) => n[0] === '.',
+        build: (raw) => ({
+            kind: 'PropertyBinding',
+            name: raw.name.slice(1),
+            hole: requireHole(raw, 'property binding'),
+            loc: raw.loc,
+        }),
+    },
+    // Boolean attribute (lit `?disabled`): a plain attribute flagged boolean.
+    {
+        id: 'boolean',
+        match: (n) => n[0] === '?',
+        build: (raw) => attribute(raw, true),
+    },
+];
+/**
+ * Resolve a raw attribute to a typed node using `directives` (defaults to the
+ * core set). `each`/`key` are handled by the parser afterward because `key` is
+ * a sibling attribute that folds into the preceding `each` node.
+ */
+export function resolveAttribute(raw, directives = CORE_DIRECTIVES, ctx = { component: false }) {
+    for (const d of directives) {
+        if (d.elementOnly && ctx.component)
+            continue; // sugar is DOM-only
+        if (d.match(raw.name))
+            return d.build(raw);
+    }
+    return attribute(raw, false);
+}

package/dist/directives.mjs

@@ -0,0 +1 @@
+var d=new Set(["capture","once","passive","prevent","stop","self"]);function i(e,t){return e.value&&e.value.kind==="hole"?e.value.hole:(e.report("invalid-binding",`${t} requires an expression value: ${e.name}=\${…}`),-1)}var r=(e,t)=>({kind:"Attribute",name:t?e.name.slice(1):e.name,value:e.value,boolean:t,loc:e.loc}),s=[{id:"event",match:e=>e[0]==="@"||e.startsWith("on:")||/^on[A-Z]/.test(e),build:e=>{let t,n;e.name[0]==="@"?(t="at",n=e.name.slice(1)):e.name.startsWith("on:")?(t="colon",n=e.name.slice(3)):(t="on",n=e.name.slice(2));let[o,...l]=n.split(".");for(let c of l)d.has(c)||e.report("invalid-directive",`Unknown event modifier ".${c}" — expected one of ${[...d].join(", ")}`);return{kind:"EventBinding",name:o,syntax:t,modifiers:l,hole:i(e,"event binding"),loc:e.loc}}},{id:"bind",elementOnly:!0,match:e=>e.startsWith("bind:"),build:e=>({kind:"BindDirective",name:e.name.slice(5),hole:i(e,"two-way binding"),loc:e.loc})},{id:"class-directive",elementOnly:!0,match:e=>e.startsWith("class:"),build:e=>({kind:"ClassDirective",name:e.name.slice(6),hole:i(e,"class directive"),loc:e.loc})},{id:"style-directive",elementOnly:!0,match:e=>e.startsWith("style:"),build:e=>({kind:"StyleDirective",name:e.name.slice(6),hole:i(e,"style directive"),loc:e.loc})},{id:"use",match:e=>e==="use"||e.startsWith("use:"),build:e=>({kind:"UseDirective",name:e.name.startsWith("use:")?e.name.slice(4):null,hole:e.value&&e.value.kind==="hole"?e.value.hole:null,loc:e.loc})},{id:"if",elementOnly:!0,match:e=>e==="if",build:e=>({kind:"IfDirective",hole:i(e,"if directive"),loc:e.loc})},{id:"each",elementOnly:!0,match:e=>e==="each",build:e=>({kind:"EachDirective",hole:i(e,"each directive"),key:null,loc:e.loc})},{id:"else",elementOnly:!0,match:e=>e==="else",build:e=>(e.value!==null&&e.report("invalid-directive","`else` takes no value"),{kind:"ElseDirective",loc:e.loc})},{id:"ref",match:e=>e==="ref",build:e=>({kind:"RefBinding",hole:i(e,"ref binding"),loc:e.loc})},{id:"property",match:e=>e[0]===".",build:e=>({kind:"PropertyBinding",name:e.name.slice(1),hole:i(e,"property binding"),loc:e.loc})},{id:"boolean",match:e=>e[0]==="?",build:e=>r(e,!0)}];function a(e,t=s,n={component:!1}){for(let o of t)if(!(o.elementOnly&&n.component)&&o.match(e.name))return o.build(e);return r(e,!1)}export{s as CORE_DIRECTIVES,d as EVENT_MODIFIERS,a as resolveAttribute};