@lithent/lithent-template-parser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 superlucky84
+
+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,159 @@
+# Lithent Template Parser
+
+Lithent Template Parser converts Lithent-specific template syntax into plain
+JavaScript `h()` calls. The compiler powers both the standalone parser APIs and
+any tooling that needs to transform JSX-like markup into Lithent render
+functions.
+
+Lithent templates look familiar to JSX but are intentionally independent. They
+offer a concise declarative layer tuned for Lithent’s render pipeline—directives
+(`l-if`, `l-for`), fragments, and interpolation all compile away to predictable
+`h()` calls without relying on the JSX transform.
+
+> **Status:** Experimental. APIs may change without notice while the parser
+> ecosystem stabilises.
+
+## Highlights
+
+- **End-to-end pipeline** – lexer → parser → transformer → code generator with
+  TypeScript definitions for every stage.
+- **Document transformer** – `transformDocument()` scans an entire source file,
+  replaces inline templates, and returns code plus optional source maps.
+- **Directive support** – `l-if`, `l-else-if`, `l-else`, `l-for`, fragments,
+  refs, interpolations, event handlers, and boolean/static/dynamic props.
+- **Batteries included** – over 90 Vitest specs, playground, and tree-shakable
+  exports for advanced tooling.
+
+## Installation
+
+```bash
+pnpm add @lithent/lithent-template-parser
+```
+
+## Quick Start
+
+```ts
+import { compile } from '@lithent/lithent-template-parser';
+
+const template = `
+  <div class="todo-list">
+    <h2>Todos ({todos.length})</h2>
+    <ul>
+      <li l-for={(todo, index) in todos}>
+        <span class="index">{index + 1}.</span>
+        <span>{todo.text}</span>
+      </li>
+    </ul>
+  </div>
+`;
+
+const result = compile(template);
+console.log(result.code);
+```
+
+Output:
+
+```js
+h('div', { class: 'todo-list' },
+  h('h2', null, 'Todos (', todos.length, ')'),
+  h('ul', null,
+    (todos).map((todo, index) =>
+      h('li', null,
+        h('span', { class: 'index' }, index + 1, '.'),
+        h('span', null, todo.text)
+      )
+    )
+  )
+);
+```
+
+## Document Transformation
+
+The `docPipe` helpers expose a higher-level API for tooling such as the Vite
+plugin:
+
+```ts
+import { transformDocument } from '@lithent/lithent-template-parser';
+
+const source = `
+const View = () => (
+  <section class="profile">
+    <Avatar l-if={user.avatar} src={user.avatar} />
+    <strong>{user.name}</strong>
+    <p l-else>No avatar</p>
+  </section>
+);
+`;
+
+const { code, map, transformed } = transformDocument(source, {
+  source: 'profile.ltsx',
+  generateSourceMap: true,
+});
+
+console.log(transformed); // true
+console.log(code);
+```
+
+The result keeps non-template code untouched while replacing all template
+regions with generated `h()` calls. When `generateSourceMap` is `true`, the
+returned source map is compatible with downstream tooling (e.g. Vite, Rollup).
+
+## Template Syntax Overview
+
+| Feature | Example |
+| --- | --- |
+| HTML elements | `<div class="box">{title}</div>` |
+| Components | `<TodoList items={todos} />` |
+| Static attributes | `<button class="primary">` |
+| Dynamic attributes | `<div class={className} id={nodeId}>` |
+| Boolean attributes | `<input disabled checked />` |
+| Event handlers | `<button onClick={handleClick}>` |
+| Text interpolation | `Hello {user.name}!` |
+| Conditionals | `<span l-if={done}>Done</span><span l-else>Pending</span>` |
+| Loops | `<li l-for={(todo, i) in todos}>{i}: {todo.text}</li>` |
+| Fragments | `<><Header /><Content /></>` |
+
+All directives can be nested and combined. Invalid syntax produces descriptive
+errors with line and column numbers.
+
+## CLI & Playground
+
+```bash
+cd packages/lithentTemplateParser
+pnpm dev
+```
+
+The Vite playground exposes a live editor that shows the generated code, AST,
+token stream, and the rendered Lithent component. In the browser console you can
+call `compile()`, `transformDocument()`, or `tokenize()` directly for faster
+experimentation.
+
+## Architecture
+
+```
+Template String
+      ↓
+    Lexer     (tokenize)
+      ↓
+   Parser     (AST)
+      ↓
+ Transform    (optimise + directive handling)
+      ↓
+  Codegen     (h() calls)
+```
+
+Every stage is exported so you can plug custom transforms, inspect the AST, or
+hook into the pipeline from other tooling.
+
+## Testing
+
+```bash
+pnpm --filter @lithent/lithent-template-parser test
+```
+
+Vitest covers lexing, parsing, directive expansion, code generation, and
+document transforms.
+
+## License
+
+MIT © Lithent contributors

