@lark.js/mvc 0.0.15 → 0.0.17

package/dist/updater.d.ts

@@ -1,90 +0,0 @@
-import type { UpdaterInterface } from "./types";
-/**
- * Updater class for view data binding.
- * Manages view-local data with change detection and DOM diff triggering.
- *
- */
-export declare class Updater implements UpdaterInterface {
-    /** View ID (same as owner frame ID) */
-    private viewId;
-    /** Current data object */
-    private data;
-    /** Ref data for template rendering */
-    refData: Record<string, unknown>;
-    /** Changed keys in current digest cycle */
-    private changedKeys;
-    /** Whether data has changed since last digest */
-    private hasChangedFlag;
-    /**
-     * Digesting queue: supports re-digest during digest.
-     * Holds pending callbacks; `null` is used as a sentinel marking the start
-     * of an active digest cycle, so `runDigest` can detect re-entrant calls.
-     */
-    private digestingQueue;
-    /** Monotonically increasing version, bumped each time data actually changes. */
-    private version;
-    /** Snapshot of `version` taken by `snapshot()`, used by `altered()`. */
-    private snapshotVersion;
-    /** Last rendered VDOM tree (only used when virtualDom is enabled) */
-    private vdom?;
-    constructor(viewId: string);
-    /**
-     * Get data by key.
-     * Returns entire data object if key is omitted.
-     */
-    get<T = unknown>(key?: string): T;
-    /**
-     * Set data, tracking changed keys.
-     * Returns this for chaining.
-     */
-    set(data: Record<string, unknown>, excludes?: ReadonlySet<string>): this;
-    /**
-     * Detect changes and trigger DOM re-render.
-     *
-     * The core rendering pipeline:
-     * 1. Set data if provided
-     * 2. If changed, run DOM diff (template → new DOM → diff against old DOM)
-     * 3. Apply DOM operations
-     * 4. Apply ID updates
-     * 5. Call endUpdate on views that need re-rendering
-     * 6. Support re-digest during digest via queue
-     */
-    digest(data?: Record<string, unknown>, excludes?: ReadonlySet<string>, callback?: () => void): void;
-    /**
-     * Core digest execution.
-     */
-    private runDigest;
-    /**
-     * Save a snapshot of the current data version for `altered()` detection.
-     * Cheap O(1) — records the current monotonic version, no serialization.
-     */
-    snapshot(): this;
-    /**
-     * Check whether data has changed since the last snapshot.
-     * Returns undefined when no snapshot has been taken yet.
-     */
-    altered(): boolean | undefined;
-    /**
-     * Translate a refData reference back to its original value.
-     *
-     * The ref protocol is `SPLITTER` + ascii decimal digits — the exact format
-     * emitted by `refFn`. We require that exact shape so a user-supplied
-     * string that merely begins with SPLITTER is never accidentally resolved
-     * (or mishandled as a "missing ref").
-     */
-    translate(data: unknown): unknown;
-    /**
-     * Resolve a dotted property path against refData.
-     *
-     * Only safe property-path syntax is supported: `a`, `a.b`, `a.b.c`.
-     * Numeric literals (e.g. `1`, `1.5`) are returned as numbers. Anything else
-     * returns `undefined` — we no longer evaluate arbitrary JavaScript via
-     * `new Function`, so the method is CSP-safe and cannot be used as an
-     * injection vector.
-     */
-    parse(expr: string): unknown;
-    /**
-     * Get the set of keys changed since the last digest (for external inspection).
-     */
-    getChangedKeys(): ReadonlySet<string>;
-}

package/dist/url-state.d.ts

