@lark.js/mvc 0.0.13 → 0.0.15

package/dist/dom.d.ts

@@ -0,0 +1,45 @@
+import type { DomRef, DomOp, FrameInterface } from "./types";
+/**
+ * Unmount frames within a DOM node.
+ */
+export declare function domUnmountFrames(frame: FrameInterface, node: ChildNode): void;
+/**
+ * Parse HTML string into a DOM element.
+ * Handles special elements (table, SVG, MathML) with wrapper elements.
+ */
+export declare function domGetNode(html: string, refNode: Element): Element;
+/**
+ * Get compare key for a DOM node (for keyed diff).
+ * Uses id or v-lark path.
+ */
+export declare function domGetCompareKey(node: ChildNode): string | undefined;
+/**
+ * Special diff for form elements (value, checked, selected).
+ * Form elements carry state on the DOM node (e.g. `input.value`) that isn't
+ * reflected in attributes, so we have to sync those properties separately.
+ */
+export declare function domSpecialDiff(oldNode: ChildNode, newNode: ChildNode): number;
+/**
+ * Set attributes from new element onto old element, tracking changes in ref.
+ */
+export declare function domSetAttributes(oldNode: Element, newNode: Element, ref: DomRef, keepId?: boolean): void;
+/**
+ * Set child nodes from new parent onto old parent using keyed diff algorithm.
+ */
+export declare function domSetChildNodes(oldParent: Element, newParent: Element, ref: DomRef, frame: FrameInterface, keys_?: ReadonlySet<string>): void;
+/**
+ * Diff two DOM nodes and apply changes.
+ */
+export declare function domSetNode(oldNode: ChildNode, newNode: ChildNode, oldParent: Element, ref: DomRef, frame: FrameInterface, keys_?: ReadonlySet<string>): void;
+/**
+ * Create an empty DomRef for tracking diff operations.
+ */
+export declare function createDomRef(): DomRef;
+/**
+ * Apply DOM diff operations to the DOM.
+ */
+export declare function applyDomOps(ops: DomOp[]): void;
+/**
+ * Apply ID updates from DOM diff.
+ */
+export declare function applyIdUpdates(updates: [Element, string][]): void;

package/dist/event-delegator.d.ts

@@ -0,0 +1,28 @@
+import type { FrameInterface } from "./types";
+/**
+ * DOM event delegation system.
+ * Delegates events to document body for performance.
+ *
+ */
+export declare const EventDelegator: {
+    /**
+     * Bind a DOM event type to document body.
+     */
+    bind(eventType: string, hasSelector?: boolean): void;
+    /**
+     * Unbind a DOM event type from document body.
+     */
+    unbind(eventType: string, hasSelector?: boolean): void;
+    /**
+     * Clean up range events for a destroyed view.
+     */
+    clearRangeEvents(viewId: string): void;
+    /**
+     * Set the frame getter function (called by Framework.boot).
+     */
+    setFrameGetter(getter: (id: string) => FrameInterface | undefined): void;
+    /**
+     * Get next element GUID.
+     */
+    nextElementGuid(): number;
+};

package/dist/event-emitter.d.ts

@@ -0,0 +1,38 @@
+import type { AnyFunc, ChangeEvent, EventEmitterInterface, EventListenerEntry } from "./types";
+/**
+ * Multi-cast event emitter class.
+ *
+ * @example
+ * const emitter = new EventEmitter();
+ * emitter.on('change', (data) => console.log(data));
+ * emitter.fire('change', { key: 'value' });
+ */
+export declare class EventEmitter<T = unknown> implements EventEmitterInterface<T> {
+    /** Event listeners: prefixed key -> listener array */
+    listeners: Map<string, EventListenerEntry[]>;
+    /** Number of `fire()` calls currently on the stack (re-entrancy depth). */
+    private firingDepth;
+    /** Keys whose listener list needs compaction after firing settles. */
+    private pendingCompaction;
+    /**
+     * Bind event listener.
+     */
+    on(event: string, handler: (this: T, e: ChangeEvent) => void): this;
+    /**
+     * Unbind event listener.
+     * If handler is provided, removes only that handler.
+     * If no handler, removes all handlers for the event.
+     */
+    off(event: string, handler?: AnyFunc): this;
+    /**
+     * Fire event, execute all bound handlers. Safe for re-entrant `off()` calls
+     * during dispatch: removed handlers are replaced with noop and compacted
+     * after the outermost fire returns.
+     *
+     * @param event - Event name
+     * @param data - Event data (type property added automatically)
+     * @param remove - Whether to remove all handlers after firing
+     * @param lastToFirst - Whether to execute handlers in reverse order
+     */
+    fire(event: string, data?: Record<string, unknown>, remove?: boolean, lastToFirst?: boolean): this;
+}