package/dist/codegen/createElement.d.ts

@@ -0,0 +1,10 @@
+import { RootNode } from '../parser/ast';
+/**
+ * Generate JavaScript code from AST
+ */
+export declare function generate(ast: RootNode, options?: GenerateOptions): string;
+export interface GenerateOptions {
+    templateFactory?: string;
+    templateFragmentFactory?: string;
+}
+export declare function formatCode(code: string): string;

package/dist/codegen/index.d.ts

@@ -0,0 +1 @@
+export * from './createElement';

package/dist/compiler.d.ts

@@ -0,0 +1,26 @@
+import { TransformOptions } from './transform';
+import { GenerateOptions } from './codegen';
+/**
+ * Compile a Lithent template to JavaScript code
+ */
+export declare function compile(template: string, options?: CompileOptions): CompileResult;
+export interface CompileOptions {
+    transform?: TransformOptions;
+    generate?: GenerateOptions;
+}
+export interface CompileResult {
+    code: string;
+    ast: any;
+    errors: CompileError[];
+}
+export interface CompileError {
+    message: string;
+    line: number;
+    column: number;
+}
+export * from './parser/tokens';
+export * from './parser/lexer';
+export * from './parser/parser';
+export * from './parser/ast';
+export * from './transform';
+export * from './codegen';

package/dist/docPipe/index.d.ts

@@ -0,0 +1,40 @@
+import { type SourceMap } from 'magic-string';
+import { type CompileError, type CompileOptions } from '../compiler';
+import { scanTemplates, type TemplateMatch } from './scan';
+export interface DocumentTransformOptions {
+    /**
+     * Include original source name in generated source map.
+     */
+    source?: string;
+    /**
+     * Emit a source map when true.
+     */
+    generateSourceMap?: boolean;
+    /**
+     * Forwarded compile options for each template block.
+     */
+    compileOptions?: CompileOptions;
+}
+export interface DocumentTransformError {
+    match: TemplateMatch;
+    error: CompileError;
+}
+export interface DocumentTransformResult {
+    code: string;
+    map: SourceMap | null;
+    /**
+     * `true` when at least one replacement succeeded.
+     */
+    transformed: boolean;
+    /**
+     * Errors produced while compiling templates.
+     */
+    errors: DocumentTransformError[];
+    /**
+     * All template matches discovered in the source.
+     */
+    matches: TemplateMatch[];
+}
+export declare const transformDocument: (source: string, options?: DocumentTransformOptions) => DocumentTransformResult;
+export { scanTemplates };
+export type { TemplateMatch };

package/dist/docPipe/scan.d.ts

@@ -0,0 +1,6 @@
+export interface TemplateMatch {
+    start: number;
+    end: number;
+    snippet: string;
+}
+export declare const scanTemplates: (code: string) => TemplateMatch[];

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lithent Template Parser
+ * A Vue-like template parser for Lithent
+ */
+export { compile } from './compiler';
+export type { CompileOptions, CompileResult, CompileError } from './compiler';
+export * from './parser/tokens';
+export * from './parser/lexer';
+export * from './parser/parser';
+export * from './parser/ast';
+export * from './transform';
+export * from './codegen';
+export * from './docPipe';