@reidelsaltres/pureper 0.1.156 → 0.1.160

package/src/foundation/engine/TemplateInstance.ts

@@ -0,0 +1,355 @@
+import Scope from './Scope.js';
+import Observable, { MutationObserver } from '../api/Observer.js';
+import Rule, { RuleMatch, RuleResult } from './Rule.js';
+
+/**
+ * TemplateChangeEvent - событие изменения шаблона
+ */
+export interface TemplateChangeEvent {
+    oldValue: any;
+    newValue: any;
+    oldTemplate: string;
+    newTemplate: string;
+}
+
+/**
+ * TemplateSection - секция шаблона, связанная с Rule
+ */
+export interface TemplateSection {
+    /** Rule который создал эту секцию */
+    rule: Rule;
+    /** Оригинальный match */
+    match: RuleMatch;
+    /** Текущий результат */
+    result: RuleResult;
+    /** Исходный шаблон секции (для пересоздания) */
+    sourceTemplate: string;
+    /** Дочерние секции */
+    children: TemplateSection[];
+    /** Observable подписки для отслеживания */
+    subscriptions: Array<{ observable: Observable<any>; unsubscribe: () => void }>;
+}
+
+/**
+ * ObservableTracking - отслеживание Observable и связанных секций
+ */
+interface ObservableTracking {
+    observable: Observable<any>;
+    sections: Array<{
+        section: TemplateSection;
+        rebuild: (section: TemplateSection) => RuleResult;
+    }>;
+    unsubscribe: () => void;
+}
+
+/**
+ * PageTemplate - динамический шаблон страницы.
+ * Хранит обработанные Rule и поддерживает реактивное обновление.
+ * 
+ * При изменении Observable все зависимые секции обновляются
+ * одновременно в одном событии onTemplateChange.
+ */
+export default class TemplateInstance {
+    private template: string;
+    private scope: Scope;
+    private sections: TemplateSection[] = [];
+    private fragment: DocumentFragment | null = null;
+    
+    /** Observers for template changes */
+    private changeObserver = new MutationObserver<TemplateChangeEvent>();
+    
+    /** Группировка секций по Observable */
+    private observableTrackings = new Map<Observable<any>, ObservableTracking>();
+
+    constructor(template: string, scope: Scope) {
+        this.template = template;
+        this.scope = scope;
+    }
+
+    /**
+     * Получить текущий шаблон
+     */
+    public getTemplate(): string {
+        return this.template;
+    }
+
+    /**
+     * Установить новый шаблон (вызывает событие изменения)
+     */
+    public setTemplate(newTemplate: string): void {
+        const oldTemplate = this.template;
+        this.template = newTemplate;
+        
+        this.changeObserver.notify(
+            { oldValue: null, newValue: null, oldTemplate, newTemplate },
+            { oldValue: null, newValue: null, oldTemplate, newTemplate }
+        );
+    }
+
+    /**
+     * Получить Scope
+     */
+    public getScope(): Scope {
+        return this.scope;
+    }
+
+    /**
+     * Подписаться на изменения шаблона
+     */
+    public onTemplateChange(
+        listener: (oldValue: any, newValue: any, oldTemplate: string, newTemplate: string) => void
+    ): () => void {
+        const wrapper = (oldEvent: TemplateChangeEvent, newEvent: TemplateChangeEvent) => {
+            listener(newEvent.oldValue, newEvent.newValue, newEvent.oldTemplate, newEvent.newTemplate);
+        };
+        this.changeObserver.subscribe(wrapper);
+        return () => this.changeObserver.unsubscribe(wrapper);
+    }
+
+    /**
+     * Добавить секцию шаблона
+     */
+    public addSection(section: TemplateSection): void {
+        this.sections.push(section);
+    }
+
+    /**
+     * Получить все секции
+     */
+    public getSections(): TemplateSection[] {
+        return this.sections;
+    }
+
+    /**
+     * Подписаться на Observable и автоматически пересоздавать секцию.
+     * Все секции, зависящие от одного Observable, обновляются разом.
+     */
+    public trackObservable(
+        observable: Observable<any>,
+        section: TemplateSection,
+        rebuild: (section: TemplateSection) => RuleResult
+    ): () => void {
+        // Проверяем, есть ли уже отслеживание для этого Observable
+        let tracking = this.observableTrackings.get(observable);
+        
+        if (!tracking) {
+            // Создаём новое отслеживание
+            const listener = (newValue: any) => {
+                this.rebuildAllSectionsForObservable(observable, newValue);
+            };
+            
+            observable.subscribe(listener);
+            
+            tracking = {
+                observable,
+                sections: [],
+                unsubscribe: () => observable.unsubscribe(listener)
+            };
+            
+            this.observableTrackings.set(observable, tracking);
+        }
+        
+        // Добавляем секцию в отслеживание
+        tracking.sections.push({ section, rebuild });
+        
+        // Возвращаем функцию отписки для этой конкретной секции
+        return () => {
+            if (tracking) {
+                tracking.sections = tracking.sections.filter(s => s.section !== section);
+                
+                // Если больше нет секций, отписываемся от Observable
+                if (tracking.sections.length === 0) {
+                    tracking.unsubscribe();
+                    this.observableTrackings.delete(observable);
+                }
+            }
+        };
+    }
+
+    /**
+     * Перестроить все секции, зависящие от Observable, за один раз
+     */
+    private rebuildAllSectionsForObservable(observable: Observable<any>, newValue: any): void {
+        const tracking = this.observableTrackings.get(observable);
+        if (!tracking || tracking.sections.length === 0) return;
+
+        const oldTemplate = this.template;
+        let currentTemplate = this.template;
+
+        // Собираем все замены: старый output -> новый output
+        // Сортируем по позиции в шаблоне (с конца), чтобы замены не сбивали индексы
+        const replacements: Array<{ oldOutput: string; newOutput: string; section: TemplateSection }> = [];
+
+        for (const { section, rebuild } of tracking.sections) {
+            // Unsubscribe old nested observables
+            this.unsubscribeSectionNested(section);
+            
+            // Rebuild section
+            const newResult = rebuild(section);
+            const oldOutput = section.result.output;
+            
+            replacements.push({
+                oldOutput,
+                newOutput: newResult.output,
+                section
+            });
+            
+            section.result = newResult;
+        }
+
+        // Применяем все замены
+        for (const { oldOutput, newOutput } of replacements) {
+            currentTemplate = currentTemplate.replace(oldOutput, newOutput);
+        }
+
+        this.template = currentTemplate;
+
+        // Одно событие для всех изменений
+        this.changeObserver.notify(
+            { oldValue: null, newValue, oldTemplate, newTemplate: this.template },
+            { oldValue: null, newValue, oldTemplate, newTemplate: this.template }
+        );
+    }
+
+    /**
+     * Отписаться от вложенных Observable в секции (но не от главного)
+     */
+    private unsubscribeSectionNested(section: TemplateSection): void {
+        // Отписываемся только от подписок, сохранённых непосредственно в секции
+        for (const sub of section.subscriptions) {
+            sub.unsubscribe();
+        }
+        section.subscriptions = [];
+
+        // Recursively unsubscribe children
+        for (const child of section.children) {
+            this.unsubscribeSectionNested(child);
+        }
+    }
+
+    /**
+     * Отписаться от всех Observable в секции
+     */
+    private unsubscribeSection(section: TemplateSection): void {
+        for (const sub of section.subscriptions) {
+            sub.unsubscribe();
+        }
+        section.subscriptions = [];
+
+        // Recursively unsubscribe children
+        for (const child of section.children) {
+            this.unsubscribeSection(child);
+        }
+    }
+
+    /**
+     * Создать DocumentFragment из текущего шаблона
+     */
+    public createFragment(): DocumentFragment {
+        if (typeof document === 'undefined') {
+            throw new Error('PageTemplate.createFragment() requires DOM environment');
+        }
+
+        const template = document.createElement('template');
+        template.innerHTML = this.template;
+        this.fragment = template.content.cloneNode(true) as DocumentFragment;
+        
+        return this.fragment;
+    }
+
+    /**
+     * Получить кэшированный DocumentFragment
+     */
+    public getFragment(): DocumentFragment | null {
+        return this.fragment;
+    }
+
+    /**
+     * Пересоздать fragment
+     */
+    public rebuildFragment(): DocumentFragment {
+        this.fragment = null;
+        return this.createFragment();
+    }
+
+    /**
+     * Очистить все подписки
+     */
+    public dispose(): void {
+        // Отписываемся от всех Observable
+        for (const tracking of this.observableTrackings.values()) {
+            tracking.unsubscribe();
+        }
+        this.observableTrackings.clear();
+        
+        // Очищаем секции
+        for (const section of this.sections) {
+            this.unsubscribeSection(section);
+        }
+        this.sections = [];
+        this.fragment = null;
+    }
+
+    /**
+     * Привязать refs после вставки в DOM
+     */
+    public bindRefs(root: Element | DocumentFragment): void {
+        const refElements = root.querySelectorAll('[data-ref]');
+        
+        for (const element of Array.from(refElements)) {
+            const refName = element.getAttribute('data-ref');
+            if (refName) {
+                this.scope.set(refName, element);
+            }
+        }
+    }
+
+    /**
+     * Обработать инжекции (@injection[head/tail])
+     * Должен вызываться после bindRefs
+     */
+    public processInjections(root: Element | DocumentFragment): void {
+        // Find all elements with injection attributes
+        const injectElements = root.querySelectorAll('[data-injection-type][data-injection-target]');
+
+        for (const element of Array.from(injectElements)) {
+            const type = element.getAttribute('data-injection-type') as 'head' | 'tail';
+            const targetRefName = decodeURIComponent(element.getAttribute('data-injection-target') || '');
+
+            if (!targetRefName) continue;
+
+            // Get target element from scope
+            const targetElement = this.scope.get(targetRefName);
+
+            if (!targetElement || !(targetElement instanceof Element)) {
+                console.warn(`[PageTemplate] Injection target "${targetRefName}" not found in scope or is not an Element`);
+                continue;
+            }
+
+            // Remove injection attributes
+            element.removeAttribute('data-injection-type');
+            element.removeAttribute('data-injection-target');
+
+            // Perform injection
+            if (type === 'head') {
+                targetElement.prepend(element);
+            } else {
+                targetElement.append(element);
+            }
+        }
+    }
+
+    /**
+     * Отвязать refs (установить null)
+     */
+    public unbindRefs(): void {
+        for (const section of this.sections) {
+            if (section.rule.name === 'ref' && section.match.data?.expression) {
+                const refName = section.match.data.expression;
+                if (this.scope.has(refName)) {
+                    this.scope.set(refName, null);
+                }
+            }
+        }
+    }
+}