package/dist/frame.d.ts

@@ -0,0 +1,143 @@
+import { EventEmitter } from "./event-emitter";
+import { View } from "./view";
+import type { AnyFunc, FrameInterface, FrameInvokeEntry, ViewInterface } from "./types";
+/**
+ * Frame (View Frame) class for view lifecycle management.
+ * Each frame owns a view and manages child frames.
+ *
+ */
+export declare class Frame extends EventEmitter implements FrameInterface {
+    /** Frame ID (same as owner DOM element ID) */
+    readonly id: string;
+    /** Parent Frame ID */
+    private _parentId;
+    get parentId(): string | undefined;
+    /** Children map: id -> id */
+    childrenMap: Record<string, string>;
+    /** Children count */
+    childrenCount: number;
+    /** Ready count (children that have fired 'created') */
+    readyCount: number;
+    /** Set of child frame IDs that have fired 'created' */
+    readyMap: Set<string>;
+    /** View instance */
+    viewInstance?: ViewInterface;
+    /** Get view instance (read-only) */
+    get view(): ViewInterface | undefined;
+    /** Invoke list for deferred method calls */
+    invokeList: FrameInvokeEntry[];
+    /** Signature for async operation tracking */
+    signature: number;
+    /** Whether view has altered */
+    hasAltered: number;
+    /** Whether view is destroyed */
+    destroyed: number;
+    /** View path (v-lark attribute value) */
+    viewPath?: string;
+    /** Original template before mount */
+    originalTemplate?: string;
+    /** Hold fire created flag */
+    holdFireCreated: number;
+    /** Children created flag */
+    childrenCreated: number;
+    /** Children alter flag */
+    childrenAlter: number;
+    constructor(id: string, parentId?: string);
+    /**
+     * Mount a view to this frame.
+     *
+     * Complete flow:
+     * 1. Parse viewPath, translate query params from parent
+     * 2. Unmount current view
+     * 3. Load View class (via require or provided ViewClass)
+     * 4. View_Prepare (scan event methods)
+     * 5. Create View instance
+     * 6. View_DelegateEvents (bind DOM events)
+     * 7. Call view.init()
+     * 8. If view has template, call render via Updater
+     * 9. If no template, call endUpdate directly
+     */
+    mountView(viewPath: string, viewInitParams?: Record<string, unknown>): void;
+    /**
+     * Internal: actually mount the view after class is loaded.
+     */
+    doMountView(ViewClass: typeof View, params: Record<string, unknown>, node: HTMLElement, sign: number): void;
+    /**
+     * Unmount current view.
+     */
+    unmountView(): void;
+    /**
+     * Mount a child frame.
+     */
+    mountFrame(frameId: string, viewPath: string, viewInitParams?: Record<string, unknown>): FrameInterface;
+    /**
+     * Unmount a child frame.
+     */
+    unmountFrame(id?: string): void;
+    /**
+     * Mount all views in a zone.
+     */
+    mountZone(zoneId?: string): void;
+    /**
+     * Unmount all views in a zone.
+     */
+    unmountZone(zoneId?: string): void;
+    /**
+     * Get all child frame IDs.
+     */
+    children(): string[];
+    /**
+     * Get parent frame at given level.
+     * @param level - How many levels up (default 1)
+     */
+    parent(level?: number): Frame | undefined;
+    /**
+     * Invoke a method on the view.
+     */
+    invoke(name: string, args?: unknown[]): unknown;
+    /**
+     * Type-safe variant of `invoke`.
+     *
+     * `invoke()` accepts any string and any args, which silently hides
+     * mismatched call sites when a method gets renamed. `invokeTyped` carries
+     * the view's method signature through TypeScript so the compiler catches
+     * those mistakes:
+     *
+     * ```ts
+     * type Home = View & { loadData(id: string): Promise<void> };
+     * frame.invokeTyped<Home, "loadData">("loadData", ["user-1"]);
+     * ```
+     *
+     * Behavior is identical to `invoke` at runtime — same defer / direct-call
+     * paths — so it's a drop-in safer overload.
+     */
+    invokeTyped<V extends Record<string, unknown>, K extends keyof V & string>(name: K, args: V[K] extends (...a: infer A) => unknown ? A : never[]): V[K] extends (...a: never[]) => infer R ? R | undefined : unknown;
+    /** Get frame by ID */
+    static get(id: string): Frame | undefined;
+    /** Get all frames */
+    static getAll(): Map<string, Frame>;
+    /**
+     * Returns the existing root frame, or `undefined` if none has been created.
+     * Pure getter — never creates a Frame, never touches the DOM.
+     *
+     * Use `Frame.createRoot(id)` to create the root explicitly during framework
+     * boot. For Micro-Frontend hosts that own multiple independent containers,
+     * use `new Frame(containerId)` directly so each MF mount has its own root.
+     */
+    static getRoot(): Frame | undefined;
+    /**
+     * Create (or return) the singleton root frame for this app.
+     *
+     * Idempotent: subsequent calls always return the original root regardless
+     * of `rootId` — so passing a different id later is silently ignored.
+     * `Framework.boot()` is the canonical caller; user code rarely needs this.
+     */
+    static createRoot(rootId?: string): Frame;
+    /** Bind event listener (static) */
+    static on(event: string, handler: AnyFunc): typeof Frame;
+    /** Unbind event listener (static) */
+    static off(event: string, handler?: AnyFunc): typeof Frame;
+    /** Fire event (static) */
+    static fire(event: string, data?: Record<string, unknown>): void;
+}
+export { registerViewClass, invalidateViewClass, getViewClassRegistry, } from "./view-registry";

