@lark.js/mvc 0.0.11 → 0.0.13

package/dist/index.d.cts

@@ -63,26 +63,6 @@ declare function mark(host: object, key: string): () => boolean;
  */
 declare function unmark(host: object): void;
 
-/**
- * Safeguard: Proxy-based debug protection for data objects.
- *
- * In DEBUG mode, wraps data objects with Proxy to:
- * 1. Warn when data is read from a different page than where it was set
- * 2. Prevent direct mutation (forces use of State.set/digest)
- * 3. Track access patterns for debugging
- */
-/**
- * Wrap data with a Proxy for debug-mode protection.
- * Only active when window.__lark_Debug is true and Proxy is available.
- *
- * @param data - Data to wrap
- * @param getter - Optional callback when properties are read
- * @param setter - Optional callback when properties are written
- * @param isRoot - Whether this is the root data object
- * @returns Proxied data or original data if debug mode is off
- */
-declare function safeguard<T>(data: T, getter?: ((key: string) => void) | null, setter?: ((path: string, value: unknown) => void) | null, isRoot?: boolean): T;
-
 /**
  * Multi-cast event emitter class.
  *
@@ -121,6 +101,34 @@ declare class EventEmitter<T = unknown> implements EventEmitterInterface<T> {
     fire(event: string, data?: Record<string, unknown>, remove?: boolean, lastToFirst?: boolean): this;
 }
 
+/**
+ * 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.
+ */
+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')
+ */
+declare function reloadViews(viewPath: string): void;
+
 /**
  * Base View class.
  * Views are created via View.extend() and mounted by Frame.
@@ -274,6 +282,37 @@ declare class View implements ViewInterface {
      * 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()`.
@@ -689,7 +728,7 @@ interface VDomNode {
     hasSpecials?: Record<string, string> | undefined;
     /** Child VDomNode array (undefined for text/raw/self-closing) */
     children?: VDomNode[] | undefined;
-    /** Diff key: from id, _, #, or v-lark path */
+    /** Diff key: from id, #, or v-lark path */
     compareKey?: string | undefined;
     /** Keyed children count map (compareKey -> count) */
     reused?: Record<string, number> | undefined;