@@ -1,32 +0,0 @@
-import type { ViewInterface } from "./types";
-/**
- * Sync view state with URL query parameters.
- *
- * @param view - The view instance to bind to (for auto location observation and lifecycle)
- * @param initialState - Default values for each URL param key. Keys not present
- *   in the URL will use these defaults. Keys present in the URL override defaults.
- * @returns A tuple `[state, setState]`:
- *   - `state`: current values read from the URL, merged with defaults
- *   - `setState`: update URL params. Accepts a partial object or an updater function.
- *     Only the specified keys are changed; other URL params are preserved.
- *
- * @example
- * ```ts
- * export default View.extend({
- *   template,
- *   init() {
- *     const [state, setState] = useUrlState(this, { page: "1", size: "20" });
- *     this.updater.set({ page: state.page, size: state.size }).digest();
- *     this.setState = setState;
- *   },
- *   assign() {
- *     const [state] = useUrlState(this, { page: "1", size: "20" });
- *     this.updater.set({ page: state.page, size: state.size });
- *   },
- *   "nextPage<click>"() {
- *     this.setState((prev) => ({ page: String(Number(prev.page) + 1) }));
- *   },
- * });
- * ```
- */
-export declare function useUrlState<S extends Record<string, string>>(view: ViewInterface, initialState?: S): [Readonly<S>, (patch: Partial<S> | ((prev: S) => Partial<S>)) => void];

package/dist/utils.d.ts

@@ -1,90 +0,0 @@
-/**
- * Lark framework utility functions.
- */
-import type { AnyFunc, ParsedUri } from "./types";
-/**
- * Schedule a task for deferred execution.
- *
- * Tasks are processed in FIFO order within time-sliced batches (9ms budget).
- * When the budget is exceeded, the scheduler yields to the browser:
- * 1. scheduler.yield() — pause-resume within the same batch (Chrome 115+)
- * 2. setTimeout(0) — end batch, start a new one in the next event loop tick
- *
- * Use this to defer DOM operations and callbacks so that:
- * 1. Multiple view updates within the same digest cycle are batched
- * 2. The browser can process user input and paint between batches
- * 3. Very large updates are split across frames to maintain responsiveness
- *
- * @param fn - The function to execute
- * @param args - Arguments to pass to the function
- */
-export declare function callFunction<T extends unknown[]>(fn: (...args: T) => void, args: T): void;
-/** Check if value is a plain object (not null, not array, typeof object) */
-export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
-export declare function asRecord(value: unknown): Record<string, unknown>;
-/** Check if value is primitive or function (not a complex object) */
-export declare function isPrimitiveOrFunc(value: unknown): boolean;
-/** Check if value is primitive (not object, not function) */
-export declare function isPrimitive(value: unknown): boolean;
-export declare function generateId(prefix?: string): string;
-/** Sync local counter with global counter */
-export declare function syncCounter(val: number): void;
-export declare function noop(): void;
-/** Safe hasOwnProperty check */
-export declare function hasOwnProperty<T extends object>(owner: T | undefined | null, prop: PropertyKey): boolean;
-/** Get object keys (own enumerable) */
-export declare function keys<T extends object>(obj: T): string[];
-/** Assign properties from sources to target (like Object.assign but safer) */
-export declare function assign<T extends object>(target: T, ...sources: Partial<T>[]): T;
-/**
- * Execute functions in try-catch, ignoring errors.
- * Returns the result of the last successfully executed function.
- */
-export declare function funcWithTry(fns: AnyFunc | AnyFunc[], args: unknown[], context: unknown, configError?: (e: unknown) => void): unknown;
-/** Shared empty Set used as default value to avoid per-call allocation. */
-export declare const EMPTY_STRING_SET: ReadonlySet<string>;
-/**
- * Set newData into oldData, tracking changed keys.
- * Returns whether any value changed.
- */
-export declare function setData(newData: Record<string, unknown>, oldData: Record<string, unknown>, changedKeys: Set<string>, excludes: ReadonlySet<string>): boolean;
-/**
- * Translate compiled refData references back to their original values.
- *
- * A reference token has the exact shape `SPLITTER + ascii decimal digits`
- * (as emitted by `refFn`). This shape check ensures user data that
- * merely happens to begin with the SPLITTER character is never mistaken
- * for a ref.
- */
-export declare function translateData(data: object, value: unknown): unknown;
-/** Get element by ID, or return the element itself if already an element */
-export declare function getById(id: string | Element | null): Element | null;
-/** Get attribute from element safely */
-export declare function getAttribute(element: Element, attr: string): string;
-/** Ensure element has an ID, generating one if missing. Returns the ID. */
-export declare function ensureElementId(element: HTMLElement, prefix?: string): string;
-/**
- * Check if node A is inside node B (or is the same node).
- * Uses compareDocumentPosition for efficiency.
- */
-export declare function nodeInside(a: string | HTMLElement, b: string | HTMLElement): boolean;
-/**
- * Parse URI string into path and params object.
- * e.g. "/xxx/?a=b&c=d" => { path: "/xxx/", params: { a: "b", c: "d" } }
- *
- * The accumulator is function-local, so nested / re-entrant calls
- * (e.g. invoking `parseUri` again inside a replace callback) are safe.
- */
-export declare function parseUri(uri: string): ParsedUri;
-/**
- * Convert path and params to URI string.
- * e.g. toUri("/xxx/", { a: "b", c: "d" }) => "/xxx/?a=b&c=d"
- */
-export declare function toUri(path: string, params: Record<string, unknown>, keepEmpty?: ReadonlySet<string>): string;
-/**
- * Convert array to map/hash object.
- * For simple arrays, counts occurrences.
- * For object arrays, uses specified key as map key.
- */
-export declare function toMap<T>(list: T[] | null | undefined, key?: keyof T): Record<string, T | number>;

