@lark.js/mvc 0.0.5 → 0.0.6

package/dist/index.d.ts

@@ -457,7 +457,7 @@ declare class Cache<T = unknown> implements CacheInterface<T> {
  * - View: base view class with extend/merge inheritance and mixin support
  * - Router: hash-based two-phase route confirmation
  * - State: simple cross-view observable singleton (recommended for simple cases)
- * - Store: complex Proxy-based reactive state with observe/handlers/multi-instance
+ * - Store: zustand-aligned state management with create/getState/setState/subscribe
  *   (recommended for complex cases)
  * - Service: API request management with caching, queuing, and deduplication
  * - Frame: view frame managing view mount/unmount lifecycle
@@ -777,7 +777,7 @@ interface RouterInterface extends EventEmitterInterface<RouterInterface> {
      * Returns an unsubscribe function so the guard can be torn down (e.g.
      * inside a view's `destroy` handler).
      */
-    beforeEach(guard: (to: Location, from: Location) => boolean | void | Promise<boolean | void>): () => void;
+    beforeEach(guard: (to: Location, from: Location) => boolean | Promise<boolean>): () => void;
     /** Internal: bind hashchange (called by Framework.boot) */
     _bind(): void;
     /** Internal: set framework config */
@@ -1203,8 +1203,7 @@ interface EventEmitterInterface<T = unknown> {
  *
  * Use State for SIMPLE cross-view data (lightweight shared values: counters,
  * toggles, page title, session info, etc.). For COMPLEX reactive state —
- * handlers, derived data, multi-instance isolation, or Proxy-based fine-grained
- * dependency tracking — use `defineStore` instead.
+ * handlers, derived data, or fine-grained subscriptions — use `create` instead.
  */
 interface StateInterface extends EventEmitterInterface<StateInterface> {
     /**
@@ -1643,6 +1642,12 @@ interface FrameworkConfig {
      * This field is required, defaults to "root".
      */
     rootId: string;
+    /**
+     * Routing mode.
+     * - `"history"` (default): uses `history.pushState` / `popstate`, clean URLs like `/home`
+     * - `"hash"`: uses URL hash fragment with `#!` prefix, e.g. `#!/home`
+     */
+    routeMode?: "history" | "hash";
     /**
      * Default view path.
      * Default root view path to load when URL doesn't match any route.
@@ -1661,7 +1666,7 @@ interface FrameworkConfig {
      * Use rewrite config item for path rewriting logic.
      */
     routes?: Record<string, string | RouteViewConfig>;
-    /** Hashbang prefix */
+    /** Hashbang prefix (only used in hash mode) */
     hashbang?: string;
     /**
      * Error handler.
@@ -1831,8 +1836,9 @@ declare function toMap<T>(list: T[] | null | undefined, key?: keyof T): Record<s
 /** Get current timestamp */
 declare function now(): number;
 
-/** Internal splitter character (invisible, used as namespace separator) */
-declare const SPLITTER = "\u001E";
+/** Internal splitter character (U+001E Record Separator, invisible, used as namespace separator).
+ * Uses String.fromCharCode to survive bundlers that strip control-char literals. */
+declare const SPLITTER: string;
 declare const RouterEvents: {
     CHANGE: string;
     CHANGED: string;
@@ -1883,14 +1889,14 @@ declare function applyStyle(styleIdOrPairs: string | string[], css?: string): ()
  * @param host - Object to associate the mark with (typically a view)
  * @param key  - Key to track (typically "render" or a specific async-op identifier)
  */
-declare function mark$1(host: object, key: string): () => boolean;
+declare function mark(host: object, key: string): () => boolean;
 /**
  * Clear all marks for a host object, invalidating every existing checker.
  * Called when a view re-renders or is destroyed.
  *
  * @param host - Object whose marks should be invalidated
  */
-declare function unmark$1(host: object): void;
+declare function unmark(host: object): void;
 
 /**
  * Safeguard: Proxy-based debug protection for data objects.
@@ -1921,7 +1927,7 @@ declare function markBooted(): void;
 declare const State: StateInterface;
 
 /**
- * Hash-based router with two-phase change confirmation.
+ * Router with two-phase change confirmation (supports history and hash modes).
  *
  * @example
  * Router.to('/list', { page: 2 });
@@ -1931,6 +1937,8 @@ declare const State: StateInterface;
 declare const Router: RouterInterface;
 /** Mark framework as booted (called by Framework.boot) */
 declare function markRouterBooted(): void;
+/** Get current routing mode */
+declare function getRouteMode(): "history" | "hash";
 
 /**
  * Module loader: async view loading via FrameworkConfig.require or dynamic import.
@@ -2328,192 +2336,100 @@ declare const EventDelegator: {
 declare const Framework: FrameworkInterface;
 
 /**
- * @lark.js/mvc Store
- *
- * Reactive state management with Proxy-based dependency tracking.
- * Adapted for Lark / React / Node.js.
+ * Sync view state with URL query parameters.
  *
- * Store is the recommended choice for COMPLEX cross-view state:
- * reactive handlers, derived data, multi-instance isolation (`multi()`),
- * store-internal reactions (inner `observe`), and Proxy-based fine-grained
- * dependency tracking. For SIMPLE shared values (counters, toggles, page
- * title, session info, etc.) prefer `State` from `./state` — fewer concepts
- * and no Proxy overhead.
+ * @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.
  *
- * Core concepts:
- * - createState: Proxy-based deep reactive state
- * - track/trigger/clear: publish-subscribe dependency tracking
- * - defineStore: declarative store definition with platform adapters
- * - cell/observeCell: lightweight standalone reactive cells
+ * @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) }));
+ *   },
+ * });
+ * ```
  */
+declare function useUrlState<S extends Record<string, string>>(view: ViewInterface, initialState?: S): [Readonly<S>, (patch: Partial<S> | ((prev: S) => Partial<S>)) => void];
 
-interface Task {
-    cb: AnyFunc;
-    params?: Record<string, unknown>;
-}
-interface SchedulerObject {
-    add: (tasks: Task[]) => void;
-    clear: () => void;
-    delete: (tasks: Task[]) => void;
-}
-type Scheduler = SchedulerObject | ((cb: AnyFunc, payload: unknown) => void);
-interface StateConfig {
-    belong?: string;
-    linkKeys?: string;
-    shallow?: boolean;
-}
-interface StoreConfig {
-    platform?: Platform;
-    scheduler?: Scheduler;
-}
-interface ObservePayload {
-    key: string;
-    alias?: string;
-    cb?: (changedMap: Record<string, unknown>) => void;
-    lazy?: boolean;
-    transform?: (val: unknown) => Record<string, unknown>;
-}
-declare enum StoreStatus {
-    BEFORE_CREATE = 0,
-    CREATED = 1,
-    ACTIVE = 2,
-    DESTROYED = 3
-}
-declare enum Platform {
-    Lark = "lark",
-    React = "react",
-    Node = "node"
-}
-declare const cloneData: <T>(data: T) => T;
-declare class Queue {
-    private pendingTasks;
-    private queue;
-    flushTasks(): void;
-    add(tasks: Task[]): void;
-    delete(tasks: Task[]): void;
-    clear(): void;
+/**
+ * @lark.js/mvc Store
+ *
+ * Zustand-aligned state management for Lark MVC.
+ *
+ * Core API:
+ * - create(name, creator): define a store with (set, get) => initialState
+ * - store.getState(): read current state snapshot
+ * - store.setState(partial | updater): shallow-merge state and notify listeners
+ * - store.subscribe(listener): listen for state changes
+ * - store.destroy(): tear down the store
+ * - computed(deps, fn): derived state that auto-recomputes when deps change
+ * - bindStore(view, store, selector?): Lark View lifecycle binding
+ */
+type Listener<T> = (state: T, prevState: T) => void;
+interface StoreApi<T = Record<string, unknown>> {
+    getState(): T;
+    setState(partial: Partial<T> | ((prev: T) => Partial<T>)): void;
+    subscribe(listener: Listener<T>): () => void;
+    destroy(): void;
 }
-/** Check if value is a reactive state */
-declare const isState: (target: unknown) => boolean;
-declare const mark: (host: Record<string, unknown>, key: string) => (() => boolean);
-declare const unmark: (host: Record<string, unknown>) => void;
-declare function createState(initialData: unknown, config?: StateConfig): Record<string, unknown>;
-declare function lazySet(target: Record<string, unknown>, data: Record<string, unknown>): void;
-/** Shallow set: only top-level properties are reactive */
-declare function shallowSet(target: Record<string, unknown>, key: string, data: unknown): unknown;
-declare const _storeName: unique symbol;
-declare const _storeStatus: unique symbol;
-declare const _storeScheduler: unique symbol;
-declare const _storeCreate: unique symbol;
-declare const _storeBoot: unique symbol;
-declare const _storeDestroy: unique symbol;
-declare const _innerStore: unique symbol;
-declare const _outerStore: unique symbol;
-declare const _originState: unique symbol;
-declare const _stateKeys: unique symbol;
-declare const _storeState: unique symbol;
-declare const _storeDefScheduler: unique symbol;
-declare const _storeProxy: unique symbol;
-declare const _computedKeys: unique symbol;
+type StateCreator<T> = (set: (partial: Partial<T> | ((prev: T) => Partial<T>)) => void, get: () => T) => T;
 /**
  * Declare a derived (computed) store property.
  *
- * Usage (inside a `defineStore` creator):
- *
+ * Usage inside a `create` creator:
  * ```ts
- * defineStore("count", (store, { computed }) => ({
+ * const store = create("counter", (set, get) => ({
  *   count: 0,
- *   doubled: computed(["count"], () => store.count * 2),
- *   increment() { store.count++ },
+ *   doubled: computed(["count"], () => get().count * 2),
  * }));
  * ```
  *
- * `deps` lists the state keys the computed reads. Whenever any of those keys
- * changes, the computed function re-runs and the new value flows out through
- * the store like a regular state update — meaning views that
- * `store.observe(this, ["doubled"])` re-render automatically.
- *
- * The returned value is typed as `T`, so the store body still type-checks as
- * `{ doubled: number; ... }`. Writes to a computed key are ignored at runtime.
+ * `deps` lists the state keys the computed reads. Whenever any dep changes
+ * via `setState`, the computed re-evaluates before listeners are notified.
+ * Writes to a computed key via `setState` are silently ignored.
  */
 declare function computed<T>(deps: readonly string[], fn: () => T): T;
-declare abstract class BaseStore {
-    [_storeName]: string;
-    [_storeStatus]: StoreStatus;
-    [_storeScheduler]: Scheduler;
-    [_originState]: Record<string, unknown>;
-    [_stateKeys]: string[];
-    [_storeState]: Record<string, unknown>;
-    [_computedKeys]: Set<string>;
-    [_storeDefScheduler]: () => Queue;
-    private [_outerStore];
-    [_storeBoot](): Record<string, unknown>;
-    [_storeDestroy](): void;
-    /**
-     *
-     * @param body - The object returned by the creator function
-     * @param excludeFns - Function keys to exclude from handlers (e.g. ['observe'])
-     */
-    [_storeCreate](body: Record<string, unknown>, excludeFns?: string[]): void;
-    constructor(name: string, config?: StoreConfig);
-    [_innerStore](): Record<string, unknown>;
-    get status(): StoreStatus;
-    get storeName(): string;
-    get scheduler(): Scheduler;
-    [_storeProxy](toOut?: boolean): Record<string, unknown>;
-}
-interface LarkView {
-    updater: {
-        set: (data: Record<string, unknown>) => unknown;
-        digest: (data?: Record<string, unknown>) => void;
-    };
-    on: (event: string, handler: AnyFunc) => unknown;
-}
-type LarkUseStore<S = Record<string, unknown>> = (view?: LarkView) => S & StoreMethods;
-type ReactUseStore<S = Record<string, unknown>, StateSlice = S> = (selector?: (store: S & StoreMethods) => StateSlice) => StateSlice;
-type NodeUseStore<S = Record<string, unknown>> = () => S & NodeStoreMethods;
-interface NodeStoreMethods {
-    observe: (key: string, callback: AnyFunc, immediate?: boolean) => () => void;
-}
-interface StoreMethods {
-    /**
-     * Subscribe a view to store changes.
-     *
-     * - `store.observe(view)` — observe every state key (D5 default).
-     * - `store.observe(view, ["k1", "k2"])` — observe specific keys only.
-     * - `store.observe(view, ["k1"], (changes) => ...)` — explicit callback.
-     * - `store.observe(undefined, ["k1"], cb)` — inner observe (no view binding).
-     */
-    observe: (view: LarkView | undefined, keys?: (string | ObservePayload)[] | (() => (string | ObservePayload)[]), defCallback?: (changedMap: Record<string, unknown>) => void) => () => void;
-}
-/** Detect platform from a component instance */
-declare const getPlatform: (comp: unknown) => Platform | undefined;
-declare const extendApis: {
-    lazySet: typeof lazySet;
-    shallowSet: typeof shallowSet;
-    computed: typeof computed;
-};
-/** Inner store type available inside defineStore creator */
-type InnerStore<S = Record<string, unknown>> = S & StoreMethods;
-declare function defineStore<S = Record<string, unknown>>(name: string, creator: (store: InnerStore<S>, apis: typeof extendApis) => S, config?: StoreConfig & {
-    platform: Platform.Lark;
-}): LarkUseStore<S>;
-declare function defineStore<S = Record<string, unknown>>(name: string, creator: (store: InnerStore<S>, apis: typeof extendApis) => S, config?: StoreConfig & {
-    platform: Platform.React;
-}): ReactUseStore<S>;
-declare function defineStore<S = Record<string, unknown>>(name: string, creator: (store: InnerStore<S>, apis: typeof extendApis) => S, config?: StoreConfig & {
-    platform: Platform.Node;
-}): NodeUseStore<S>;
-declare function getStore(name: string): BaseStore | undefined;
-declare function delStore(name: string): void;
-declare function getUseStore(name: string): AnyFunc | undefined;
-declare function cloneStore(name: string, useStore: AnyFunc, config?: StoreConfig): unknown;
-declare function isStoreActive(name: string): boolean;
-declare function cell<T = unknown>(data: T): T;
-declare function observeCell(state: Record<string, unknown>, cb: AnyFunc, immediate?: boolean): () => void;
-declare function multi<S = Record<string, unknown>>(useStore: LarkUseStore<S>): [LarkUseStore<S>, {
-    make: AnyFunc;
-}];
+declare function create<T>(name: string, creator: StateCreator<T>): StoreApi<T>;
+/**
+ * Bind a store to a Lark View. Subscribes to state changes and auto-unsubscribes
+ * when the view is destroyed.
+ *
+ * @param view - Lark View instance (must have updater.set/digest and on("destroy"))
+ * @param store - Store created via `create()`
+ * @param selector - Optional function to pick a subset of state for the updater.
+ *   If omitted, only non-function state keys are forwarded.
+ * @returns unsubscribe function
+ *
+ * @example
+ * ```ts
+ * // Observe all state
+ * bindStore(this, useCountStore);
+ *
+ * // Observe with selector
+ * bindStore(this, useCountStore, (s) => ({ count: s.count }));
+ * ```
+ */
+declare function bindStore<T extends Record<string, unknown>>(view: unknown, store: StoreApi<T>, selector?: (state: T) => Record<string, unknown>): () => void;
+/**
+ * @deprecated Use `create()` instead. This is a temporary alias.
+ */
+declare const defineStore: typeof create;
 
 /** Serialized view info attached to a frame node */
 interface SerializedViewInfo {
@@ -2533,6 +2449,14 @@ interface SerializedViewInfo {
     };
     /** Whether view has a template function */
     hasTemplate: boolean;
+    /** Delegated event types (keys from $evtObjMap) */
+    eventMethodKeys: string[];
+    /** Captured resource keys */
+    resourceKeys: string[];
+    /** Whether view exposes an assign method (supports CrossSite reuse) */
+    hasAssign: boolean;
+    /** Updater refData snapshot (shallow copy of current data) */
+    updaterData: Record<string, unknown> | null;
 }
 /** A single node in the serialized frame tree */
 interface SerializedFrameNode {
@@ -2654,4 +2578,4 @@ declare function compileTemplate(source: string, options?: CompileOptions): stri
  */
 declare function extractGlobalVars(source: string): string[];
 
-export { type AnyFunc, CALL_BREAK_TIME, Cache, type CacheEntry, type CacheInterface, type CacheOptions, type ChangeEvent, type CompileOptions, CrossSite, type CrossSiteConfig, EVENT_METHOD_REGEXP, EventDelegator, EventEmitter, type EventEmitterInterface, type EventListenerEntry, Frame, type FrameBoundElement, type FrameInterface, type FrameInvokeEntry, type FrameStaticEvent, FrameVisualBridge, Framework, type FrameworkConfig, type FrameworkInterface, LARK_VIEW, type LarkUseStore, type Location, type LocationDiff, type MixinEventHandler, type NodeUseStore, type ObservePayload, type ParamDiff, type ParsedUri, Payload, type PayloadEntry, type PayloadInterface, type PendingCacheEntry, Platform, RouterEvents as ROUTER_EVENTS, type ReactUseStore, type RouteChangeEvent, type RouteChangedEvent, type RouteViewConfig, Router, type RouterInterface, SPLITTER, type SerializedFrameNode, type SerializedFrameTree, type SerializedViewInfo, Service, type ServiceCacheInfo, type ServiceEntry, type ServiceEvent, type ServiceInterface, type ServiceMetaEntry, type ServiceOptions, State, type StateInterface, type StoreConfig, type StoreMethods, TAG_NAME_REGEXP, Updater, type UpdaterInterface, type VDomOp, type VDomRef, VIEW_EVENT_METHOD_REGEXP, type VdomElement, View, type ViewEvent, type ViewEventSelectorEntry, type ViewGlobalEventEntry, type ViewInterface, type ViewLocationObserved, type ViewObserveLocation, type ViewResourceEntry, type ViewTemplate, type VoidFunc, applyIdUpdates, applyStyle, applyVdomOps, assign, cell, cloneData, cloneStore, compileTemplate, computed, createState, createVdomRef, defineStore, defineView, delStore, encodeHTML, encodeQ, encodeSafe, encodeURIExtra, ensureElementId, extractGlobalVars, config as frameworkConfig, funcWithTry, generateId, getAttribute, getById, getPlatform, getStore, getUseStore, hasOwnProperty, installFrameVisualizerBridge, invalidateViewClass, isPlainObject, isPrimitive, isPrimitiveOrFunc, isState, isStoreActive, keys, lazySet, mark$1 as mark, markBooted, markRouterBooted, multi, nextCounter, nodeInside, noop, now, observeCell, parseUri, registerViewClass, resetProjectsMap, safeguard, serializeFrameTree, setData, shallowSet, mark as storeMark, unmark as storeUnmark, syncCounter, toMap, toUri, translateData, unmark$1 as unmark, use, vdomGetCompareKey, vdomGetNode, vdomSetAttributes, vdomSetChildNodes, vdomSetNode, vdomSpecialDiff, vdomUnmountFrames };
+export { type AnyFunc, CALL_BREAK_TIME, Cache, type CacheEntry, type CacheInterface, type CacheOptions, type ChangeEvent, type CompileOptions, CrossSite, type CrossSiteConfig, EVENT_METHOD_REGEXP, EventDelegator, EventEmitter, type EventEmitterInterface, type EventListenerEntry, Frame, type FrameBoundElement, type FrameInterface, type FrameInvokeEntry, type FrameStaticEvent, FrameVisualBridge, Framework, type FrameworkConfig, type FrameworkInterface, LARK_VIEW, type Location, type LocationDiff, type MixinEventHandler, type ParamDiff, type ParsedUri, Payload, type PayloadEntry, type PayloadInterface, type PendingCacheEntry, RouterEvents as ROUTER_EVENTS, type RouteChangeEvent, type RouteChangedEvent, type RouteViewConfig, Router, type RouterInterface, SPLITTER, type SerializedFrameNode, type SerializedFrameTree, type SerializedViewInfo, Service, type ServiceCacheInfo, type ServiceEntry, type ServiceEvent, type ServiceInterface, type ServiceMetaEntry, type ServiceOptions, State, type StateInterface, type StoreApi, TAG_NAME_REGEXP, Updater, type UpdaterInterface, type VDomOp, type VDomRef, VIEW_EVENT_METHOD_REGEXP, type VdomElement, View, type ViewEvent, type ViewEventSelectorEntry, type ViewGlobalEventEntry, type ViewInterface, type ViewLocationObserved, type ViewObserveLocation, type ViewResourceEntry, type ViewTemplate, type VoidFunc, applyIdUpdates, applyStyle, applyVdomOps, assign, bindStore, compileTemplate, computed, create, createVdomRef, defineStore, defineView, encodeHTML, encodeQ, encodeSafe, encodeURIExtra, ensureElementId, extractGlobalVars, config as frameworkConfig, funcWithTry, generateId, getAttribute, getById, getRouteMode, hasOwnProperty, installFrameVisualizerBridge, invalidateViewClass, isPlainObject, isPrimitive, isPrimitiveOrFunc, keys, mark, markBooted, markRouterBooted, nextCounter, nodeInside, noop, now, parseUri, registerViewClass, resetProjectsMap, safeguard, serializeFrameTree, setData, syncCounter, toMap, toUri, translateData, unmark, use, useUrlState, vdomGetCompareKey, vdomGetNode, vdomSetAttributes, vdomSetChildNodes, vdomSetNode, vdomSpecialDiff, vdomUnmountFrames };