@@ -1426,8 +1465,9 @@ interface FrameworkInterface {
      * @param fns Function or function array
      * @param args Arguments array passed to functions
      * @param context `this` binding during function execution
+     * @param configError Optional error callback, receives the caught exception
      */
-    toTry(fns: AnyFunc | AnyFunc[], args?: unknown[], context?: unknown): unknown;
+    toTry(fns: AnyFunc | AnyFunc[], args?: unknown[], context?: unknown, configError?: (e: unknown) => void): unknown;
     /**
      * Convert path and params to URL string.
      * Example: `Framework.toUrl('/xxx/', {a:'b',c:'d'})` => `/xxx/?a=b&c=d`
@@ -1447,7 +1487,7 @@ interface FrameworkInterface {
      * @param target Target object
      * @param sources One or more source objects
      */
-    mix<T extends object>(target: T, ...sources: Partial<T>[]): T;
+    mix<T extends object>(target: T, ...sources: Record<string, unknown>[]): T;
     /**
      * Check if object has specified own property (safe hasOwnProperty).
      * @param owner Object to check, supports undefined/null
@@ -1484,13 +1524,6 @@ interface FrameworkInterface {
      * @param callback Callback after modules are loaded
      */
     use(names: string | string[], callback?: (...modules: unknown[]) => void): void;
-    /**
-     * Protect object from direct modification in debug mode.
-     * Wraps data object with Proxy, intercepts read/write operations, warns to use State.set/digest for state management.
-     * Only effective when `window.__lark_Debug` is true.
-     * @param o Object to protect
-     */
-    guard<T extends object>(o: T): T;
     /**
      * Dynamically inject CSS styles into page. Returns cleanup function to remove injected styles.
      * Supports single and batch injection.
@@ -2271,4 +2304,4 @@ declare function create<T>(name: string, creator: StateCreator<T>): StoreApi<T>;
  */
 declare function bindStore<T>(view: unknown, store: StoreApi<T>, selector?: (state: T) => Record<string, unknown>): () => void;
 
-export { type AnyFunc, CALL_BREAK_TIME, Cache, type CacheEntry, type CacheInterface, type CacheOptions, type ChangeEvent, type CompileOptions, CrossSite, type CrossSiteConfig, type DomElement, type DomOp, type DomRef, EVENT_METHOD_REGEXP, EventDelegator, EventEmitter, type EventEmitterInterface, type EventListenerEntry, Frame, type FrameBoundElement, type FrameInterface, type FrameInvokeEntry, type FrameStaticEvent, Framework, type FrameworkConfig, type FrameworkInterface, LARK_VIEW, type Location, type LocationDiff, type MixinEventHandler, type ParamDiff, type ParsedUri, Payload, type PayloadInterface, type PendingCacheEntry, RouterEvents as ROUTER_EVENTS, type RouteChangeEvent, type RouteChangedEvent, type RouteViewConfig, Router, type RouterInterface, SPLITTER, Service, type ServiceCacheInfo, type ServiceEvent, type ServiceMetaEntry, type ServiceOptions, State, type StateInterface, type StoreApi, TAG_NAME_REGEXP, Updater, type UpdaterInterface, type VDomCreateFn, type VDomNode, type VDomRef, type VDomTemplate, VIEW_EVENT_METHOD_REGEXP, View, type ViewEvent, type ViewEventSelectorEntry, type ViewGlobalEventEntry, type ViewInterface, type ViewLocationObserved, type ViewObserveLocation, type ViewResourceEntry, type ViewTemplate, type VoidFunc, applyStyle, bindStore, computed, create, createVDomRef, defineView, config as frameworkConfig, getRouteMode, invalidateViewClass, mark, markBooted, markRouterBooted, nextCounter, registerViewClass, resetProjectsMap, safeguard, unmark, use, useUrlState, vdomCreate };
+export { type AnyFunc, CALL_BREAK_TIME, Cache, type CacheEntry, type CacheInterface, type CacheOptions, type ChangeEvent, type CompileOptions, CrossSite, type CrossSiteConfig, type DomElement, type DomOp, type DomRef, EVENT_METHOD_REGEXP, EventDelegator, EventEmitter, type EventEmitterInterface, type EventListenerEntry, Frame, type FrameBoundElement, type FrameInterface, type FrameInvokeEntry, type FrameStaticEvent, Framework, type FrameworkConfig, type FrameworkInterface, type HotContext, LARK_VIEW, type Location, type LocationDiff, type MixinEventHandler, type ParamDiff, type ParsedUri, Payload, type PayloadInterface, type PendingCacheEntry, RouterEvents as ROUTER_EVENTS, type RouteChangeEvent, type RouteChangedEvent, type RouteViewConfig, Router, type RouterInterface, SPLITTER, Service, type ServiceCacheInfo, type ServiceEvent, type ServiceMetaEntry, type ServiceOptions, State, type StateInterface, type StoreApi, TAG_NAME_REGEXP, Updater, type UpdaterInterface, type VDomCreateFn, type VDomNode, type VDomRef, type VDomTemplate, VIEW_EVENT_METHOD_REGEXP, View, type ViewEvent, type ViewEventSelectorEntry, type ViewGlobalEventEntry, type ViewInterface, type ViewLocationObserved, type ViewObserveLocation, type ViewResourceEntry, type ViewTemplate, type VoidFunc, applyStyle, bindStore, computed, create, createVDomRef, defineView, config as frameworkConfig, getRouteMode, invalidateViewClass, mark, markBooted, markRouterBooted, nextCounter, registerViewClass, reloadViews, resetProjectsMap, unmark, use, useUrlState, vdomCreate };

package/dist/index.d.ts

@@ -63,26 +63,6 @@ declare function mark(host: object, key: string): () => boolean;
  */
 declare function unmark(host: object): void;
 
-/**
- * Safeguard: Proxy-based debug protection for data objects.
- *
- * In DEBUG mode, wraps data objects with Proxy to:
- * 1. Warn when data is read from a different page than where it was set
- * 2. Prevent direct mutation (forces use of State.set/digest)
- * 3. Track access patterns for debugging
- */
-/**
- * Wrap data with a Proxy for debug-mode protection.
- * Only active when window.__lark_Debug is true and Proxy is available.
- *
- * @param data - Data to wrap
- * @param getter - Optional callback when properties are read
- * @param setter - Optional callback when properties are written
- * @param isRoot - Whether this is the root data object
- * @returns Proxied data or original data if debug mode is off
- */
-declare function safeguard<T>(data: T, getter?: ((key: string) => void) | null, setter?: ((path: string, value: unknown) => void) | null, isRoot?: boolean): T;
-
 /**
  * Multi-cast event emitter class.
  *
@@ -121,6 +101,34 @@ declare class EventEmitter<T = unknown> implements EventEmitterInterface<T> {
     fire(event: string, data?: Record<string, unknown>, remove?: boolean, lastToFirst?: boolean): this;
 }
 
+/**
+ * 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.
+ */
+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')
+ */
+declare function reloadViews(viewPath: string): void;
+
 /**
  * Base View class.
  * Views are created via View.extend() and mounted by Frame.
@@ -274,6 +282,37 @@ declare class View implements ViewInterface {
      * 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()`.
@@ -689,7 +728,7 @@ interface VDomNode {
     hasSpecials?: Record<string, string> | undefined;
     /** Child VDomNode array (undefined for text/raw/self-closing) */
     children?: VDomNode[] | undefined;
-    /** Diff key: from id, _, #, or v-lark path */
+    /** Diff key: from id, #, or v-lark path */
     compareKey?: string | undefined;
     /** Keyed children count map (compareKey -> count) */
     reused?: Record<string, number> | undefined;
@@ -1426,8 +1465,9 @@ interface FrameworkInterface {
      * @param fns Function or function array
      * @param args Arguments array passed to functions
      * @param context `this` binding during function execution
+     * @param configError Optional error callback, receives the caught exception
      */
-    toTry(fns: AnyFunc | AnyFunc[], args?: unknown[], context?: unknown): unknown;
+    toTry(fns: AnyFunc | AnyFunc[], args?: unknown[], context?: unknown, configError?: (e: unknown) => void): unknown;
     /**
      * Convert path and params to URL string.
      * Example: `Framework.toUrl('/xxx/', {a:'b',c:'d'})` => `/xxx/?a=b&c=d`
@@ -1447,7 +1487,7 @@ interface FrameworkInterface {
      * @param target Target object
      * @param sources One or more source objects
      */
-    mix<T extends object>(target: T, ...sources: Partial<T>[]): T;
+    mix<T extends object>(target: T, ...sources: Record<string, unknown>[]): T;
     /**
      * Check if object has specified own property (safe hasOwnProperty).
      * @param owner Object to check, supports undefined/null
@@ -1484,13 +1524,6 @@ interface FrameworkInterface {
      * @param callback Callback after modules are loaded
      */
     use(names: string | string[], callback?: (...modules: unknown[]) => void): void;
-    /**
-     * Protect object from direct modification in debug mode.
-     * Wraps data object with Proxy, intercepts read/write operations, warns to use State.set/digest for state management.
-     * Only effective when `window.__lark_Debug` is true.
-     * @param o Object to protect
-     */
-    guard<T extends object>(o: T): T;
     /**
      * Dynamically inject CSS styles into page. Returns cleanup function to remove injected styles.
      * Supports single and batch injection.
@@ -2271,4 +2304,4 @@ declare function create<T>(name: string, creator: StateCreator<T>): StoreApi<T>;
  */
 declare function bindStore<T>(view: unknown, store: StoreApi<T>, selector?: (state: T) => Record<string, unknown>): () => void;
 
-export { type AnyFunc, CALL_BREAK_TIME, Cache, type CacheEntry, type CacheInterface, type CacheOptions, type ChangeEvent, type CompileOptions, CrossSite, type CrossSiteConfig, type DomElement, type DomOp, type DomRef, EVENT_METHOD_REGEXP, EventDelegator, EventEmitter, type EventEmitterInterface, type EventListenerEntry, Frame, type FrameBoundElement, type FrameInterface, type FrameInvokeEntry, type FrameStaticEvent, Framework, type FrameworkConfig, type FrameworkInterface, LARK_VIEW, type Location, type LocationDiff, type MixinEventHandler, type ParamDiff, type ParsedUri, Payload, type PayloadInterface, type PendingCacheEntry, RouterEvents as ROUTER_EVENTS, type RouteChangeEvent, type RouteChangedEvent, type RouteViewConfig, Router, type RouterInterface, SPLITTER, Service, type ServiceCacheInfo, type ServiceEvent, type ServiceMetaEntry, type ServiceOptions, State, type StateInterface, type StoreApi, TAG_NAME_REGEXP, Updater, type UpdaterInterface, type VDomCreateFn, type VDomNode, type VDomRef, type VDomTemplate, VIEW_EVENT_METHOD_REGEXP, View, type ViewEvent, type ViewEventSelectorEntry, type ViewGlobalEventEntry, type ViewInterface, type ViewLocationObserved, type ViewObserveLocation, type ViewResourceEntry, type ViewTemplate, type VoidFunc, applyStyle, bindStore, computed, create, createVDomRef, defineView, config as frameworkConfig, getRouteMode, invalidateViewClass, mark, markBooted, markRouterBooted, nextCounter, registerViewClass, resetProjectsMap, safeguard, unmark, use, useUrlState, vdomCreate };
+export { type AnyFunc, CALL_BREAK_TIME, Cache, type CacheEntry, type CacheInterface, type CacheOptions, type ChangeEvent, type CompileOptions, CrossSite, type CrossSiteConfig, type DomElement, type DomOp, type DomRef, EVENT_METHOD_REGEXP, EventDelegator, EventEmitter, type EventEmitterInterface, type EventListenerEntry, Frame, type FrameBoundElement, type FrameInterface, type FrameInvokeEntry, type FrameStaticEvent, Framework, type FrameworkConfig, type FrameworkInterface, type HotContext, LARK_VIEW, type Location, type LocationDiff, type MixinEventHandler, type ParamDiff, type ParsedUri, Payload, type PayloadInterface, type PendingCacheEntry, RouterEvents as ROUTER_EVENTS, type RouteChangeEvent, type RouteChangedEvent, type RouteViewConfig, Router, type RouterInterface, SPLITTER, Service, type ServiceCacheInfo, type ServiceEvent, type ServiceMetaEntry, type ServiceOptions, State, type StateInterface, type StoreApi, TAG_NAME_REGEXP, Updater, type UpdaterInterface, type VDomCreateFn, type VDomNode, type VDomRef, type VDomTemplate, VIEW_EVENT_METHOD_REGEXP, View, type ViewEvent, type ViewEventSelectorEntry, type ViewGlobalEventEntry, type ViewInterface, type ViewLocationObserved, type ViewObserveLocation, type ViewResourceEntry, type ViewTemplate, type VoidFunc, applyStyle, bindStore, computed, create, createVDomRef, defineView, config as frameworkConfig, getRouteMode, invalidateViewClass, mark, markBooted, markRouterBooted, nextCounter, registerViewClass, reloadViews, resetProjectsMap, unmark, use, useUrlState, vdomCreate };