@arikajs/view 0.0.4 → 0.0.6

package/README.md

@@ -1,246 +1,144 @@
-## Arika View
+# Arika View v1.0 💎
 
-`@arikajs/view` is the server-side rendering (SSR) and template engine for the ArikaJS framework.
-
-It allows developers to render dynamic HTML using a clean, expressive template syntax inspired by modern server frameworks — while remaining lightweight, secure, and framework-agnostic.
-
-```ts
-import { View } from '@arikajs/view';
-
-const view = new View({
-    viewsPath: './views',
-    cachePath: './storage/views',
-});
-
-const html = await view.render('home', {
-    title: 'Welcome to ArikaJS',
-});
-```
-
-The View package enables presentation logic in ArikaJS, transforming templates into clean HTML output with safe escaping and high performance.
-
----
-
-### Status
-
-- **Stage**: Experimental / v0.x
-- **Scope (v0.x)**:
-  - Template compilation & rendering
-  - Layout & section management
-  - Basic control structures (`@if`, `@for`)
-  - Safe output escaping
-  - Template caching
-- **Out of scope (for this package)**:
-  - HTTP request/response handling (see `@arikajs/http`)
-  - Route matching (see `@arikajs/router`)
-  - Authentication logic
-
----
-
-## 🎯 Purpose
-
-The View package is the presentation layer of the ArikaJS ecosystem. It is responsible for:
-- Rendering templates into HTML
-- Managing layouts and partials
-- Escaping output safely
-- Supporting control structures
-- Providing a foundation for Web views, Email templates, and Error pages.
+`@arikajs/view` is a production-grade, TypeScript-first template engine designed for the ArikaJS ecosystem. It combines the power of modern JS with a clean, expressive syntax inspired by Laravel Blade, but built natively for the Node.js event loop.
 
 ---
 
-## 🧠 Responsibilities
+## 🚀 Core Architecture
 
-### ✅ What Arika View Does
-- Compile templates into renderable functions
-- Render templates with dynamic data
-- Support layouts, sections, and includes
-- Provide basic control structures (`if`, `for`)
-- Escape output by default
-- Cache compiled templates for performance
-
-### ❌ What Arika View Does NOT Do
-- Handle HTTP requests or responses
-- Match routes
-- Manage authentication
-- Execute business logic
+Arika View v1 features a completely rewritten compiler stack:
+- **Lexer**: Intelligent tokenization of `.ark` files.
+- **Parser**: Builds a robust Abstract Syntax Tree (AST) for complex nesting.
+- **Directive Registry**: Modular system for extending template logic.
+- **Code Generator**: Produces highly optimized, async-ready JavaScript.
 
 ---
 
-## 🧬 Rendering Flow
-
-```
-Controller
-  ↓
-View.render()
-  ↓
-Template Compiler
-  ↓
-Compiled Template
-  ↓
-HTML Output
-```
-
----
-
-## Features
-
-- **Simple, expressive template syntax**
-  - Clean tags for logic and output.
-- **Layout & section support**
-  - Powerful inheritance model for UI consistency.
-- **Partial / include support**
-  - Modularize your templates into reusable components.
-- **Safe output escaping**
-  - Protection against XSS by default.
-- **Custom directives**
-  - Extend the engine with your own syntax.
-- **Template caching**
-  - High-performance rendering via pre-compiled templates.
-
----
+## ✨ Key Features
 
-## Installation
-
-```bash
-npm install @arikajs/view
-# or
-yarn add @arikajs/view
-# or
-pnpm add @arikajs/view
-```
-
----
-
-## 🧩 Template Syntax
-
-### Variable Output
+### 1️⃣ Pure JavaScript Expressions
+Arika View embraces JavaScript. No need to learn a limited expression language — if it's valid JS, it's valid in your template.
 ```html
-<h1>{{ title }}</h1>
-```
-*Escaped by default.*
-
-### Raw Output
-```html
-{!! html !!}
-```
-
-### Conditionals
-```html
-@if (user)
-    <p>Welcome, {{ user.name }}</p>
+@if (user?.isAdmin && posts.length > 0)
+    <p>Welcome back, Admin!</p>
 @endif
 ```
 
-### Loops
-```html
-@for (item in items)
-    <li>{{ item }}</li>
-@endfor
+### 2️⃣ Type-Safe View Data
+Leverage TypeScript's power in your views.
+```ts
+interface HomeData {
+    title: string;
+    user: { name: string };
+}
+
+await view.render<HomeData>('home', {
+    title: 'ArikaJS',
+    user: { name: 'Prakash' }
+});
 ```
 
-### Includes
+### 3️⃣ Modern Components (`<x-`)
+Stop using clunky syntax. Use modern, HTML-like components.
 ```html