package/dist/framework.d.ts

@@ -0,0 +1,9 @@
+import type { FrameworkInterface } from "./types";
+/** Wait result: OK = rendered, TIMEOUT_OR_NOT_FOUND = not rendered */
+export declare const WAIT_OK = 1;
+export declare const WAIT_TIMEOUT_OR_NOT_FOUND = 0;
+/**
+ * Main framework object.
+ * Provides boot, config, and all global utility methods.
+ */
+export declare const Framework: FrameworkInterface;

package/dist/hmr.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Minimal HMR context interface.
+ * Compatible with Vite's `import.meta.hot` and webpack's `module.hot`.
+ * Defined here to avoid depending on bundler-specific type packages.
+ */
+export interface HotContext {
+    /** Accept a self-update. The callback receives the new module namespace. */
+    accept(cb?: (mod: {
+        default?: unknown;
+    } | undefined) => void): void;
+    /** Register a cleanup callback that runs before this module is replaced. */
+    dispose(cb: (data: unknown) => void): void;
+    /** Force a full page reload (fallback when HMR cannot handle the update). */
+    invalidate(): void;
+}
+/**
+ * Find all currently mounted frames whose viewPath matches the given path,
+ * and re-mount them.
+ *
+ * After a new View class is registered via `registerViewClass`, calling this
+ * function triggers `frame.mountView()` on each matching frame. Since the new
+ * class is already in the registry, `Frame.mountView` takes the synchronous
+ * path (`getViewClass` returns the class immediately).
+ *
+ * @param viewPath - The view path to match (e.g. 'home', 'components/list')
+ */
+export declare function reloadViews(viewPath: string): void;
+/**
+ * Set up the HMR accept handler for a view module.
+ *
+ * When the module is updated:
+ * 1. Extracts the new View class from the new module (default export or module itself)
+ * 2. Registers the new class in the view registry
+ * 3. Re-mounts all frames currently using this viewPath
+ *
+ * If the new module doesn't export a valid View class, falls back to
+ * `hot.invalidate()` which triggers a full page reload.
+ *
+ * @param hot - The HMR context (import.meta.hot)
+ * @param viewPath - The view path identifier (e.g. 'home')
+ */
+export declare function acceptView(hot: HotContext, viewPath: string): void;
+/**
+ * Set up the HMR dispose handler for a view module.
+ *
+ * When the module is about to be replaced, removes the old View class
+ * from the registry so that subsequent `getViewClass` calls don't return
+ * the stale class.
+ *
+ * @param hot - The HMR context (import.meta.hot)
+ * @param viewPath - The view path identifier (e.g. 'home')
+ */
+export declare function disposeView(hot: HotContext, viewPath: string): void;