package/dist/vdom.d.ts

@@ -1,45 +0,0 @@
-import type { VDomNode, VDomRef, FrameInterface, ViewInterface } from "./types";
-/**
- * Create a virtual DOM node.
- *
- * Text node: `vdomCreate(0, 'text content')`
- * Element: `vdomCreate('div', { class: 'row' }, [child1, child2])`
- * Self-closing: `vdomCreate('br', null, 1)`
- * Raw HTML: `vdomCreate(0, '<b>bold</b>', 1)` (children truthy → raw HTML node)
- * Root: `vdomCreate(viewId, 0, [children])`
- */
-export declare function vdomCreate(tag: string | number, props?: Record<string, unknown> | string | number | null, children?: VDomNode[] | string | number | null, specials?: Record<string, string>): VDomNode;
-/**
- * Create a real DOM node from a VDomNode.
- *
- * Text node → `document.createTextNode(html)`
- * Element → `createElementNS` + `vdomSetAttributes` + `innerHTML`
- */
-export declare function vdomCreateNode(vnode: VDomNode, owner: Element, ref: VDomRef): ChildNode;
-/**
- * Set/update attributes on a real DOM element from a VDomNode.
- *
- * If `lastVDom` is provided, removes old attributes not present in new.
- * Special attributes are set as DOM properties; others via setAttribute.
- *
- * Returns 1 if any attribute changed, 0 otherwise.
- */
-export declare function vdomSetAttributes(realNode: Element, newVDom: VDomNode, ref: VDomRef, lastVDom?: VDomNode): number;
-/**
- * Diff children of a real DOM parent against old and new VDOM trees.
- *
- * Three-phase algorithm:
- * 1. Head fast-path: match identical nodes from the start
- * 2. Tail fast-path: match identical nodes from the end
- * 3. KeyMap reconciliation: build key→node index, process remaining children
- *
- * Old DOM node references are snapshotted before any mutations to ensure
- * correct removal regardless of DOM position shifts.
- *
- * Fast path: on first render (lastVDom undefined), sets innerHTML directly.
- */
-export declare function vdomSetChildNodes(realNode: Element, lastVDom: VDomNode | undefined, newVDom: VDomNode, ref: VDomRef, frame: FrameInterface, keys: ReadonlySet<string>, view: ViewInterface, ready: () => void): void;
-/**
- * Create an empty VDomRef for tracking diff operations.
- */
-export declare function createVDomRef(viewId: string): VDomRef;

package/dist/view-registry.d.ts

@@ -1,20 +0,0 @@
-import type { View } from "./view";
-/**
- * Look up a previously registered View class by path.
- * Returns `undefined` if no class is registered for `path`.
- */
-export declare function getViewClass(path: string): typeof View | undefined;
-/**
- * Register a View class for a given view path.
- * Called after module loading completes (or up front during boot).
- */
-export declare function registerViewClass(viewPath: string, ViewClass: typeof View): void;
-/**
- * Invalidate a View class from the registry.
- * Used by HMR to force re-loading of a view module.
- */
-export declare function invalidateViewClass(viewPath: string): void;
-/**
- * Get the full view class registry (for HMR / debugging).
- */
-export declare function getViewClassRegistry(): Record<string, typeof View>;

