@trustme24/flext 1.10.2 → 1.10.4

package/README.md

@@ -1,64 +1,241 @@
-## Flext
+# Flext
 
 [![Static Badge](https://img.shields.io/badge/GitHub-Star%20%281%29-yellow?logo=github)](https://github.com/TrustMe-kz/flext)
-[![Static Badge](https://img.shields.io/badge/NPM-Download%20%28613%29-blue)](https://www.npmjs.com/package/@trustme24/flext)
-[![Static Badge](https://img.shields.io/badge/CodeSandbox-Preview%20%2841%29-black)](https://codesandbox.io/p/devbox/trustme24-flext-f5x2hy)
+[![Static Badge](https://img.shields.io/badge/NPM-Download%20%285480%29-blue)](https://www.npmjs.com/package/@trustme24/flext)
+[![Static Badge](https://img.shields.io/badge/CodeSandbox-Preview%20%2853%29-black)](https://codesandbox.io/p/devbox/trustme24-flext-f5x2hy)
 
-**Flext** is a lightweight extension over [Handlebars](https://handlebarsjs.com/). It introduces a small DSL for handling macros and modules to help create dynamic templates. The library is compiled to both ESM and CommonJS bundles and can be embedded in other projects such as [Vue components](https://www.npmjs.com/package/vue-flext).
+![trustme24_flext_cover.jpg](https://raw.githubusercontent.com/TrustMe-kz/flext/ae3284e6156dd8b18e1998084943636e50cd64a2/docs/trustme24_flext_logo_cover.jpg)
 
-- [Demo: Available at CodeSandbox](https://codesandbox.io/p/devbox/trustme24-flext-f5x2hy)
-- [Documentation: Available at TrustMe Wiki](https://trustmekz.atlassian.net/wiki/external/MTUwYzM5NjUzNDE4NDViMGJlMTliOWEzNzM1Y2RiZWE).
+**Flext** is a technology for building reliable document templates.
 
-[Flext is maintained by TrustMe](https://trustme24.com/).
+In many systems, templates start simple and gradually become fragile: fields appear without documentation, rendering logic spreads across multiple layers, versions break compatibility, and debugging becomes difficult. Flext addresses this problem by allowing templates to describe the structure and requirements of the document itself.
+
+A Flext template can contain Markup, Metadata, Modules, and rendering hints in a single artifact. This makes templates easier to reuse, validate, and embed into larger systems such as document pipelines, reporting services, or contract generation platforms.
+
+- [GitHub: TrustMe-kz/flext](https://github.com/TrustMe-kz/flext)  
+- [NPM: @trustme24/flext](https://www.npmjs.com/package/@trustme24/flext)  
+- [Demo: Available at CodeSandbox](https://codesandbox.io/p/devbox/trustme24-flext-f5x2hy)  
+- [Documentation: Available at TrustMe Wiki](https://trustmekz.atlassian.net/wiki/external/MTUwYzM5NjUzNDE4NDViMGJlMTliOWEzNzM1Y2RiZWE)
+
+---
+
+## Installation
+
+```shell
+npm i @trustme24/flext tailwindcss
+```
+
+Add the **CSS** import:
+
+```css
+@import "@trustme24/flext/index.css";
+```
+
+🎉 **That's It!**
+
+---
+
+## The Problem
+
+Document templating often looks simple at first. Over time it tends to accumulate hidden complexity.
+
+Typical issues include: undocumented fields, incompatible template versions, duplicated rendering logic across services, fragile helper usage, and weak validation before rendering.
+
+![trustme24_flext_abstract_painting.jpg](https://raw.githubusercontent.com/TrustMe-kz/flext/ae3284e6156dd8b18e1998084943636e50cd64a2/docs/trustme24_flext_abstract_painting.jpg)
+
+### A few common scenarios illustrate the problem:
+
+1. **A template expects a field that is not provided at runtime. The result is either a broken document or silent incorrect output.**  
+Solution with Flext: The template can explicitly declare required fields using Metadata so missing data is detected early.
+
+————————————
+
+2. **Multiple services use the same template but apply different helper logic or formatting rules.**  
+Solution with Flext: Templates can declare Module dependencies so rendering logic is predictable and consistent.
+
+————————————
+
+3. **Templates evolve but older documents still rely on previous versions.**  
+Solution with Flext: Templates can carry explicit Version information and compatibility rules.
+
+---
+
+## What It Provides
+
+**Flext** builds on top of [Handlebars](https://handlebarsjs.com/) and keeps its familiar syntax while adding a small metadata layer. The goal is not to replace existing template engines but to make document templates safer and easier to maintain.
+
+Instead of treating templates as plain text files, Flext treats them as structured artifacts. A template can include Markup, Metadata directives, and Module dependencies, all stored together.
+
+This approach helps systems understand what a template requires before rendering it.
+
+### Quick Start:
+
+```ts
+import Flext from '@trustme24/flext';
+
+const template = `
+  {{!-- @v "1.0.beta4" --}}
+  {{!-- @use "put" --}}
+  <p>{{ put name 'Unknown user...' }}</p>
+`;
+
+const flext = new Flext(template, { name: 'Anna' });
+
+document.body.innerHTML = flext.html;
+```
+
+---
+
+## Core Ideas
+
+A **Flext** template contains three conceptual layers. The first layer is markup: HTML and standard Handlebars expressions. The second layer is Metadata written as directives such as `@v`, `@field`, or `@use`. The third layer is runtime behavior provided through Modules and helpers.
+
+Keeping these elements close together makes templates easier to move between systems and reduces hidden assumptions.
+
+Metadata directives can describe template Version, language, title, rendering parameters, and required fields. Modules provide reusable logic such as formatting numbers, inserting fallback values, or conditional rendering.
 
 ### Example
+
 ```ts
-import { Flext } from '@trustme24/flext';
+import Flext from '@trustme24/flext';
 
 const template = `
   {{!-- @v "1.0.beta4" --}}
   {{!-- @use "put" --}}
+  {{!-- @group "data" --}}
+  {{!-- @field "data.someField" type="string" label="Message" required --}}
 
-  <div class="text-center text-red-500">{{ put data.helloWorld 'No hello world...' }}</div>
+  <p class="text-center text-red-500">
+    {{ put data.someField 'No hello world...' }}
+  </p>
 `;
 
 const flext = new Flext(template, {
-  data: { helloWorld: 'Hello World!' },
+  data: { someField: 'Hello World!' },
 });
 
-document.body.innerHTML = flext.html;
+console.log(flext.html);   // <p class="...">Hello World!</p>
+console.log(flext.model);  // {"name":"data","$":[{"name":"someField"}]}
 ```
 
-## Installation
+> 💡 **In this example** the template carries additional information: Version, Field definition, and Module usage. This allows runtime tools to build a Data Model, validate input, and render HTML predictably.
 
-1. Install **dependencies**:
+---
 
-```shell
-npm i @trustme24/flext tailwindcss
+## Use Cases
+
+![trustme24_flext_use_cases.jpg](https://raw.githubusercontent.com/TrustMe-kz/flext/ae3284e6156dd8b18e1998084943636e50cd64a2/docs/trustme24_flext_use_cases.jpg)
+
+**Flext** is intended for structured document generation. Common examples include contracts, invoices, reports, certificates, and internal document workflows. It is particularly useful when templates must be versioned, validated, reused across services, or rendered in multiple environments.
+
+Flext can be used on its own, but it is also designed to serve as a core library inside larger systems. Related tools include [vue-flext](https://www.npmjs.com/package/vue-flext) for Vue integration, [flext2pdf](https://www.npmjs.com/package/flext2pdf) for HTML‑to‑PDF rendering, and some **Flext Convert Service** for running document rendering as a microservice.
+
+Together these components allow Flext to power full document pipelines while remaining a lightweight core library.
+
+---
+
+## Writing Templates
+
+Templates should stay declarative and focused on layout. Business logic is usually better handled in Modules or application code. Metadata directives such as `@field` help document required data and make validation possible.
+
+### Example:
+
+```handlebars
+{{!-- @v "1.0.beta4" --}}
+{{!-- @use "put" "date" --}}
+{{!-- @group "data" --}
+{{!-- @field "data.city" type="string" label="City" required --}}
+{{!-- @field "data.date" type="date"   label="Date" required --}}
+
+<p>
+  {{ put data.city "City" }}, {{ put (date:text data.date "No date...") }}
+</p>
 ```
 
-2. Add the **CSS** import in your CSS file:
+### Best practices
 
-```css
-@import "@trustme24/flext/index.css";
+Treat templates as versioned artifacts. Prefer explicit metadata over hidden assumptions. Keep helper usage predictable and document important data paths with `@field`. Test templates with realistic data and separate document layout from application business rules.
+
+### Limitations
+
+Flext is intentionally focused. It is not a full programming language, not a WYSIWYG editor, and not a complete document management system. Its role is to act as a reliable template core inside document generation workflows.
+
+---
+
+## API
+
+The main entry point is the `Flext` class.
+
+### Constructor:
+
+```ts
+import Flext from '@trustme24/flext';
+
+new Flext().setTemplate('...').setData({});
 ```
 
-3. **You're all set!**
+[More information about the API is available at TrustMe Wiki](https://trustmekz.atlassian.net/wiki/external/MTUwYzM5NjUzNDE4NDViMGJlMTliOWEzNzM1Y2RiZWE).
 
-## Tests & Demo
+---
 
-- **Unit** Tests:
+## Architecture
 
-```shell
-npm run test
+**Flext** operates as a simple pipeline.
+
+```text
+Template
+  v
+Parser / AST
+  v
+Directives / Modules
+  v
+PDF / Preview / Data Model / Export
 ```
 
-- Test **App**:
+At runtime Flext parses the template, extracts Metadata, registers Modules, builds a Data Model, and generates preview. The output can then be passed to other tools to display, store, or generating PDF.
+
+- [Repo: More information about the repo can be found in ARCHITECTURE.md](https://github.com/TrustMe-kz/flext/blob/main/ARCHITECTURE.md)
+- [Documentation: More information about the API is available at TrustMe Wiki](https://trustmekz.atlassian.net/wiki/external/MTUwYzM5NjUzNDE4NDViMGJlMTliOWEzNzM1Y2RiZWE)
+
+---
+
+## Development
 
 ```shell
 npm run test:app
 ```
 
+Run **Tests**:
+
+```shell
+npm run test
+```
+
+[More information about the contribution can be found in CONTRIBUTING.md](https://github.com/TrustMe-kz/flext/blob/main/CONTRIBUTING.md).
+
 ---
+
+## Roadmap
+
+Future development focuses on improving reliability and adoption. Planned areas include stronger template validation, better parser and AST tooling, clearer compatibility rules, improved module authoring experience, richer documentation, ecosystem integrations, editor support, and a template corpus for regression testing.
+
+![trustme24_flext_abstract_painting.jpg](https://raw.githubusercontent.com/TrustMe-kz/flext/ae3284e6156dd8b18e1998084943636e50cd64a2/docs/trustme24_flext_abstract_painting.jpg)
+
+- **Contributions** are welcome. Useful areas include documentation, example templates, modules, parser improvements, performance optimizations, and test coverage. Changes that affect the template syntax or core semantics should first be discussed in issues so architectural decisions remain consistent.
+
+————————————
+
+- **Governance:** Flext is maintained by [TrustMe](https://trustme24.com/). External contributions are encouraged while core design decisions remain centralized to keep the language and runtime coherent.
+
+————————————
+
+- **Security:** If you discover a security issue, please report it privately to [i.am@kennyromanov.com](mailto:i.am@kennyromanov.com) instead of opening a public issue
+
+————————————
+
+- **License:** Flext is released under the [MIT License](https://github.com/TrustMe-kz/flext/blob/main/LICENSE)
+
+---
+
 **Flext by Kenny Romanov**  
 TrustMe

package/dist/engine.d.ts

@@ -0,0 +1,66 @@
+import { AST } from '@handlebars/parser';
+import * as types from './types';
+import * as errors from './errors';
+export declare const DEFAULT_HELPER_NAME = "__default";
+export declare const DEFAULT_MODEL_DEPTH = 10;
+export type MacrosData = {
+    version?: string | null;
+    lang?: string | null;
+    timeZone?: string | null;
+    title?: string | null;
+    moduleNames?: string[] | null;
+    lineHeight?: string | null;
+    fields?: types.Field[] | null;
+};
+export declare class SimpleFlext {
+    ast: AST.Program;
+    data: types.Obj;
+    helpers: types.Obj;
+    onGetProcessed: types.GetProcessedTemplateHandler;
+    onGetAst: types.GetTemplateAstHandler;
+    constructor(val?: string | null, data?: types.Obj, helpers?: types.Obj);
+    setTemplate(val: string): this;
+    setData(val: types.Obj): this;
+    setHelpers(val: types.Obj): this;
+    addHelper(name: string, val: any): this;
+    setOnGetProcessed(val: types.GetProcessedTemplateHandler): this;
+    setOnGetAst(val: types.GetTemplateAstHandler): this;
+    getHtml(data?: types.Obj | null, helpers?: types.Obj | null): string;
+    getCss(data?: types.Obj | null, options?: types.Obj): Promise<string>;
+    get html(): string;
+}
+export declare class Flext extends SimpleFlext {
+    version: string;
+    lang: string;
+    title: string;
+    timeZone: string;
+    lineHeight: number;
+    assets: types.Obj<Blob>;
+    fields: types.Field[];
+    onGetTitle: types.GetTemplateTitleHandler;
+    onGetMacro: types.GetTemplateMacroHandler;
+    constructor(val?: string | null, data?: types.Obj, helpers?: types.Obj);
+    useModule(...val: string[]): this;
+    setTemplate(val: string): this;
+    setVersion(val: string): this;
+    setLang(val: string): this;
+    setTitle(val: string): this;
+    setTimeZone(val: string): this;
+    setLineHeight(val: number): this;
+    setAssets(val: types.Obj<Blob>): this;
+    addAsset(name: string, val: Blob): this;
+    setFields(val: types.Field[]): this;
+    addModule(name: string, val: any): this;
+    setOnGetTitle(val: types.GetTemplateTitleHandler): this;
+    setOnGetMacro(val: types.GetTemplateMacroHandler): this;
+    getDataModel(depth?: number): types.MetadataModelNode[];
+    getValidationErrors(data?: types.Obj | null, depth?: number): errors.TemplateDataValidationError[];
+    getIsValid(data?: types.Obj | null, depth?: number): boolean;
+    get model(): types.MetadataModelNode[];
+    get validationErrors(): errors.TemplateDataValidationError[];
+    get errors(): errors.BaseError[];
+    get isValid(): boolean;
+}
+export declare function macrosToData(macros: types.Macro[]): MacrosData;
+export declare function defaultGetProcessed(val: string): string;
+export default Flext;