-@include('partials.header')
+<x-alert type="danger" :dismissible="true">
+    <x-slot name="title">Warning!</x-slot>
+    Something went wrong.
+</x-alert>
 ```
 
-### Layouts & Sections
+### 4️⃣ Smart Caching & Dev Mode
+- **Hash-based Invalidation**: Templates only recompile when content actually changes.
+- **Dev Mode**: Real-time recompilation and enhanced error stack traces with file/line references.
+- **Production Mode**: Minified output and aggressive in-memory caching.
 
-**layout.html**
+### 5️⃣ Fragments (HTMX Ready ⚡)
+Render only a specific part of your template — perfect for HTMX or partial reloads.
 ```html
-<html>
-<body>
-    @yield('content')
-</body>
-</html>
+@fragment('sidebar')
+    <nav>...</nav>
+@endfragment
 ```
-
-**page.html**
-```html
-@extends('layout')
-
-@section('content')
-    <h1>Hello World</h1>
-@endsection
+```ts
+await view.renderFragment('dashboard', 'sidebar');
 ```
 
 ---
 
-## 🔌 Usage
+## 🛠 Directives Reference
+
+| Directive | Description |
+|-----------|-------------|
+| `@if`, `@elseif`, `@else` | Standard conditional logic. |
+| `@unless` | Inverse of `@if`. |
+| `@for` | Standard JS loop. |
+| `@each(view, data, item, empty)` | Render a view for each item in a collection. |
+| `@switch`, `@case`, `@default` | Switch statement support. |
+| `@break`, `@continue` | Control loop execution. |
+| `@auth`, `@guest` | Conditional rendering based on user session. |
+| `@once` | Ensure a block is only rendered once per request. |
+| `@verbatim` | Stop parsing content inside the block. |
+| `@push`, `@stack`, `@prepend` | Manage assets and scripts across layouts. |
+| `@await(promise)` | Native async support inside templates. |
 
-### Basic Rendering
-```ts
-import { View } from '@arikajs/view';
+---
 
-const view = new View({
-    viewsPath: './views',
-    cachePath: './storage/views',
-});
+## 🔌 Advanced Ecosystem
 
-const html = await view.render('home', {
-    title: 'Welcome to ArikaJS',
+### View Composers
+Inject data into specific views automatically before they are rendered.
+```ts
+view.composer('dashboard', async (data) => {
+    data.notifications = await getNotifications();
 });
 ```
 
-### Controller Integration
-*(Typically provided by the HTTP Kernel)*
+### Global Helpers
+Define custom functions accessible in every template.
 ```ts
-return view('dashboard', {
-    user,
-});
+view.helper('formatDate', (date) => new Intl.DateTimeFormat().format(date));
 ```
+Usage: `{{ formatDate(user.createdAt) }}`
 
----
-
-## ⚙️ Configuration Options
-
+### Custom Directives API
+Extend Arika View with your own powerful directives.
 ```ts
