@mintjamsinc/ichigojs 0.1.81 → 0.1.83

package/dist/types/ichigo/ExpressionEvaluator.d.ts

@@ -0,0 +1,118 @@
+import { VBindings } from "./VBindings";
+/**
+ * Options for expression evaluation.
+ */
+export interface ExpressionEvaluatorOptions {
+    /**
+     * Additional context variables to be available in the expression (e.g., 'event', '$ctx').
+     */
+    additionalContext?: Record<string, any>;
+    /**
+     * If true, allows assignment expressions (e.g., "count++", "value = 10").
+     * This is used by VOnDirective to support inline assignments.
+     * Default: false
+     */
+    allowAssignment?: boolean;
+    /**
+     * A custom function to rewrite the expression before evaluation.
+     * This is used by VOnDirective to transform identifiers into 'this.identifier' form.
+     */
+    rewriteExpression?: (expression: string, identifiers: string[]) => string;
+}
+/**
+ * A centralized expression evaluator that normalizes expression evaluation across all directives.
+ *
+ * This class provides:
+ * - Consistent identifier extraction and binding resolution
+ * - Unified global object whitelisting (Math, Date, JSON, etc.)
+ * - Expression caching for performance
+ * - Centralized error handling
+ * - Support for custom expression rewriting (for VOnDirective)
+ *
+ * Example usage:
+ * ```typescript
+ * const evaluator = ExpressionEvaluator.create(
+ *   "count + 1",
+ *   bindings,
+ *   functionDependencies
+ * );
+ * const result = evaluator.evaluate();
+ * ```
+ */
+export declare class ExpressionEvaluator {
+    /**
+     * Cache for compiled expression functions.
+     * Key: expression string
+     * Value: compiled function
+     */
+    private static readonly cache;
+    /**
+     * Global objects that are whitelisted for use in expressions.
+     * These objects are available to all expressions for convenience and compatibility.
+     */
+    private static readonly GLOBAL_WHITELIST;
+    /**
+     * The original expression string.
+     */
+    private readonly expression;
+    /**
+     * The identifiers extracted from the expression.
+     */
+    private readonly identifiers;
+    /**
+     * The bindings to use for evaluating the expression.
+     */
+    private readonly bindings;
+    /**
+     * The compiled function for evaluating the expression.
+     */
+    private readonly evaluatorFunc;
+    /**
+     * Additional context variables (e.g., 'event', '$ctx').
+     */
+    private readonly additionalContext?;
+    /**
+     * Private constructor. Use ExpressionEvaluator.create() to create instances.
+     */
+    private constructor();
+    /**
+     * Creates an ExpressionEvaluator instance.
+     *
+     * @param expression The expression string to evaluate.
+     * @param bindings The bindings to use for evaluating the expression.
+     * @param functionDependencies A dictionary mapping function names to their dependencies.
+     * @param options Optional configuration for the evaluator.
+     * @returns An ExpressionEvaluator instance.
+     */
+    static create(expression: string, bindings: VBindings, functionDependencies: Record<string, string[]>, options?: ExpressionEvaluatorOptions): ExpressionEvaluator;
+    /**
+     * Compiles an expression into a function.
+     *
+     * @param expression The expression string to compile.
+     * @param identifiers The identifiers extracted from the expression.
+     * @param options Optional configuration.
+     * @returns A compiled function.
+     */
+    private static compileExpression;
+    /**
+     * Evaluates the expression with the current bindings.
+     *
+     * @returns The result of the expression evaluation.
+     */
+    evaluate(): any;
+    /**
+     * Evaluates the expression and returns the result as a boolean.
+     *
+     * @returns The boolean result of the expression evaluation.
+     */
+    evaluateAsBoolean(): boolean;
+    /**
+     * Gets the list of identifiers extracted from the expression.
+     */
+    get dependentIdentifiers(): string[];
+    /**
+     * Clears the expression cache.
+     * This should be called sparingly, as it will force recompilation of all expressions.
+     */
+    static clearCache(): void;
+}

package/dist/types/ichigo/VComponent.d.ts

@@ -0,0 +1,2 @@
+export declare class VComponent {
+}

package/dist/types/ichigo/VComponentRegistry.d.ts

@@ -0,0 +1,2 @@
+export declare class VComponentRegistry {
+}

package/dist/types/ichigo/VNode.d.ts

@@ -175,6 +175,7 @@ export declare class VNode {
      * 4. Unregister dependencies
      * 5. Clean up directive manager
      * 6. Call onUnmounted lifecycle hooks
+     * 7. Leave the parent's child list
      */
     destroy(): void;
 }

package/dist/types/ichigo/VUpdateContext.d.ts

