@adaas/are 0.0.2 → 0.0.4

package/src/lib/AreSyntax/AreSyntax.types.ts

@@ -1,156 +1,92 @@
-
-
-export type AreSyntaxInitOptions = {
-    /**
-     * Enable or disable debug mode for AreSyntax.
-     * When enabled, additional logging and debugging information will be available.
-     * Default is false.
-     */
-    debugMode?: boolean;
-
-    /**
-     * Custom interpolation delimiters for template parsing.
-     * Default is ['{{', '}}'].
-     */
-    interpolationDelimiters?: [string, string];
-
-    /**
-     * Custom binding delimiters for data binding parsing.
-     * Default is ':'.
-     */
-    bindingDelimiter?: string;
-
-
-    /**
-     * Custom listener delimiters for event binding parsing.
-     * Default is '@'.
-     */
-    listenerDelimiter?: string;
-
-
-
+import { A_TYPES__Entity_Constructor } from "@adaas/a-concept";
+import { AreAttribute } from "@adaas/are/attribute/AreAttribute.entity";
+import { AreNode } from "@adaas/are/node/AreNode.entity";
+import { AreStore } from "@adaas/are/store/AreStore.context";
+// ── Token Rule ────────────────────────────────────────────────────────────────
+
+export interface AreSyntaxTokenRules<T extends AreNode = AreNode> {
+    /** Opening delimiter e.g. '<', '{{', '<!--', '{' */
+    opening?: string
+    /** Closing delimiter e.g. '>', '}}', '-->', '}' */
+    closing?: string
+    /** Optional self-closing marker e.g. '/>' */
+    selfClosing?: string
+    /** Regex that must match content immediately before the opening delimiter */
+    prefix?: RegExp
+    /** Replaces open/close entirely — matches entire pattern via RegExp */
+    pattern?: RegExp
+    /**
+     * Fully custom matcher — complete control over how a token is found.
+     * Receives (source, from, to, build) where build(raw, content, position, closing)
+     * constructs the AreSyntaxTokenMatch. Return null if no match found.
+     */
+    matcher?: (
+        source: string,
+        from: number,
+        to: number,
+        build: (raw: string, content: string, position: number, closing: string) => AreSyntaxTokenMatch
+    ) => AreSyntaxTokenMatch | null
+    /** Constructor to instantiate when this rule matches */
+    component: A_TYPES__Entity_Constructor<T>
+    /** Higher = checked first. Default: 0 */
+    priority?: number
+    /** Whether this token can contain nested tokens of same open/close. Default: true */
+    nested?: boolean
+    /** Custom data extractor — called after match, result stored in match.meta */
+    extract?: (raw: string, match: AreSyntaxTokenMatch) => Record<string, any>
+}
+// ── Token Payload  ───────────────────────────────────────────────────────────────
+export type AreSyntaxTokenPayload = {
     /**
-     * Enable or disable strict mode for syntax parsing.
-     * When enabled, the parser will throw errors for any syntax violations.
-     * Default is true.
+     * Allows to override ASEID generation for this token match. Useful when the token corresponds to an existing entity or needs a stable ID across parses. If not provided, ASEID will be generated based on position and content.
      */
-    strictMode?: boolean;
-
+    id?: string;
     /**
-     * A list of custom directives to be recognized by the syntax parser.
-     * Each directive should be a string representing the directive name.
-     * Default is an empty array.
+     * Allows to override the entity type for this token match. Useful when the token corresponds to an existing entity or needs a specific entity type across parses. If not provided, the entity type will be inferred from the token.
      */
-    customDirectives?: string[];
-
+    entity?: string;
     /**
-     * Enable or disable whitespace trimming in templates.
-     * When enabled, leading and trailing whitespace in template expressions will be trimmed.
-     * Default is true.    
+     * Allows to override the scope for this token match. Useful when the token corresponds to an existing entity or needs a specific scope across parses. If not provided, the scope will be generated based on position and content.
      */
-    trimWhitespace?: boolean;
-
+    scope?: string;
+    [key: string]: any
+}
 
-    /**
-     * identifier of the root tag to use when compiling in browser context.
-     */
-    rootTag?: string;
+// ── Token Match ───────────────────────────────────────────────────────────────
+
+export interface AreSyntaxTokenMatch {
+    /** Full matched string including delimiters */
+    raw: string
+    /** Content between delimiters */
+    content: string
+    /** The opening delimiter that matched */
+    opening: string
+    /** The closing delimiter that matched */
+    closing: string
+    /** Start position in source string */
+    position: number
+    /** Data extracted via rule.extract */
+    payload: AreSyntaxTokenPayload
+    /** @internal – the rule that produced this match (used by instantiate) */
+    _rule?: AreSyntaxTokenRules
+}
 
+export interface AreSyntaxInitOptions {
     /**
-     * Custom directive delimiter for directive parsing.
-     * Default is '$'.
+     * Array of token rules defining the syntax to be parsed. Each rule specifies how to identify and process a particular type of token (e.g. interpolation, directive, comment) within templates. The rules are checked in order of priority, allowing for flexible and customizable parsing behavior.
      */
-    directiveDelimiter?: string;
-
+    rules: AreSyntaxTokenRules[]
     /**
-     * List of standard HTML tags to recognize.
+     * Whether to trim leading/trailing whitespace from token content. Default: true. When enabled, any whitespace at the start or end of the content captured by a token will be removed before further processing. This can help prevent issues with unintended spaces affecting rendering or logic, especially in cases like interpolations or directives where extra whitespace may be common.
      */
-    standardTags?: string[]
+    trimWhitespace?: boolean
+    /** Throw on unclosed tokens. Default: true */
+    strictMode?: boolean
 };
 
 
-// ==================================================================================
-// ========================= SYNTAX Structures TYPES ================================
-// ==================================================================================
-
-export type AreAttribute = {
-    /**
-     * Tag name where the attribute was found
-     */
-    tag: string;
-    /**
-     * Property name (e.g. "label")
-     */
-    name: string;
-    /**
-     * Full raw attribute (e.g. ' :label="buttonLabel" ')
-     */
-    raw: string;
-    /**
-     * Attribute value (e.g. "buttonLabel")
-     */
-    value: string;
-    /**
-     * True if the attribute is a binding (e.g. :prop), false otherwise (e.g. prop="value")
-     */
-    binding: boolean;
-};
 
-export type AreInterpolation = {
-    /**
-     * Tag name where the interpolation was found
-     */
-    raw: string;
-    /**
-     * Name of the interpolation (e.g. "userName")
-     */
-    name: string;
-    /**
-     * Position in the template where this interpolation was found 
-     */
-    position: number;
+export type AreSyntaxCompiledExpression = {
+    execute: (store: AreStore, scope?: Record<string, any>) => any
+    isCallable: boolean
 }
-
-
-export type AreListener = {
-    /**
-     * tag name where listener was found
-     */
-    tag: string;
-    /**
-     * event name (e.g. "input")
-     */
-    name: string;
-    /**
-     * full raw attribute (e.g. ' @input="onChange"')
-     */
-    raw: string;
-    /**
-     * handler expression (e.g. "onChange")
-     */
-    handler: string;
-};
-
-
-export type AreDirective = {
-    /**
-     * The tag name where the directive was found
-     */
-    tag: string;
-    /**
-     * The name of the directive (e.g. "$if")
-     */
-    name: string;
-    /**
-     * The full raw attribute text (e.g. '$if="condition"')
-     */
-    raw: string;
-    /**
-     * The value expression associated with the directive (e.g. "condition")
-     */
-    value?: string;
-    /**
-     * The full tag template where the directive was found
-     */
-    template: string;
-};

package/src/lib/AreTokenizer/AreTokenizer.component.ts

@@ -0,0 +1,289 @@
+import { A_Caller, A_Component, A_Context, A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame";
+import { AreNode } from "@adaas/are/node/AreNode.entity";
+import { AreSyntaxTokenMatch, AreSyntaxTokenRules } from "@adaas/are/syntax/AreSyntax.types";
+import { AreSyntax } from "@adaas/are/syntax/AreSyntax.context";
+import { AreContext } from "@adaas/are/component/Are.context";
+// import { AreEngine } from "@adaas/are/engine/AreEngine.component";
+import { AreEngineFeatures } from "@adaas/are/engine/AreEngine.constants";
+import { AreTokenizerError } from "./AreTokenizer.error";
+import { AreNodeFeatures } from "@adaas/are/node/AreNode.constants";
+import { A_Logger } from "@adaas/a-utils/a-logger";
+
+
+@A_Frame.Component({
+    namespace: 'A-ARE',
+    name: 'AreTokenizer',
+    description: 'AreTokenizer is responsible for scanning and tokenizing template source strings using the syntax rules defined in AreSyntax. It converts raw template strings into AreNode instances that represent the structured AST of the template, enabling downstream compilation and rendering within the ARE framework.'
+})
+export class AreTokenizer extends A_Component {
+
+    /**
+     * Get the AreSyntax from the current scope. The AreSyntax defines the syntax rules and structures for tokenizing templates. It provides mechanisms for parsing and interpreting templates, attributes, directives, interpolations, and event listeners, enabling dynamic and interactive UI rendering within the ARE framework. If no AreSyntax is found in the scope, an error is thrown indicating that AreTokenizer requires an AreSyntax to function properly.
+     */
+    protected get config(): AreSyntax {
+        const syntax = A_Context.scope(this).resolve(AreSyntax);
+
+        if (!syntax) throw new AreTokenizerError({
+            title: 'Syntax Context Not Found',
+            description: 'AreTokenizer requires an AreSyntax to be present in the same scope. Ensure that an AreSyntax fragment is included in the concept and is accessible from the scope where AreTokenizer is used.'
+        });
+
+        return syntax
+    }
+
+    /**
+     * Instantiate AreNodes based on the token matches obtained from scanning the source template. This method takes the raw source string from the context, scans it for tokens using the defined syntax rules, and creates corresponding AreNode instances for each matched token. The resulting array of AreNodes represents the structured representation of the template, which can then be used for further processing, such as rendering or applying scene instructions.
+     * 
+     * 
+     * @param context 
+     * @returns 
+     */
+    @A_Feature.Extend({
+        name: AreEngineFeatures.Load,
+        // scope: [AreEngine]
+    })
+    instantiate<T extends AreNode>(
+        @A_Inject(AreContext) context: AreContext,
+    ): void {
+        context.startPerformance('Tokenizer Instantiate');
+
+        const source = context.source;
+
+        const nodes = this
+            .scan(source, 0, source.length, context)
+            .map(match => {
+                const rule = this.findRuleForMatch(match)
+                if (!rule) throw new Error(`No rule found for match at position ${match.position}`)
+                return new (rule.component as typeof AreNode)(match)
+            })
+
+        for (const node of nodes) {
+            context.addRoot(node)
+        }
+
+        context.endPerformance('Tokenizer Instantiate');
+    }
+
+
+    @A_Feature.Extend({
+        name: AreNodeFeatures.onTokenize,
+        scope: [AreNode]
+    })
+    tokenize(
+        @A_Inject(A_Caller) node: AreNode,
+        @A_Inject(AreContext) context: AreContext,
+        @A_Inject(A_Logger) logger?: A_Logger,
+    ) {
+        context.startPerformance(`Tokenize method`);
+
+        const source = node.content
+        const content = this
+            .scan(source, 0, source.length, context)
+            .map(match => {
+                const rule = this.findRuleForMatch(match)
+                if (!rule) throw new Error(`No rule found for match at position ${match.position}`)
+                return new (rule.component as typeof AreNode)(match)
+            })
+
+        logger?.debug('red', `Tokenized node <${node.aseid.toString()}> with content:`, content.length);
+
+        context.endPerformance(`Tokenize method`);
+
+        context.startPerformance(`Tokenize node Create Children`);
+        for (const child of content) {
+            node.addChild(child);
+
+            context.startPerformance('AreTokenizer.tokenize child init');
+            child.init();
+            // child.call(AreNodeFeatures.onInit, child.scope);
+
+            context.endPerformance('AreTokenizer.tokenize child init');
+        }
+
+        context.endPerformance(`Tokenize node Create Children`);
+
+
+    }
+
+    protected scan(source: string, from: number, to: number, context: AreContext): AreSyntaxTokenMatch[] {
+        context.startPerformance('Tokenizer Scan');
+
+        const tokens: AreSyntaxTokenMatch[] = []
+        let index = from
+        let hasMatchBefore = false
+
+        while (index < to) {
+            const match = this.findNextMatch(source, index, to)
+            if (!match) {
+                const rest = source.slice(index, to)
+                /**
+                 * Trailing text (after the last match). When trimWhitespace is on,
+                 * discard it if it is whitespace-only — it is edge indentation/newlines.
+                 */
+                const t = this.tryPlainText(rest, index)
+                if (t && !(this.config.trimWhitespace && !rest.trim())) tokens.push(t)
+                break
+            }
+            if (match.position > index) {
+                const plain = source.slice(index, match.position)
+                const t = this.tryPlainText(plain, index)
+                if (t) {
+                    /**
+                     * When trimWhitespace is on and the text is whitespace-only:
+                     * - Discard if it is leading text (before the first match)
+                     * - Preserve (collapse to single space) if it is between two matches
+                     */
+                    if (this.config.trimWhitespace && !plain.trim()) {
+                        if (hasMatchBefore) {
+                            t.content = ' '
+                            tokens.push(t)
+                        }
+                        // else: leading whitespace — skip
+                    } else {
+                        tokens.push(t)
+                    }
+                }
+            }
+            tokens.push(match)
+            hasMatchBefore = true
+            index = match.position + match.raw.length
+        }
+
+        context.endPerformance('Tokenizer Scan');
+
+
+        return tokens
+    }
+
+    protected findNextMatch(source: string, from: number, to: number): AreSyntaxTokenMatch | null {
+        let earliest: AreSyntaxTokenMatch | null = null
+        for (const rule of this.config.rules) {
+            if (!rule.opening && !rule.closing && !rule.pattern && !rule.matcher) continue
+            const match = this.matchRule(source, rule, from, to)
+            if (!match) continue
+            if (!earliest || match.position < earliest.position) earliest = match
+        }
+        return earliest
+    }
+
+    protected matchRule(source: string, rule: AreSyntaxTokenRules, from: number, to: number): AreSyntaxTokenMatch | null {
+        if (rule.matcher) {
+            return rule.matcher(source, from, to, (raw, content, position, closing) =>
+                this.buildMatch(rule, raw, content, position, closing)
+            )
+        }
+        if (rule.pattern) {
+            const slice = source.slice(from, to)
+            rule.pattern.lastIndex = 0
+            const m = rule.pattern.exec(slice)
+            if (!m) return null
+            return this.buildMatch(rule, m[0], m[0], from + m.index, '')
+        }
+        if (!rule.opening || !rule.closing) return null
+        if (rule.prefix) return this.matchPrefixedRule(source, rule, from, to)
+        return this.matchStandardRule(source, rule, from, to)
+    }
+
+    protected matchStandardRule(source: string, rule: AreSyntaxTokenRules, from: number, to: number): AreSyntaxTokenMatch | null {
+        const opening = rule.opening!
+        const closing = rule.closing!
+        const openPos = source.indexOf(opening, from)
+        if (openPos === -1 || openPos >= to) return null
+        const contentStart = openPos + opening.length
+
+        if (rule.selfClosing) {
+            const selfClosePos = source.indexOf(rule.selfClosing, contentStart)
+            const normalClosePos = source.indexOf(closing, contentStart)
+            if (selfClosePos !== -1 && (normalClosePos === -1 || selfClosePos < normalClosePos)) {
+                const closeEnd = selfClosePos + rule.selfClosing.length
+                return this.buildMatch(rule, source.slice(openPos, closeEnd), source.slice(contentStart, selfClosePos), openPos, rule.selfClosing)
+            }
+        }
+
+        const closePos = rule.nested !== false
+            ? this.findMatchingClose(source, opening, closing, contentStart, to)
+            : source.indexOf(closing, contentStart)
+
+        if (closePos === -1) {
+            if (this.config.strictMode) throw new Error(`Unclosed token '${opening}' at position ${openPos}`)
+            return null
+        }
+
+        return this.buildMatch(rule, source.slice(openPos, closePos + closing.length), source.slice(contentStart, closePos), openPos, closing)
+    }
+
+    protected matchPrefixedRule(source: string, rule: AreSyntaxTokenRules, from: number, to: number): AreSyntaxTokenMatch | null {
+        const opening = rule.opening!
+        const closing = rule.closing!
+        let searchFrom = from
+
+        while (searchFrom < to) {
+            const openPos = source.indexOf(opening, searchFrom)
+            if (openPos === -1 || openPos >= to) return null
+
+            const before = source.slice(from, openPos)
+            const prefixRe = new RegExp(rule.prefix!.source + '$')
+            const prefixM = prefixRe.exec(before)
+
+            if (prefixM) {
+                const actualStart = openPos - prefixM[0].length
+                const contentStart = openPos + opening.length
+                const closePos = rule.nested !== false
+                    ? this.findMatchingClose(source, opening, closing, contentStart, to)
+                    : source.indexOf(closing, contentStart)
+
+                if (closePos === -1) {
+                    if (this.config.strictMode) throw new Error(`Unclosed token '${opening}' at position ${openPos}`)
+                    return null
+                }
+
+                return this.buildMatch(rule, source.slice(actualStart, closePos + closing.length), source.slice(contentStart, closePos), actualStart, closing)
+            }
+            searchFrom = openPos + 1
+        }
+        return null
+    }
+
+    protected findMatchingClose(source: string, opening: string, closing: string, from: number, to: number): number {
+        let level = 1
+        let index = from
+        while (index < to) {
+            const nextOpen = source.indexOf(opening, index)
+            const nextClose = source.indexOf(closing, index)
+            if (nextClose === -1) return -1
+            if (nextOpen !== -1 && nextOpen < nextClose) {
+                level++
+                index = nextOpen + opening.length
+                continue
+            }
+            level--
+            if (level === 0) return nextClose
+            index = nextClose + closing.length
+        }
+        return -1
+    }
+
+    protected buildMatch(rule: AreSyntaxTokenRules, raw: string, content: string, position: number, closingUsed: string): AreSyntaxTokenMatch {
+        const trimmed = this.config.trimWhitespace ? content.trim() : content
+        const match: AreSyntaxTokenMatch = { raw, content: trimmed, opening: rule.opening ?? '', closing: closingUsed, position, payload: {}, _rule: rule }
+        if (rule.extract) match.payload = rule.extract(raw, match)
+        return match
+    }
+
+    protected tryPlainText(raw: string, position: number): AreSyntaxTokenMatch | null {
+        if (!raw) return null
+        const rule = this.config.rules.find(r => !r.opening && !r.closing && !r.pattern && !r.matcher)
+        if (!rule) return null
+        const match = this.buildMatch(rule, raw, raw, position, '')
+        match._rule = rule
+        return match
+    }
+
+    protected findRuleForMatch(match: AreSyntaxTokenMatch): AreSyntaxTokenRules | undefined {
+        // Fast path: the rule that produced this match is already stored
+        if (match._rule) return match._rule
+        // Fallback: match by opening/closing (for externally constructed AreSyntaxTokenMatch objects)
+        return this.config.rules.find(r => (r.opening ?? '') === match.opening && (r.closing ?? '') === match.closing)
+    }
+}

package/src/lib/AreTokenizer/AreTokenizer.error.ts

@@ -0,0 +1,7 @@
+import { A_Error } from "@adaas/a-concept";
+
+
+
+export class AreTokenizerError extends A_Error {
+
+}

package/src/lib/AreTransformer/AreTransformer.component.ts

@@ -0,0 +1,46 @@
+import { A_Caller, A_Component, A_Feature, A_FormatterHelper, A_Inject, A_Scope } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame";
+import { A_Logger } from "@adaas/a-utils/a-logger";
+import { AreNode } from "@adaas/are/node/AreNode.entity";
+import { AreNodeFeatures } from "@adaas/are/node/AreNode.constants";
+import { AreScene } from "@adaas/are/scene/AreScene.context";
+
+
+
+@A_Frame.Component({
+    description: 'Reshapes the AreNode tree before compilation without changing its abstraction level. Responsible for structural rewrites that would complicate the compiler if left unhandled — converting $for nodes into AreGroupNode, extracting AreText and AreInterpolation from raw text, sorting directives via TopologicalSorter, and flagging static nodes.'
+})
+export class AreTransformer extends A_Component {
+
+    @A_Feature.Extend({
+        name: AreNodeFeatures.onTransform,
+        scope: [AreNode]
+    })
+    transform(
+        @A_Inject(A_Caller) node: AreNode,
+        @A_Inject(A_Scope) scope: A_Scope,
+        @A_Inject(AreScene) scene: AreScene,
+        ...args: any[]
+    ) {
+         // walk entire tree inside one feature — no recursive feature calls
+        const queue = [node]
+        while (queue.length > 0) {
+            const current = queue.shift()!
+            // const scene = current.scene;
+            // if (scene.isInactive)
+            //     continue;
+
+            /**
+             * 2. Prepare Instructions for directives and add then to render plan.
+             */
+            for (let i = 0; i < current.attributes.length; i++) {
+
+                const attribute = current.attributes[i];
+                attribute.transform();
+            }
+            
+            queue.push(...current.children)
+        }
+
+    }
+}

package/src/lib/AreWatcher/AreWatcher.component.ts

@@ -0,0 +1,84 @@
+import { A_Component } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame";
+
+@A_Frame.Component({
+    namespace: 'A-ARE',
+    name: 'AreWatcher',
+    description: 'AreWatcher is a component that observes browser navigation events (history pushState, replaceState, and popstate) and notifies registered handlers when the URL changes, enabling client-side routing and reactive route-based rendering within the ARE framework.'
+})
+export class AreWatcher extends A_Component {
+
+    private readonly handlers: Set<(url: URL) => void> = new Set();
+    private current: URL = new URL(window.location.href);
+
+    constructor() {
+        super();
+        this.patchHistory();
+        this.attachListeners();
+    }
+
+    // ── Public ────────────────────────────────────────────────────────────────
+
+    onChange(handler: (url: URL) => void): () => void {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);   // returns unsubscribe fn
+    }
+
+    get url(): URL {
+        return this.current;
+    }
+
+    destroy(): void {
+        window.removeEventListener('popstate', this.onPopState);
+        window.removeEventListener('hashchange', this.onHashChange);
+        window.removeEventListener('urlchange', this.onURLChange);
+        this.handlers.clear();
+    }
+
+    // ── Listeners ─────────────────────────────────────────────────────────────
+
+    private onPopState = (): void => {
+        this.notify();
+    }
+
+    private onHashChange = (): void => {
+        this.notify();
+    }
+
+    private onURLChange = (): void => {
+        this.notify();
+    }
+
+    private attachListeners(): void {
+        window.addEventListener('popstate', this.onPopState);
+        window.addEventListener('hashchange', this.onHashChange);
+        window.addEventListener('urlchange', this.onURLChange);   // custom event from patch
+    }
+
+    // ── Patch pushState / replaceState ────────────────────────────────────────
+
+    private patchHistory(): void {
+        const patch = (original: typeof history.pushState) =>
+            function (this: History, ...args: Parameters<typeof history.pushState>) {
+                original.apply(this, args);
+                window.dispatchEvent(new Event('urlchange'));
+            };
+
+        history.pushState = patch(history.pushState);
+        history.replaceState = patch(history.replaceState);
+    }
+
+    // ── Notify ────────────────────────────────────────────────────────────────
+
+    private notify(): void {
+        const next = new URL(window.location.href);
+
+        if (next.href === this.current.href) return;   // no actual change
+
+        this.current = next;
+
+        for (const handler of this.handlers) {
+            handler(this.current);
+        }
+    }
+}