-{
-  viewsPath: string;           // Directory containing templates
-  cachePath?: string;          // Directory for compiled templates
-  extension?: '.html' | '.ark'; // Template file extension
-  cache?: boolean;             // Enable/disable caching
-}
+view.directive('uppercase', (exp) => `_output += String(${exp}).toUpperCase();`);
 ```
 
 ---
 
-## 🧱 Project Structure
-
-- `src/`
-  - `View.ts` – Main entry point
-  - `Engine.ts` – Execution context
-  - `Compiler.ts` – Template string to JS compiler
-  - `Template.ts` – Template resolution and state
-  - `Directives/` – Built-in controls
-    - `If.ts`, `For.ts`, `Include.ts`, `Section.ts`
-  - `index.ts` – Public exports
-- `tests/` – Unit and integration tests
-- `package.json`
-- `tsconfig.json`
-- `README.md`
-- `LICENSE`
-
----
+## 📁 File Structure & Extension
 
-## Versioning & Stability
+Arika View exclusively uses the `.ark.html` extension for all templates.
 
-- While in **v0.x**, the API may change between minor versions.
-- Once the API stabilizes, `@arikajs/view` will move to **v1.0** and follow **semver** strictly.
+```text
+resources/views/
+├── layouts/
+│   └── app.ark.html
+├── auth/
+│   ├── login.ark.html
+│   └── register.ark.html
+└── welcome.ark.html
+```
 
 ---
 
-## Contributing
+## 💻 CLI Integration
 
-Contributions are welcome! Please ensure all pull requests include tests and follow the project's coding standards.
+Generate views instantly with the Arika CLI:
+```bash
+arika make:view home
+# Generates resources/views/home.ark.html
+```
 
 ---
 
-## License
+## 🧠 Philosophy
 
-`@arikajs/view` is open-sourced software licensed under the **MIT license**.
+> "Arika View turns your templates into native Node.js code, making UI rendering as fast as the engine itself."
 
 ---
 
-## 🧠 Philosophy
-
-> “Presentation is a reflection of logic, not a home for it.”
+## License
+MIT

package/dist/Compiler/AST.d.ts

@@ -0,0 +1,34 @@
+export declare enum NodeType {
+    Root = "Root",
+    Text = "Text",
+    Expression = "Expression",
+    RawExpression = "RawExpression",
+    Directive = "Directive"
+}
+export interface Node {
+    type: NodeType;
+    [key: string]: any;
+}
+export interface RootNode extends Node {
+    type: NodeType.Root;
+    children: Node[];
+}
+export interface TextNode extends Node {
+    type: NodeType.Text;
+    content: string;
+}
+export interface ExpressionNode extends Node {
+    type: NodeType.Expression;
+    content: string;
+}
+export interface RawExpressionNode extends Node {
+    type: NodeType.RawExpression;
+    content: string;
+}
+export interface DirectiveNode extends Node {
+    type: NodeType.Directive;
+    name: string;
+    expression: string | null;
+    children?: Node[];
+}
+//# sourceMappingURL=AST.d.ts.map

package/dist/Compiler/AST.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AST.d.ts","sourceRoot":"","sources":["../../src/Compiler/AST.ts"],"names":[],"mappings":"AAAA,oBAAY,QAAQ;IAChB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,UAAU,eAAe;IACzB,aAAa,kBAAkB;IAC/B,SAAS,cAAc;CAC1B;AAED,MAAM,WAAW,IAAI;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACtB;AAED,MAAM,WAAW,QAAS,SAAQ,IAAI;IAClC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;IACpB,QAAQ,EAAE,IAAI,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,QAAS,SAAQ,IAAI;IAClC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAe,SAAQ,IAAI;IACxC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAkB,SAAQ,IAAI;IAC3C,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAc,SAAQ,IAAI;IACvC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC;CACrB"}

package/dist/Compiler/AST.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeType = void 0;
+var NodeType;
+(function (NodeType) {
+    NodeType["Root"] = "Root";
+    NodeType["Text"] = "Text";
+    NodeType["Expression"] = "Expression";
+    NodeType["RawExpression"] = "RawExpression";
+    NodeType["Directive"] = "Directive";
+})(NodeType || (exports.NodeType = NodeType = {}));
+//# sourceMappingURL=AST.js.map

package/dist/Compiler/AST.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AST.js","sourceRoot":"","sources":["../../src/Compiler/AST.ts"],"names":[],"mappings":";;;AAAA,IAAY,QAMX;AAND,WAAY,QAAQ;IAChB,yBAAa,CAAA;IACb,yBAAa,CAAA;IACb,qCAAyB,CAAA;IACzB,2CAA+B,CAAA;IAC/B,mCAAuB,CAAA;AAC3B,CAAC,EANW,QAAQ,wBAAR,QAAQ,QAMnB"}

package/dist/Compiler/CodeGenerator.d.ts

@@ -0,0 +1,11 @@
+import { RootNode } from './AST';
+import { DirectiveRegistry } from './DirectiveRegistry';
+export declare class CodeGenerator {
+    private registry;
+    constructor(registry: DirectiveRegistry);
+    generate(root: RootNode): string;
+    private generateNodes;
+    private generateNode;
+    private cleanExpression;
+}
+//# sourceMappingURL=CodeGenerator.d.ts.map

package/dist/Compiler/CodeGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeGenerator.d.ts","sourceRoot":"","sources":["../../src/Compiler/CodeGenerator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAA8E,MAAM,OAAO,CAAC;AAC7G,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,qBAAa,aAAa;IACtB,OAAO,CAAC,QAAQ,CAAoB;gBAExB,QAAQ,EAAE,iBAAiB;IAIhC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM;IAUvC,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,YAAY;IAiCpB,OAAO,CAAC,eAAe;CAK1B"}

package/dist/Compiler/CodeGenerator.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodeGenerator = void 0;
+const AST_1 = require("./AST");
+class CodeGenerator {
+    constructor(registry) {
+        this.registry = registry;
+    }
+    generate(root) {
+        let jsCode = 'let _output = "";\n';
+        jsCode += 'const _escape = (val) => String(val ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/\\\'/g, "&#39;");\n';
+        jsCode += this.generateNodes(root.children);
+        jsCode += 'return _output;';
+        return jsCode;
+    }
+    generateNodes(nodes) {
+        return nodes.map(node => this.generateNode(node)).join('\n');
+    }
+    generateNode(node) {
+        switch (node.type) {
+            case AST_1.NodeType.Text:
+                const text = node.content
+                    .replace(/\\/g, '\\\\')
+                    .replace(/`/g, '\\`')
+                    .replace(/\${/g, '\\${');
+                return `_output += \`${text}\`;`;
+            case AST_1.NodeType.Expression:
+                return `_output += _escape(${this.cleanExpression(node.content)});`;
+            case AST_1.NodeType.RawExpression:
+                return `_output += (${this.cleanExpression(node.content)});`;
+            case AST_1.NodeType.Directive:
+                const dir = node;
+                const childrenCode = dir.children ? this.generateNodes(dir.children) : '';
+                const result = this.registry.handle(dir.name, dir.expression, childrenCode);
+                if (result === null) {
+                    // Fallback for unknown directives (e.g., CSS @media, @keyframes)
+                    const originalText = `@${dir.name}${dir.expression ? '(' + dir.expression + ')' : ''}`;
+                    const sanitized = originalText.replace(/`/g, '\\`').replace(/\${/g, '\\${');
+                    return `_output += \`${sanitized}\`;\n${childrenCode}`;
+                }
+                return result;
+            default:
+                return '';
+        }
+    }
+    cleanExpression(exp) {
+        // Strip leading $ from variables to support Laravel-style {{ $var }}
+        // This regex finds $ followed by an identifier and replaces it with just the identifier
+        return exp.replace(/(^|[^a-zA-Z0-9_])\$([a-zA-Z_][a-zA-Z0-9_]*)/g, '$1$2');
+    }
+}
+exports.CodeGenerator = CodeGenerator;
+//# sourceMappingURL=CodeGenerator.js.map