@@ -0,0 +1,21 @@
+import { VBindings } from "./VBindings";
+/**
+ * Context provided during the update of the virtual DOM.
+ * This context includes the current bindings and a list of identifiers that have changed.
+ */
+export interface VUpdateContext {
+    /**
+     * The current bindings.
+     */
+    bindings: VBindings;
+    /**
+     * A list of variable and function names whose values have changed.
+     */
+    changedIdentifiers: string[];
+    /**
+     * Indicates if this is the initial update.
+     * This flag is true when the update is being performed for the first time after the VNode's creation.
+     * It can be used to optimize rendering or initialization logic that should only run once.
+     */
+    isInitial?: boolean;
+}

package/dist/types/ichigo/components/IchigoElement.d.ts

@@ -36,9 +36,13 @@ export interface ScopedSlotEntry {
  *    microtask fires, so data() can read them. A component used without any prop
  *    binding still mounts — with its declared defaults — instead of waiting forever.
  *
- * Slot content is captured on the first connection and cached, so a component
- * that is moved in the DOM (e.g. reordered by v-for) re-expands its template
- * and redistributes the same slot nodes on reconnection.
+ * Slot content is captured on the first expansion and cached. The nodes are the
+ * parent application's compiled nodes and are only ever moved, never cloned:
+ * each `<slot>` outlet the component renders moves them into place
+ * (VStaticSlotOutletDirective; scoped `<template v-slot>` content is rendered
+ * per outlet by VSlotOutletDirective instead). A component that is moved in
+ * the DOM (e.g. reordered by v-for) re-expands its template, and its outlets
+ * move the same nodes into the fresh expansion.
  *
  * Subclasses must set the static fields _template, _props, _propOptions and
  * _buildOptions before calling customElements.define(). defineComponent()
@@ -76,6 +80,13 @@ export declare class IchigoElement extends HTMLElement {
      * VSlotOutletDirective when the component template renders a `<slot>`.
      */
     get _ichigoScopedSlots(): Map<string, ScopedSlotEntry> | undefined;
+    /**
+     * The static slot content captured for the given slot name ('default'
+     * for the unnamed slot): the parent application's nodes, moved into place
+     * by VStaticSlotOutletDirective. Undefined when nothing was provided for
+     * that name, in which case the outlet's fallback content renders.
+     */
+    _ichigoSlotNodes(name: string): Node[] | undefined;
     /**
      * Handles RE-attachment, and nothing else.
      *

package/dist/types/ichigo/directives/VBindingsPreparer.d.ts

@@ -0,0 +1,24 @@
+import { VBindings } from "../VBindings";
+/**
+ * Interface representing a preparer for VBindings in the virtual DOM.
+ */
+export interface VBindingsPreparer {
+    /**
+     * The list of identifiers that this preparer is concerned with.
+     * These identifiers are used to determine when the bindings need to be prepared.
+     */
+    get identifiers(): string[];
+    /**
+     * The list of identifiers that can be prepared by this preparer.
+     * This is a subset of the identifiers property.
+     */
+    get preparableIdentifiers(): string[];
+    /**
+     * Prepares the VBindings for the virtual node.
+     * This method is called before the bindings are applied to the DOM.
+     * It allows for any necessary transformations or initializations of the bindings.
+     * @param bindings The original VBindings to be prepared.
+     * @returns The prepared VBindings.
+     */
+    prepareBindings(bindings: VBindings): VBindings;
+}

package/dist/types/ichigo/directives/VDOMUpdater.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface representing an updater for the virtual DOM.
+ * An implementation of this interface is responsible for applying changes
+ * from the virtual DOM to the actual DOM.
+ */
+export interface VDOMUpdater {
+    /**
+     * A list of variable and function names that this updater is concerned with.
+     * Changes to these identifiers may trigger the updater to apply changes to the DOM.
+     */
+    get identifiers(): string[];
+    /**
+     * Applies the changes from the virtual DOM to the actual DOM.
+     * This method is called when the identifiers change or when an update is needed.
+     */
+    applyToDOM(): void;
+}

package/dist/types/ichigo/directives/VSlotOutletDirective.d.ts

@@ -26,9 +26,9 @@ import { VDOMUpdater } from "../VDOMUpdater";
  * ```
  *
  * This directive is created only when a scoped template for the slot's name
- * exists (see {@link VSlotOutletDirective.tryCreate}); otherwise `<slot>`
- * elements keep their existing behavior (static distribution at expansion,
- * or fallback content compiled in the component scope).
+ * exists (see {@link VSlotOutletDirective.tryCreate}); otherwise plain slot
+ * content is moved into place by VStaticSlotOutletDirective, and a `<slot>`
+ * with no content at all renders its fallback in the component scope.
  *
  * Rendering happens synchronously in onMount — before the component
  * application would compile the slot's fallback children — by replacing the

package/dist/types/ichigo/directives/VStaticSlotOutletDirective.d.ts

@@ -0,0 +1,129 @@
+import type { VNode } from "../VNode";
+import { VBindingsPreparer } from "../VBindingsPreparer";
+import { VDirective } from "./VDirective";
+import { VDOMUpdater } from "../VDOMUpdater";
+/**
+ * Renders a static slot outlet: a `<slot>` element inside a component template
+ * whose host element received plain slot content from the parent — child
+ * nodes for the default slot, or elements carrying `slot="name"`:
+ *
+ * ```html
+ * <!-- component template -->
+ * <div v-if="open" class="body"><slot></slot></div>
+ *
+ * <!-- usage -->
+ * <my-dialog :open="show">
+ *   <my-field :label="title"></my-field>
+ * </my-dialog>
+ * ```
+ *
+ * The slot content is the parent application's own nodes, compiled in the
+ * parent scope; it keeps its bindings, listeners and component props only as
+ * long as those very nodes are displayed. So the outlet MOVES them into place
+ * and never clones them. That is what lets a `<slot>` sit behind a v-if or
+ * v-for in the component template: the directive clones its template source,
+ * the clone carries a fresh `<slot>`, and the outlet created for that clone
+ * moves the live nodes in.
+ *
+ * Nodes can only be in one place, so when the same slot is rendered more than
+ * once (e.g. a `<slot>` inside a v-for), the outlet rendered last receives the
+ * content and the earlier ones are left empty. When the outlet holding the
+ * content goes away while others remain (its row is removed), the content
+ * moves to the last remaining one. For content per row, use a scoped slot
+ * (`<template v-slot:name="scope">`), which renders a copy per outlet
+ * (VSlotOutletDirective).
+ *
+ * The component application never compiles the moved nodes: they are placed
+ * in onMount, after the parent VNode has taken its snapshot of the children
+ * to compile. Components inside them belong to the parent application, which
+ * expands them through {@link expandComponents} once they are in the document.
+ * When the last outlet goes away (its v-if turns false) the nodes leave with
+ * the removed clone and wait there until the next outlet moves them again;
+ * they are not destroyed, because they are not this application's to destroy.
+ *
+ * Created only when the host captured content for the slot's name and no
+ * scoped template claims it; otherwise the `<slot>` element renders its
+ * fallback children in the component scope.
+ */
+export declare class VStaticSlotOutletDirective implements VDirective {
+    #private;
+    /**
+     * Creates a static slot outlet for the given `<slot>` VNode when the host
+     * element captured content for its slot name. Returns undefined when there
+     * is none, so the `<slot>` element keeps rendering its fallback content.
+     */
+    static tryCreate(vNode: VNode): VStaticSlotOutletDirective | undefined;
+    private constructor();
+    /**
+     * @inheritdoc
+     */
+    get name(): string;
+    /**
+     * @inheritdoc
+     */
+    get vNode(): VNode;
+    /**
+     * @inheritdoc
+     */
+    get needsAnchor(): boolean;
+    /**
+     * @inheritdoc
+     */
+    get bindingsPreparer(): VBindingsPreparer | undefined;
+    /**
+     * @inheritdoc
+     */
+    get domUpdater(): VDOMUpdater | undefined;
+    /**
+     * @inheritdoc
+     */
+    get templatize(): boolean;
+    /**
+     * @inheritdoc
+     */
+    get dependentIdentifiers(): string[];
+    /**
+     * @inheritdoc
+     *
+     * Moves the slot content in place of the `<slot>` element — synchronously
+     * during VNode construction, before the component application would
+     * compile the slot's fallback children (which the content replaces).
+     */
+    get onMount(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     */
+    get onMounted(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     */
+    get onUpdate(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     */
+    get onUpdated(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     */
+    get onUnmount(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     */
+    get onUnmounted(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     *
+     * Expands the components in the slot content through the parent
+     * application's VNodes. Called by the walk of whoever inserted this
+     * outlet into the document (VApplication.mount, v-if, v-for), so the
+     * content is connected by now — unless a later outlet took it, in which
+     * case that outlet's walk expands it.
+     */
+    expandComponents(): void;
+    /**
+     * @inheritdoc
+     *
+     * The slot content is the parent application's; nothing to release here.
+     */
+    destroy(): void;
+}

package/dist/types/ichigo/util/BindingsUtils.d.ts

@@ -0,0 +1,10 @@
+import { VBindings } from "../VBindings";
+export declare class BindingsUtils {
+    /**
+     * Gets the identifiers that have changed between two sets of bindings.
+     * @param oldBindings The old set of bindings.
+     * @param newBindings The new set of bindings.
+     * @returns An array of identifiers that have changed.
+     */
+    static getChangedIdentifiers(oldBindings: VBindings, newBindings: VBindings): string[];
+}

package/dist/types/ichigo/util/VLogLevel.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Log level enumeration.
+ */
+export declare enum VLogLevel {
+    DEBUG = "debug",
+    INFO = "info",
+    WARN = "warn",
+    ERROR = "error"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintjamsinc/ichigojs",
-  "version": "0.1.81",
+  "version": "0.1.83",
   "description": "ichigo.js - Simple and intuitive reactive framework. Lightweight, fast, and user-friendly virtual DOM library",
   "main": "./dist/ichigo.cjs",
   "module": "./dist/ichigo.esm.js",