@reidelsaltres/pureper 0.1.157 → 0.1.162

package/src/foundation/engine/TemplateEngine.ts

@@ -0,0 +1,318 @@
+import Scope from './Scope.js';
+import Expression from './Expression.js';
+import EscapeHandler from './EscapeHandler.js';
+import TemplateInstance, { TemplateSection, FragmentBinding } from './TemplateInstance.js';
+import Rule, { RuleMatch, RuleResult, SyntaxRule, AttributeRule } from './Rule.js';
+import Observable from '../api/Observer.js';
+
+// Import rules
+import ExpressionRule from './rules/syntax/ExpressionRule.js';
+import IfRule from './rules/syntax/IfRule.js';
+import ForRule from './rules/syntax/ForRule.js';
+import RefRule from './rules/attribute/RefRule.js';
+import EventRule from './rules/attribute/EventRule.js';
+import InjectionRule from './rules/attribute/InjectionRule.js';
+
+/**
+ * TemplateEngineOptions - настройки TemplateEngine
+ */
+export interface TemplateEngineOptions {
+    /** Оставлять синтаксис атрибутивных Rule в финальном HTML */
+    showAttributeRule?: boolean;
+    /** Включить предупреждения отладки */
+    debugWarnings?: boolean;
+}
+
+/**
+ * ProcessResult - результат обработки шаблона
+ */
+export interface ProcessResult {
+    output: string;
+    observables: Observable<any>[];
+    sections: TemplateSection[];
+    /** ID созданного фрагмента (если был создан) */
+    fragmentId?: string;
+}
+
+/**
+ * TemplateEngine - главный класс шаблонизатора.
+ * Обрабатывает HTML-шаблон с Rule и создаёт TemplateInstance.
+ */
+export default class TemplateEngine {
+    private readonly scope: Scope;
+    private readonly options: TemplateEngineOptions;
+    private readonly syntaxRules: SyntaxRule[] = [];
+    private readonly attributeRules: AttributeRule[] = [];
+
+    constructor(scope: Scope | object, options?: TemplateEngineOptions) {
+        this.scope = scope instanceof Scope ? scope : Scope.from(scope);
+        this.options = {
+            showAttributeRule: false,
+            debugWarnings: true,
+            ...options
+        };
+
+        // Register default rules (sorted by priority)
+        this.registerDefaultRules();
+    }
+
+    /**
+     * Зарегистрировать стандартные правила
+     */
+    private registerDefaultRules(): void {
+        // Syntax rules
+        this.syntaxRules.push(new ForRule());
+        this.syntaxRules.push(new IfRule());
+        this.syntaxRules.push(new ExpressionRule());
+
+        // Attribute rules
+        this.attributeRules.push(new RefRule());
+        this.attributeRules.push(new EventRule());
+        this.attributeRules.push(new InjectionRule());
+
+        // Sort by priority
+        this.syntaxRules.sort((a, b) => a.priority - b.priority);
+        this.attributeRules.sort((a, b) => a.priority - b.priority);
+    }
+
+    /**
+     * Добавить пользовательское правило
+     */
+    public addRule(rule: Rule): void {
+        if (rule.type === 'syntax') {
+            this.syntaxRules.push(rule as SyntaxRule);
+            this.syntaxRules.sort((a, b) => a.priority - b.priority);
+        } else {
+            this.attributeRules.push(rule as AttributeRule);
+            this.attributeRules.sort((a, b) => a.priority - b.priority);
+        }
+    }
+
+    /**
+     * Получить Scope
+     */
+    public getScope(): Scope {
+        return this.scope;
+    }
+
+    /**
+     * Обработать шаблон и вернуть TemplateInstance
+     */
+    public parse(template: string): TemplateInstance {
+        const templateInstance = new TemplateInstance(this.scope);
+        const result = this.processTemplateWithFragments(template, this.scope, templateInstance, null);
+
+        // Устанавливаем корневой фрагмент
+        if (result.fragmentId) {
+            templateInstance.setRootFragment(result.fragmentId);
+        }
+
+        // Add sections and track observables
+        for (const section of result.sections) {
+            templateInstance.addSection(section);
+
+            // Track observables
+            for (const observable of section.result.observables || []) {
+                templateInstance.trackObservable(observable, section, (s) => {
+                    return this.processTemplate(s.sourceTemplate, this.scope);
+                });
+            }
+        }
+
+        return templateInstance;
+    }
+
+    /**
+     * Обработать шаблон с созданием фрагментов
+     */
+    private processTemplateWithFragments(
+        template: string,
+        scope: Scope,
+        instance: TemplateInstance,
+        parentFragmentId: string | null
+    ): ProcessResult {
+        const result = this.processTemplate(template, scope);
+        
+        // Создаём фрагмент для этого результата
+        const fragmentId = instance.createFragment(
+            result.output,
+            template,
+            result.sections,
+            parentFragmentId
+        );
+        
+        return {
+            ...result,
+            fragmentId
+        };
+    }
+
+    /**
+     * Обработать шаблон (внутренний метод, используется Rule для рекурсии)
+     */
+    public processTemplate(template: string, scope: Scope): ProcessResult {
+        const allObservables: Observable<any>[] = [];
+        const allSections: TemplateSection[] = [];
+
+        // Step 1: Handle @@ escape sequences
+        let processed = EscapeHandler.process(template, (escaped) => {
+            let result = escaped;
+
+            // Step 2: Process syntax rules (in priority order)
+            for (const rule of this.syntaxRules) {
+                result = this.processRule(rule, result, scope, allObservables, allSections);
+            }
+
+            // Step 3: Process attribute rules
+            for (const rule of this.attributeRules) {
+                // Skip injection - processed last
+                if (rule.name === 'injection') continue;
+                result = this.processRule(rule, result, scope, allObservables, allSections);
+            }
+
+            return result;
+        });
+
+        // Step 4: Process injection rules last
+        const injectionRule = this.attributeRules.find(r => r.name === 'injection');
+        if (injectionRule) {
+            processed = this.processRule(injectionRule, processed, scope, allObservables, allSections);
+        }
+
+        // Step 5: Handle showAttributeRule option
+        if (!this.options.showAttributeRule) {
+            processed = this.removeAttributeSyntax(processed);
+        }
+
+        return {
+            output: processed,
+            observables: allObservables,
+            sections: allSections
+        };
+    }
+
+    /**
+     * Обработать одно правило
+     */
+    private processRule(
+        rule: Rule,
+        template: string,
+        scope: Scope,
+        observables: Observable<any>[],
+        sections: TemplateSection[]
+    ): string {
+        const matches = rule.find(template);
+        
+        // Sort matches by position (reverse to process from end)
+        matches.sort((a, b) => b.start - a.start);
+
+        let result = template;
+
+        for (const match of matches) {
+            try {
+                const ruleResult = rule.execute(match, scope, this) as RuleResult;
+
+                // Track observables
+                if (ruleResult.observables) {
+                    observables.push(...ruleResult.observables);
+                }
+
+                // Create section
+                const section: TemplateSection = {
+                    rule,
+                    match,
+                    result: ruleResult,
+                    sourceTemplate: match.fullMatch,
+                    children: [],
+                    subscriptions: []
+                };
+                sections.push(section);
+
+                // Replace in template
+                result = result.slice(0, match.start) + ruleResult.output + result.slice(match.end);
+
+            } catch (error) {
+                console.error(`[TemplateEngine] Error processing rule "${rule.name}":`, error);
+                // Continue processing other rules
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Удалить синтаксис атрибутивных Rule из финального HTML
+     */
+    private removeAttributeSyntax(template: string): string {
+        // Remove @[ref], @on[...], @injection[...] patterns that weren't processed
+        return template
+            .replace(/@\[ref\]\s*=\s*["'][^"']*["']/gi, '')
+            .replace(/@on\[[a-zA-Z]+\]\s*=\s*["'][^"']*["']/gi, '')
+            .replace(/@injection\[(head|tail)\]\s*=\s*["'][^"']*["']/gi, '');
+    }
+
+    /**
+     * Добавить новый шаблон в существующий TemplateInstance.
+     * Обрабатывает шаблон и добавляет результат как новый фрагмент.
+     * Если instance привязан к контейнерам, DOM обновится автоматически.
+     * 
+     * @param instance - существующий TemplateInstance
+     * @param template - новый шаблон для добавления
+     * @param customScope - опциональный scope для нового шаблона
+     * @returns ID созданного фрагмента
+     */
+    public appendTemplate(instance: TemplateInstance, template: string, customScope?: Scope | object): string {
+        const scope = customScope 
+            ? (customScope instanceof Scope ? customScope : Scope.from(customScope))
+            : instance.getScope();
+        
+        // Обрабатываем шаблон
+        const result = this.processTemplate(template, scope);
+        
+        // Создаём фрагмент
+        const fragmentId = instance.createFragment(
+            result.output,
+            template,
+            result.sections,
+            null // без родителя - это отдельный фрагмент
+        );
+        
+        // Добавляем секции и отслеживаем Observable
+        for (const section of result.sections) {
+            instance.addSection(section);
+            
+            for (const observable of section.result.observables || []) {
+                instance.trackObservable(observable, section, (s) => {
+                    return this.processTemplate(s.sourceTemplate, scope);
+                });
+            }
+        }
+        
+        // Вставляем в привязанные контейнеры
+        instance.insertAppendedFragment(fragmentId);
+        
+        return fragmentId;
+    }
+
+    /**
+     * Статический метод для быстрой обработки
+     */
+    public static process(template: string, scope: object, options?: TemplateEngineOptions): string {
+        const engine = new TemplateEngine(scope, options);
+        const TemplateInstance = engine.parse(template);
+        return TemplateInstance.getTemplate();
+    }
+
+    /**
+     * Создать TemplateInstance из шаблона
+     */
+    public static create(template: string, scope: object, options?: TemplateEngineOptions): TemplateInstance {
+        const engine = new TemplateEngine(scope, options);
+        return engine.parse(template);
+    }
+}
+
+// Re-export useful types
+export { Scope, Expression, TemplateInstance, Rule, SyntaxRule, AttributeRule };
+export { ExpressionRule, IfRule, ForRule, RefRule, EventRule, InjectionRule };
+export * from './exceptions/TemplateExceptions.js';

package/src/foundation/engine/TemplateInstance.md

@@ -0,0 +1,110 @@
+Проанализируй текущий код TemplateInstance, Переделай TemplateInstance
+
+# Предположительный пример структуры и работы
+
+Должен содержать множество различных мелких фрагментов, и при обновлении rebuild-ить только те на которые изменения повлияли, т.е
+Если:
+<div>@(observable1)</div> 
+<div>@(observable2)</div> 
+
+должно создатся 2 фрагмента
+1. <div>@(observable1)</div> - пересоздастся только при изменении observable1, изменения observable2 не повлияют на него
+2. <div>@(observable2)</div> - пересоздастся только при изменении observable2, изменения observable1 не повлияют на него
+
+---
+
+Если:
+<div>@(observable1) и @(observable2)</div> то изменения observable1 и изменение observable2 должны влиять
+
+здесь 1 фрагмент:
+1. <div>@(observable1) и @(observable2)</div> #id1
+
+---
+
+Если:
+<div @[ref]="'outer'">
+    <span>@(observable1)</span>
+    <span>@(observable2)</span>
+    @for (observableVar in observableCollection) {
+        <span>@(observableVar)</span>
+    }
+</div>
+
+здесь 5+ фрагментов:
+1.  <div @[ref]="'outer'"> #id1
+        #id2
+        #id3
+        #id4
+    </div>
+2.  <span>@(observable1)</span> #id2
+3.  <span>@(observable2)</span> #id3
+4.  *RuleFragment* @for (observableVar in observableCollection) { #id5 } #id4
+5+  <span>@(observableVar)</span> #id5
+
+3 отдельных фрагмента (#id5-a, #id5-b, #id5-c), каждый обновляется независимо
+
+Если изменится observable1 то пересоздастся должен только #id2
+Если изменится observableCollection то пересоздастся должен #id4 и соответсвенно это коснётся и вложенного в него #id5
+Измеения в var в #id5 должно пересоздать только #id5
+
+
+Если Scope { observable1 = new Observable(1), 
+    observable1 = new Observable(2), 
+    observableCollection = new Observable([55,56,57]) }
+
+то результат будет выглядеть так:
+
+<div id="'outer'">
+    <span>1</span>
+    <span>2</span>
+    <span>55</span>
+    <span>56</span>
+    <span>57</span>
+</div>
+
+но при изменении observable1.setObject(999) то результат станет:
+
+<div id="'outer'">
+    <span>999</span>
+    <span>2</span>
+    <span>55</span>
+    <span>56</span>
+    <span>57</span>
+</div>
+
+если TemplateInstance имеет биндинг с контейнером, то аналогичные изменения должны происходить и в контейнере
+
+---
+
+
+
+изменения observable1 повлияет только на #id1
+изменения observabıe2 повлияет только на #id2
+
+TemplateInstance должен иметь эмитить ивенты на которые можно подписатся
+onFragmentChange(event: FragmentChangeEvent)
+
+должен иметь методы
+bindRefs() - должен создавать в Scope переменные из @[ref] правила
+unbindRefs() - должен удалять из Scope переменные из @[ref] правила (приравнивать к null)
+
+bindEvents() - должен добавлять обработчик событий к html-element из @on[event] правила
+unbindEvents() - должен удалять обработчик событий из html-element по @on[event] правилу
+
+bind(container) - должен связывать внутреннюю DOM структуру с container, должен вставлять DOM в container
+unbind(container) - должен удалять связь внутренней DOM структуры с container, оставляет элементы в container, но при изменении в TemplateInstance container уже не должен меняется
+
+Если существует binding с container то изменения внутри TemplateInstance должны так же отражатся и на container,
+удаление и добавление ивентов, динамическое обновление и пересоздание фагментов, 
+
+TemplateInstance может иметь множество контейнеров binding-ов
+
+bind(container) - должен автоматически вызывать bindRefs,bindEvents
+unbind(container) - должен автоматически вызывать unbindRefs,unbindEvents
+
+# Уточнения
+1. Архитектурная проблема — TemplateEngine не создаёт фрагменты:
+Сейчас TemplateEngine.parse() возвращает один общий результат. Разбиение на фрагменты по Observable не происходит. Нужно менять логику парсинга. Изменения TemplateEngine приемлимы если требуются
+
+
+