package/dist/view.d.ts

@@ -1,214 +0,0 @@
-import type { HotContext } from "./hmr";
-import type { AnyFunc, ViewInterface, ViewTemplate, FrameInterface, UpdaterInterface, ViewLocationObserved, ViewGlobalEventEntry, ViewEventSelectorEntry, ViewResourceEntry } from "./types";
-/**
- * Base View class.
- * Views are created via View.extend() and mounted by Frame.
- */
-export declare class View implements ViewInterface {
-    /** View ID (same as owner frame ID) */
-    id: string;
-    /** Owner frame */
-    owner: FrameInterface | number;
-    /** Updater instance */
-    updater: UpdaterInterface;
-    /** Signature: > 0 means active, incremented on render, 0 = destroyed */
-    signature: number;
-    /** Whether rendered at least once */
-    rendered?: boolean;
-    /** Whether view has template */
-    template?: ViewTemplate;
-    /** Location observation config */
-    locationObserved: ViewLocationObserved;
-    /** Observed state keys */
-    observedStateKeys?: string[];
-    /** Resource map */
-    resources: Record<string, ViewResourceEntry>;
-    /** Whether endUpdate pending */
-    endUpdatePending?: number;
-    /** Internal event storage */
-    private _events;
-    /** Prototype-stored event maps shape (set by View.prepare). */
-    private get protoEventState();
-    /**
-     * Event bitmask map: eventType -> bitmask (1=root, 2=selector).
-     * Read from prototype ($evtObjMap) set by View.prepare.
-     * Using a getter avoids ES6 class field shadowing the prototype value.
-     */
-    get eventObjectMap(): Record<string, number>;
-    /**
-     * Selector event map: eventType -> selector list.
-     * Read from prototype ($selMap) set by View.prepare.
-     */
-    get eventSelectorMap(): Record<string, ViewEventSelectorEntry>;
-    /**
-     * Global event list: [{handler, element, eventName, modifiers}].
-     * Read from prototype ($globalEvtList) set by View.prepare.
-     */
-    get globalEventList(): ViewGlobalEventEntry[];
-    /**
-     * Initialize view (called by Frame when mounting).
-     */
-    init(): void;
-    /**
-     * Render view template (called by Frame after init).
-     * Wrapped by View.wrapMethod to manage signature + resources.
-     */
-    render(): void;
-    on(event: string, handler: AnyFunc): this;
-    off(event: string, handler?: AnyFunc): this;
-    fire(event: string, data?: Record<string, unknown>, remove?: boolean, lastToFirst?: boolean): this;
-    /** Get the owning frame, asserting it has been bound. */
-    private get ownerFrame();
-    /**
-     * Notify view that HTML update is about to begin.
-     * Unmounts child frames in the update zone.
-     */
-    beginUpdate(id?: string): void;
-    /**
-     * Notify view that HTML update has ended.
-     * Mounts child frames in the update zone and runs deferred invokes.
-     */
-    endUpdate(id?: string, inner?: boolean): void;
-    /**
-     * Wrap an async callback to check view signature before executing.
-     * If the view has been re-rendered or destroyed, the callback is skipped.
-     */
-    wrapAsync<Fn extends AnyFunc>(fn: Fn, context?: unknown): (...args: Parameters<Fn>) => ReturnType<Fn> | undefined;
-    /**
-     * Observe location parameters or path changes.
-     * When observed keys change, render() is called automatically.
-     */
-    observeLocation(params: string | string[] | Record<string, unknown>, observePath?: boolean): void;
-    /**
-     * Observe State data keys for changes.
-     * When observed keys change via State.digest(), render() is called.
-     */
-    observeState(observedKeys: string | string[]): void;
-    /**
-     * Capture (register) a resource under a key.
-     * If a resource already exists at that key, it's destroyed first.
-     * When destroyOnRender=true, the resource is destroyed on next render call.
-     */
-    capture(key: string, resource?: unknown, destroyOnRender?: boolean): unknown;
-    /**
-     * Release a captured resource.
-     * If destroy=true, calls the resource's destroy() method.
-     */
-    release(key: string, destroy?: boolean): unknown;
-    /**
-     * Set up a leave confirmation for route changes and page unload.
-     */
-    leaveTip(message: string, condition: () => boolean): void;
-    /** Collected ctors from mixins */
-    static ctors?: AnyFunc[];
-    /**
-     * Prepare a View subclass by scanning its prototype for event method patterns.
-     * Pattern: `$?name<eventType1,eventType2>(&modifiers)`
-     *
-     * Only runs once per View subclass (guarded by ctors marker).
-     * Called from Frame.mountView before creating the view instance.
-     */
-    static prepare(oView: typeof View): AnyFunc[];
-    /**
-     * Bind or unbind event delegation for a view instance.
-     * Called from Frame during mount/unmount.
-     */
-    static delegateEvents(view: ViewInterface, destroy?: boolean): void;
-    /**
-     * Destroy all resources managed by a view.
-     * If lastly=true, destroy ALL resources; otherwise only destroyOnRender ones.
-     */
-    static destroyAllResources(view: ViewInterface, lastly: boolean): void;
-    /**
-     * Process deferred invoke calls on a frame.
-     */
-    static runInvokes(frame: FrameInterface): void;
-    /**
-     * Wrap a method on the prototype to add signature checking and resource cleanup.
-     */
-    private static wrapMethod;
-    /**
-     * When two mixins define the same event method, merge them into
-     * a single function that calls both in sequence.
-     */
-    private static processMixinsSameEvent;
-    /**
-     * Merge an array of mixin objects into the view prototype.
-     */
-    private static mergeMixins;
-    /**
-     * Destroy a single resource entry.
-     */
-    private static destroyResource;
-    /**
-     * Extend View to create a new View subclass.
-     *
-     * Supports:
-     * - props.ctor: constructor-like init (called with initParams + {node, deep})
-     * - props.mixins: array of mixin objects
-     * - Event method patterns: `'name<click>'` etc.
-     */
-    static extend(props?: ThisType<ViewInterface> & Record<string, unknown>, statics?: Record<string, unknown>): typeof View;
-    /**
-     * Merge mixins into View prototype.
-     */
-    static merge(this: typeof View, ...mixins: Record<string, unknown>[]): typeof View;
-    /**
-     * Set up HMR accept handler for this view module.
-     *
-     * When the module is hot-replaced, the new View class is extracted from
-     * the new module, registered in the view registry, and all currently
-     * mounted frames using this viewPath are re-mounted.
-     *
-     * No-op when `hot` is undefined (production / non-HMR environment).
-     *
-     * ```ts
-     * if (import.meta.hot) {
-     *   HomeView.accept(import.meta.hot, 'home');
-     * }
-     * ```
-     */
-    static accept(hot: HotContext | undefined, viewPath: string): void;
-    /**
-     * Set up HMR dispose handler for this view module.
-     *
-     * When the module is about to be replaced, the old View class is removed
-     * from the registry so subsequent lookups don't return the stale class.
-     *
-     * No-op when `hot` is undefined (production / non-HMR environment).
-     *
-     * ```ts
-     * if (import.meta.hot) {
-     *   HomeView.dispose(import.meta.hot, 'home');
-     * }
-     * ```
-     */
-    static dispose(hot: HotContext | undefined, viewPath: string): void;
-}
-/**
- * Type-safe wrapper around `View.extend()`.
- *
- * `View.extend({...})` accepts any object literal, and inside its methods
- * `this` is typed only as the base `ViewInterface` — so any custom state
- * field or helper method requires a `(this as MyView).foo` strong-cast at
- * every call site.
- *
- * `defineView()` threads the literal's own shape back into `this` via
- * `ThisType<P & ViewInterface>`, so `this.foo` is typed automatically:
- *
- * ```ts
- * const HomeView = defineView({
- *   $title: "Home",
- *   init() {
- *     this.updater.set({ title: this.$title }); // both typed
- *   },
- *   greet() {
- *     return `hello ${this.$title}`;
- *   },
- * });
- * ```
- *
- * Runtime semantics are identical to `View.extend(props, statics)` — this is
- * a zero-cost type-only wrapper.
- */
-export declare function defineView<P extends Record<string, unknown>>(props: P & ThisType<P & ViewInterface>, statics?: Record<string, unknown>): typeof View;