package/dist/Compiler/CodeGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeGenerator.js","sourceRoot":"","sources":["../../src/Compiler/CodeGenerator.ts"],"names":[],"mappings":";;;AAAA,+BAA6G;AAG7G,MAAa,aAAa;IAGtB,YAAY,QAA2B;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC7B,CAAC;IAEM,QAAQ,CAAC,IAAc;QAC1B,IAAI,MAAM,GAAG,qBAAqB,CAAC;QACnC,MAAM,IAAI,oKAAoK,CAAC;QAE/K,MAAM,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE5C,MAAM,IAAI,iBAAiB,CAAC;QAC5B,OAAO,MAAM,CAAC;IAClB,CAAC;IAEO,aAAa,CAAC,KAAa;QAC/B,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjE,CAAC;IAEO,YAAY,CAAC,IAAU;QAC3B,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAChB,KAAK,cAAQ,CAAC,IAAI;gBACd,MAAM,IAAI,GAAI,IAAiB,CAAC,OAAO;qBAClC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;qBACtB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;qBACpB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAC7B,OAAO,gBAAgB,IAAI,KAAK,CAAC;YAErC,KAAK,cAAQ,CAAC,UAAU;gBACpB,OAAO,sBAAsB,IAAI,CAAC,eAAe,CAAE,IAAuB,CAAC,OAAO,CAAC,IAAI,CAAC;YAE5F,KAAK,cAAQ,CAAC,aAAa;gBACvB,OAAO,eAAe,IAAI,CAAC,eAAe,CAAE,IAA0B,CAAC,OAAO,CAAC,IAAI,CAAC;YAExF,KAAK,cAAQ,CAAC,SAAS;gBACnB,MAAM,GAAG,GAAG,IAAqB,CAAC;gBAClC,MAAM,YAAY,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1E,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;gBAE5E,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;oBAClB,iEAAiE;oBACjE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;oBACvF,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;oBAC5E,OAAO,gBAAgB,SAAS,QAAQ,YAAY,EAAE,CAAC;gBAC3D,CAAC;gBACD,OAAO,MAAM,CAAC;YAElB;gBACI,OAAO,EAAE,CAAC;QAClB,CAAC;IACL,CAAC;IAEO,eAAe,CAAC,GAAW;QAC/B,qEAAqE;QACrE,wFAAwF;QACxF,OAAO,GAAG,CAAC,OAAO,CAAC,8CAA8C,EAAE,MAAM,CAAC,CAAC;IAC/E,CAAC;CACJ;AA3DD,sCA2DC"}

package/dist/Compiler/DirectiveRegistry.d.ts

@@ -0,0 +1,10 @@
+export type DirectiveHandler = (expression: string | null, children?: string) => string;
+export declare class DirectiveRegistry {
+    private directives;
+    constructor();
+    register(name: string, handler: DirectiveHandler): void;
+    has(name: string): boolean;
+    handle(name: string, expression: string | null, children?: string): string | null;
+    private registerDefaultDirectives;
+}
+//# sourceMappingURL=DirectiveRegistry.d.ts.map

package/dist/Compiler/DirectiveRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DirectiveRegistry.d.ts","sourceRoot":"","sources":["../../src/Compiler/DirectiveRegistry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;AAExF,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,UAAU,CAA4C;;IAMvD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAIvD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAQxF,OAAO,CAAC,yBAAyB;CAyNpC"}