package/src/foundation/engine/exceptions/TemplateExceptions.ts

@@ -0,0 +1,27 @@
+/**
+ * InvalidDynamicRuleUsage - исключение при использовании Observable
+ * в правилах, которые не поддерживают динамическое обновление.
+ * Например: @[ref], @injection
+ */
+export class InvalidDynamicRuleUsage extends Error {
+    constructor(ruleName: string, message?: string) {
+        super(message ?? `Rule "${ruleName}" does not support Observable values. Use a static value instead.`);
+        this.name = 'InvalidDynamicRuleUsage';
+    }
+}
+
+/**
+ * InvalidTemplateEngineSyntaxException - исключение при синтаксических ошибках
+ * в шаблоне. Например: @if без boolean, @for с неверным типом.
+ */
+export class InvalidTemplateEngineSyntaxException extends Error {
+    public readonly line?: number;
+    public readonly column?: number;
+
+    constructor(message: string, options?: { line?: number; column?: number }) {
+        super(message);
+        this.name = 'InvalidTemplateEngineSyntaxException';
+        this.line = options?.line;
+        this.column = options?.column;
+    }
+}

package/src/foundation/engine/rules/attribute/EventRule.ts

@@ -0,0 +1,171 @@
+import { AttributeRule } from '../../Rule.js';
+import type { RuleMatch, RuleResult } from '../../Rule.js';
+import Scope from '../../Scope.js';
+import Expression from '../../Expression.js';
+
+interface EventMatch extends RuleMatch {
+    data: {
+        eventName: string;
+        expression: string;
+        attributeMatch: string;
+    };
+}
+
+/**
+ * EventRule - обработка @on[eventName]="expression"
+ * Подписывает элемент на событие.
+ */
+export default class EventRule extends AttributeRule {
+    public readonly name = 'event';
+    public readonly priority = 30;
+
+    public find(template: string): RuleMatch[] {
+        const results: RuleMatch[] = [];
+        // Match @on[eventName]="
+        const pattern = /@on\[([a-zA-Z]+)\]\s*=/gi;
+        let match: RegExpExecArray | null;
+
+        while ((match = pattern.exec(template)) !== null) {
+            const idx = match.index;
+
+            // Check for @@ escape
+            if (idx > 0 && template[idx - 1] === '@') {
+                continue;
+            }
+
+            const eventName = match[1].toLowerCase();
+
+            // Find quote char after =
+            let pos = idx + match[0].length;
+            while (pos < template.length && /\s/.test(template[pos])) {
+                pos++;
+            }
+
+            const quoteChar = template[pos];
+            if (quoteChar !== '"' && quoteChar !== "'") {
+                continue;
+            }
+
+            // Find matching closing quote
+            const contentStart = pos + 1;
+            pos++;
+            while (pos < template.length && template[pos] !== quoteChar) {
+                pos++;
+            }
+
+            if (pos >= template.length) continue;
+
+            const content = template.slice(contentStart, pos);
+            const fullMatch = template.slice(idx, pos + 1);
+
+            results.push({
+                fullMatch,
+                start: idx,
+                end: pos + 1,
+                data: {
+                    eventName,
+                    expression: content,
+                    attributeMatch: fullMatch
+                }
+            });
+        }
+
+        return results;
+    }
+
+    public execute(match: RuleMatch, scope: Scope): RuleResult {
+        const data = (match as EventMatch).data;
+        
+        // Generate data attribute for later DOM binding
+        // Actual event binding happens in postprocessing
+        const encodedExpr = encodeURIComponent(data.expression);
+        
+        return {
+            output: `data-event-${data.eventName}="${encodedExpr}"`,
+            observables: []
+        };
+    }
+
+    /**
+     * Постобработка: привязать события к элементам
+     */
+    public static bindEvents(element: Element, scope: Scope): (() => void)[] {
+        const unbinders: (() => void)[] = [];
+
+        // Find all data-event-* attributes
+        const attributes = Array.from(element.attributes);
+        
+        for (const attr of attributes) {
+            if (attr.name.startsWith('data-event-')) {
+                const eventName = attr.name.slice('data-event-'.length);
+                const exprCode = decodeURIComponent(attr.value);
+
+                const handler = (event: Event) => {
+                    // Create local scope with event
+                    const localScope = scope.createChild({ event });
+                    const expr = new Expression(exprCode);
+                    
+                    try {
+                        expr.execute(localScope);
+                    } catch (error) {
+                        console.error(`[EventRule] Error executing handler for ${eventName}:`, error);
+                    }
+                };
+
+                element.addEventListener(eventName, handler);
+                unbinders.push(() => element.removeEventListener(eventName, handler));
+
+                // Optionally remove the data attribute
+                // element.removeAttribute(attr.name);
+            }
+        }
+
+        return unbinders;
+    }
+
+    /**
+     * Привязать событие с поддержкой Observable
+     */
+    public static bindEventWithObservable(
+        element: Element,
+        eventName: string,
+        exprCode: string,
+        scope: Scope
+    ): () => void {
+        let currentHandler: ((event: Event) => void) | null = null;
+
+        const setupHandler = () => {
+            // Remove old handler if exists
+            if (currentHandler) {
+                element.removeEventListener(eventName, currentHandler);
+            }
+
+            currentHandler = (event: Event) => {
+                const localScope = scope.createChild({ event });
+                const expr = new Expression(exprCode);
+                
+                try {
+                    const result = expr.execute(localScope);
+                    
+                    // If result is Observable, handle it
+                    if (result && typeof result === 'object' && typeof result.subscribe === 'function') {
+                        // Re-setup handler when Observable changes
+                        result.subscribe(() => setupHandler());
+                    }
+                } catch (error) {
+                    console.error(`[EventRule] Error executing handler for ${eventName}:`, error);
+                }
+            };
+
+            element.addEventListener(eventName, currentHandler);
+        };
+
+        setupHandler();
+
+        return () => {
+            if (currentHandler) {
+                element.removeEventListener(eventName, currentHandler);
+            }
+        };
+    }
+}

