@saolabs/client 1.0.0

package/src/core/view/LoopContext.ts

@@ -0,0 +1,109 @@
+import type { LoopContextInterface } from "../contracts/LoopContextInterface";
+
+/**
+ * LoopContext — provides loop metadata for @foreach, @for, @while directives.
+ * 
+ * Available properties inside loops:
+ *   $loop.index      — 0-based index
+ *   $loop.iteration  — 1-based iteration count
+ *   $loop.count      — total items (or -1 for @while)
+ *   $loop.remaining  — items left
+ *   $loop.first      — is first iteration
+ *   $loop.last       — is last iteration
+ *   $loop.odd        — is odd iteration (1-based)
+ *   $loop.even       — is even iteration (1-based)
+ *   $loop.depth      — nesting depth (starts at 1)
+ *   $loop.parent     — parent LoopContext (for nested loops)
+ */
+export class LoopContext implements LoopContextInterface {
+    public index: number = 0;
+    public iteration: number = 0;
+    public count: number = 0;
+    public remaining: number = -1;
+    public first: boolean = false;
+    public last: boolean = false;
+    public odd: boolean = true;
+    public even: boolean = false;
+    public depth: number = 1;
+    public parent: LoopContext | null;
+
+    private type: 'increment' | 'decrement' = 'increment';
+
+    constructor(parent: LoopContext | null = null) {
+        this.parent = parent;
+        if (parent) {
+            this.depth = parent.depth + 1;
+        }
+    }
+
+    setType(type: 'increment' | 'decrement'): void {
+        if (type === 'increment' || type === 'decrement') {
+            this.type = type;
+        }
+    }
+
+    setCount(count: number): void {
+        this.count = count;
+        if (count === -1) {
+            // Unknown count (@while) — remaining/last unreliable
+            this.remaining = -1;
+            this.last = false;
+        } else {
+            this.remaining = count;
+        }
+    }
+
+    setCurrentTimes(index: number): void {
+        this.index = index;
+        this.iteration = index + 1;
+        this.first = index === 0;
+        this.last = this.count > 0 ? index === this.count - 1 : false;
+        this.odd = this.iteration % 2 === 1;
+        this.even = !this.odd;
+        if (this.count > 0) {
+            this.remaining = this.count - this.iteration;
+        }
+    }
+
+    next(): void {
+        if (this.type === 'increment') {
+            this.increment();
+        } else {
+            this.decrement();
+        }
+    }
+
+    reset(): void {
+        this.iteration = 0;
+        this.index = 0;
+        this.remaining = -1;
+        this.count = 0;
+        this.first = false;
+        this.last = false;
+        this.odd = true;
+        this.even = false;
+    }
+
+    private increment(): void {
+        this.iteration++;
+        this.index = this.iteration - 1;
+        if (this.remaining !== -1) {
+            this.remaining--;
+        }
+        this.first = this.index === 0;
+        this.last = this.count > 0 ? this.index === this.count - 1 : false;
+        this.odd = this.iteration % 2 === 1;
+        this.even = !this.odd;
+    }
+
+    private decrement(): void {
+        this.iteration--;
+        this.index = this.iteration - 1;
+        if (this.remaining !== -1) {
+            this.remaining++;
+        }
+        this.last = this.count > 0 ? this.index === this.count - 1 : false;
+        this.odd = this.iteration % 2 === 1;
+        this.even = !this.odd;
+    }
+}

package/src/core/view/Section.ts