package/src/foundation/engine/rules/attribute/InjectionRule.ts

@@ -0,0 +1,140 @@
+import { AttributeRule } from '../../Rule.js';
+import type { RuleMatch, RuleResult } from '../../Rule.js';
+import Scope from '../../Scope.js';
+import Expression from '../../Expression.js';
+import { InvalidDynamicRuleUsage } from '../../exceptions/TemplateExceptions.js';
+
+interface InjectionMatch extends RuleMatch {
+    data: {
+        type: 'head' | 'tail';
+        expression: string;
+        attributeMatch: string;
+    };
+}
+
+/**
+ * InjectionRule - обработка @injection[type]="expression"
+ * Инжектирует элемент в целевой элемент (найденный по @[ref]).
+ * type: 'head' = prepend, 'tail' = append
+ */
+export default class InjectionRule extends AttributeRule {
+    public readonly name = 'injection';
+    public readonly priority = 200; // Выполняется в самом конце
+
+    public find(template: string): RuleMatch[] {
+        const results: RuleMatch[] = [];
+        // Match @injection[head] or @injection[tail]
+        const pattern = /@injection\[(head|tail)\]\s*=/gi;
+        let match: RegExpExecArray | null;
+
+        while ((match = pattern.exec(template)) !== null) {
+            const idx = match.index;
+
+            // Check for @@ escape
+            if (idx > 0 && template[idx - 1] === '@') {
+                continue;
+            }
+
+            const injectionType = match[1].toLowerCase() as 'head' | 'tail';
+
+            // Find quote char after =
+            let pos = idx + match[0].length;
+            while (pos < template.length && /\s/.test(template[pos])) {
+                pos++;
+            }
+
+            const quoteChar = template[pos];
+            if (quoteChar !== '"' && quoteChar !== "'") {
+                continue;
+            }
+
+            // Find matching closing quote
+            const contentStart = pos + 1;
+            pos++;
+            while (pos < template.length && template[pos] !== quoteChar) {
+                pos++;
+            }
+
+            if (pos >= template.length) continue;
+
+            const content = template.slice(contentStart, pos);
+            const fullMatch = template.slice(idx, pos + 1);
+
+            results.push({
+                fullMatch,
+                start: idx,
+                end: pos + 1,
+                data: {
+                    type: injectionType,
+                    expression: content,
+                    attributeMatch: fullMatch
+                }
+            });
+        }
+
+        return results;
+    }
+
+    public execute(match: RuleMatch, scope: Scope): RuleResult {
+        const data = (match as InjectionMatch).data;
+        const expr = new Expression(data.expression);
+        const targetRefName = expr.execute(scope);
+
+        // Check if Observable - not allowed for @injection
+        if (targetRefName && typeof targetRefName === 'object' && typeof targetRefName.subscribe === 'function') {
+            throw new InvalidDynamicRuleUsage('@injection',
+                '@injection does not support Observable values. The target reference must be static.');
+        }
+
+        if (typeof targetRefName !== 'string') {
+            console.error(`[InjectionRule] Expression must return a string (reference name), got: ${typeof targetRefName}`);
+            return { output: '' };
+        }
+
+        // Store injection info for postprocessing
+        const encodedTarget = encodeURIComponent(targetRefName);
+
+        return {
+            output: `data-injection-type="${data.type}" data-injection-target="${encodedTarget}"`,
+            observables: []
+        };
+    }
+
+    public supportsObservable(): boolean {
+        return false;
+    }
+
+    /**
+     * Постобработка: выполнить инжекцию элементов
+     */
+    public static processInjections(root: Element | DocumentFragment, scope: Scope): void {
+        // Find all elements with injection attributes
+        const injectElements = root.querySelectorAll('[data-injection-type][data-injection-target]');
+
+        for (const element of Array.from(injectElements)) {
+            const type = element.getAttribute('data-injection-type') as 'head' | 'tail';
+            const targetRefName = decodeURIComponent(element.getAttribute('data-injection-target') || '');
+
+            if (!targetRefName) continue;
+
+            // Get target element from scope
+            const targetElement = scope.get(targetRefName);
+
+            if (!targetElement || !(targetElement instanceof Element)) {
+                console.warn(`[InjectionRule] Target element "${targetRefName}" not found in scope or is not an Element`);
+                continue;
+            }
+
+            // Remove injection attributes
+            element.removeAttribute('data-injection-type');
+            element.removeAttribute('data-injection-target');
+
+            // Perform injection
+            if (type === 'head') {
+                targetElement.prepend(element);
+            } else {
+                targetElement.append(element);
+            }
+        }
+    }
+}