@@ -0,0 +1,86 @@
+import { HtmlInterface } from "../contracts/ElementInterface";
+import { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { SectionConstruvtorArgs, SectionContentRenderer, SectionContentType, SectionInterface, SectionItemType } from "../contracts/views";
+
+export class Section implements SectionInterface {
+    ctx: ViewControllerInterface | undefined | null = null;
+    name: string;
+    type: SectionItemType;
+    contentType: SectionContentType;
+    stateKeys?: string[];
+    
+    renderFactory: SectionContentRenderer;
+    subscribeFn: (() => void) | null = null;
+    unsubscribeFn: (() => void) | null = null;
+
+    content: any = null; // Can be string or OneElementChildren depending on contentType
+
+    parentElement: HtmlInterface | undefined | null = null; // For dynamic/reactive sections that need a parent element reference
+
+    isStarted: boolean = false; // Flag to indicate if this section is static (renders once) or dynamic/reactive (renders on state change)
+
+    constructor({ ctx, name, type = 'static', contentType = 'text', stateKeys, renderFactory }: SectionConstruvtorArgs) {
+        this.ctx = ctx ?? null;
+        this.name = name;
+        this.type = type;
+        this.contentType = contentType;
+        this.stateKeys = stateKeys;
+        this.renderFactory = renderFactory;
+        
+        this.initialize();
+    }
+
+    initialize() {
+        if (this.type === 'static') {
+            this.render();
+        }
+        this.start();
+
+    }
+
+    render(parentElement?: HtmlInterface | null | undefined) {
+        this.parentElement = parentElement ?? null;
+        this.content = this.renderFactory(this.parentElement);
+    }
+
+    start() {
+        if(this.isStarted) return; // No need to subscribe for static sections
+        this.isStarted = true;
+        if ((this.type === 'reactive' || this.type === 'dynamic') && this.stateKeys && this.ctx) {
+            this.subscribeFn = () => {
+                this.render(this.parentElement);
+            };
+            this.unsubscribeFn = this.ctx.states.subscribe(this.stateKeys, this.subscribeFn);
+        }
+        
+    }
+
+    stop() {
+        if (!this.isStarted) return;
+        this.isStarted = false;
+        if (this.unsubscribeFn) {
+            this.unsubscribeFn();
+            this.unsubscribeFn = null;
+        }
+    }
+}
+
+/**
+ * Note: The "Section" concept is being phased out in favor of a more flexible Block/BlockOutlet system.
+ * Sections are still supported for backward compatibility but may be deprecated in future versions.
+ * For new development, consider using Blocks instead of Sections for better flexibility and composability.
+ * 
+ * --- CHANGELOG ---
+ * vX.X.X - Introduced Block/BlockOutlet system as a more flexible alternative to Sections.
+ *   - Sections are now considered legacy and may be deprecated in future versions.
+ *   - ViewController's section management is being refactored to support Blocks instead of Sections.
+ *   - Updated documentation and examples to encourage use of Blocks over Sections.
+ * 
+ * --- FUTURE PLANS ---
+ * - Phase out Sections entirely in favor of Blocks, which offer more composability and dynamic capabilities.
+ * - Provide migration guides for existing users to transition from Sections to Blocks.
+ * - Enhance Block system with features like nested blocks, dynamic block registration, and improved lifecycle management.
+ * 
+ * --- CURRENT RECOMMENDATION ---
+ * For new views, prefer using Blocks and BlockOutlets for layout composition instead of Sections. Sections will still work but are not recommended for new development.
+ */

package/src/core/view/View.ts

@@ -0,0 +1,109 @@
+import type { ViewControllerInterface, ViewType } from "../contracts/ViewControllerInterface";
+import type { ViewInterface, ViewLifecycleHooks } from "../contracts/ViewInterface";
+import type { OneObjectType } from "../types/utils";
+import { ViewController } from "./ViewController";
+
+/**
+ * View — the base class for all views in OneView.
+ * 
+ * A View is the unit that the user writes. It contains:
+ *   - User-defined properties (reactive state, computed values)
+ *   - User-defined methods (event handlers, business logic)
+ *   - Lifecycle hooks (onInit, onMounted, onUpdated, onDestroy)
+ *   - A ViewController (hidden as __ctrl__) that manages everything internally
+ * 
+ * The ViewController is non-enumerable so it doesn't show up in serialization
+ * or when iterating over the View's properties.
+ * 
+ * Usage:
+ *   Typically the compiler generates a subclass of View with $__setup__
+ *   that declares state, methods, and the render factory.
+ * 
+ * @example
+ * // Compiled output from counter.one:
+ * class CounterView extends View {
+ *     $__setup__() {
+ *         const [count, setCount] = this.__ctrl__.states.__.useState(0, 'count');
+ *         this.count = count;
+ *         this.setCount = setCount;
+ *         this.increment = () => setCount(this.count + 1);
+ *     }
+ * }
+ */
+export class View implements ViewInterface, ViewLifecycleHooks {
+    public __ctrl__!: ViewController;
+    [key: string]: any;
+
+    constructor(path: string, viewType: ViewType = 'view', viewControllerClass?: any) {
+        const CtrlClass = viewControllerClass ?? ViewController;
+        const controller = new CtrlClass(this, path, viewType);
+
+        // Store controller as non-enumerable, non-writable property
+        Object.defineProperty(this, '__ctrl__', {
+            value: controller,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        });
+    }
+
+    /**
+     * Setup hook — called by framework after construction.
+     * Compiled .one output overrides this to declare state, methods, render factory.
+     * 
+     * @param __data__    — Route params, props, etc.
+     * @param systemData  — System-level data (SSR data, global config, etc.)
+     */
+    $__setup__(__data__: Record<string, any> = {}, systemData: Record<string, any> = {}): void {
+        // Override in subclass
+    }
+
+    // ─── Lifecycle Hooks ────────────────────────────────────────
+    // Users can override these in their view class
+
+    onInit?(): void | Promise<void>;
+    onMounted?(): void | Promise<void>;
+    onUpdated?(): void | Promise<void>;
+    onDestroy?(): void | Promise<void>;
+    onActivated?(): void | Promise<void>;
+    onDeactivated?(): void | Promise<void>;
+
+    // ─── Convenience Accessors ──────────────────────────────────
+
+    get path(): string {
+        return this.__ctrl__.path;
+    }
+
+    get viewType(): ViewType {
+        return this.__ctrl__.viewType;
+    }
+
+    /** Shortcut to controller */
+    get __(): ViewController {
+        return this.__ctrl__;
+    }
+
+    /** Shortcut to ViewState */
+    get $state(): any {
+        return this.__ctrl__.states;
+    }
+    get oneType(): OneObjectType {
+        return 'View';
+    }
+    set oneType(value: OneObjectType) {
+        // No-op setter to satisfy the Interface; this property is always 'View'
+    }
+
+    get parent(): ViewInterface | null {
+        return this.__ctrl__.getParentView();
+    }
+    get children(): ViewInterface[] {
+        return this.__ctrl__.getChildrenViews();
+    }
+    get superView(): ViewInterface | null {
+        return this.__ctrl__.getSuperView();
+    }
+    get originView(): ViewInterface | null {
+        return this.__ctrl__.getOriginView();
+    }
+}