lanka 1.0.0

package/dist/viewmodel/index.js

@@ -0,0 +1,701 @@
+"use client";
+import {
+  lankaScenarioBootstrap
+} from "../chunk-Q3SOVBIJ.js";
+import "../chunk-EWVDJYCC.js";
+import {
+  lankaLogger
+} from "../chunk-C2HP7CRD.js";
+import {
+  getLankaFlags
+} from "../chunk-D27MREPB.js";
+import "../chunk-BGVDPDX4.js";
+
+// src/viewmodel/_abstractions/lanka-vm-environment/ALankaVMEnvironment.ts
+var ALankaVMEnvironment = class {
+  /** What `createGateways` answered: the data layer, kept apart from services. */
+  gateways;
+  /** What `createServices` answered: everything that is not a gateway. */
+  services;
+  /** The data layer, built once per ViewModel. */
+  createGateways() {
+    return {};
+  }
+  /** Non-gateway collaborators, built once per ViewModel. */
+  createServices() {
+    return {};
+  }
+  /** Runs after the scenarios are bound. */
+  onInit() {
+  }
+  /** Runs when the screen goes away, before the scenarios are unbound. */
+  onReset() {
+  }
+};
+
+// src/viewmodel/_abstractions/lanka-vm/ALankaVM.ts
+import { create } from "zustand";
+
+// src/viewmodel/_internal/create-lanka-blind-spot-trap/createLankaBlindSpotTrap.ts
+var createLankaBlindSpotTrap = (viewModelName, isArmed) => {
+  if (!isArmed) {
+    return {
+      isArmed: false,
+      observeGet: (get) => get,
+      observeActions: (declared) => declared,
+      report: () => void 0
+    };
+  }
+  const indirectReads = /* @__PURE__ */ new Map();
+  const warnedKeys = /* @__PURE__ */ new Set();
+  let activeActionName = null;
+  return {
+    isArmed: true,
+    observeGet(get) {
+      return () => {
+        const state = get();
+        const actionName = activeActionName;
+        if (actionName === null) return state;
+        return new Proxy(state, {
+          get(target, prop, receiver) {
+            if (typeof prop === "string") {
+              let keys = indirectReads.get(actionName);
+              if (!keys) {
+                keys = /* @__PURE__ */ new Set();
+                indirectReads.set(actionName, keys);
+              }
+              keys.add(prop);
+            }
+            return Reflect.get(target, prop, receiver);
+          }
+        });
+      };
+    },
+    observeActions(declared) {
+      const observed = { ...declared };
+      for (const [name, value] of Object.entries(declared)) {
+        if (typeof value !== "function") continue;
+        observed[name] = (...args) => {
+          const previous = activeActionName;
+          activeActionName = name;
+          try {
+            return value(...args);
+          } finally {
+            activeActionName = previous;
+          }
+        };
+      }
+      return observed;
+    },
+    report(trackedKeys, next, prev) {
+      for (const [changedKey, value] of Object.entries(next)) {
+        if (Object.is(value, prev[changedKey])) continue;
+        if (trackedKeys.has(changedKey) || warnedKeys.has(changedKey)) continue;
+        const viaGetter = [...trackedKeys].some(
+          (key) => indirectReads.get(key)?.has(changedKey)
+        );
+        if (!viaGetter) continue;
+        warnedKeys.add(changedKey);
+        console.warn(
+          `[lanka] ${viewModelName}: key "${changedKey}" changed but no re-render will follow. The component reads it only through a getter, and tracking sees direct proxy reads only. Set enableAccessTrackingOptimization: false on this ViewModel \u2014 destructuring the key in the view "for the side effect" reads as dead code and will not survive a refactor.`
+        );
+      }
+    }
+  };
+};
+
+// src/viewmodel/_internal/create-lanka-scenario-binder/createLankaScenarioBinder.ts
+var createLankaScenarioBinder = (config) => {
+  const subscriptions = /* @__PURE__ */ new Map();
+  let isInitialized = false;
+  return {
+    get isInitialized() {
+      return isInitialized;
+    },
+    initializeScenario() {
+      if (isInitialized) return;
+      const context = config.context();
+      for (const binding of config.bindings ?? []) {
+        const key = binding.scenario.eventType;
+        if (subscriptions.has(key)) continue;
+        subscriptions.set(
+          key,
+          binding.scenario.subscribe(binding.handler(context), {
+            usedBy: config.name,
+            ...binding.options
+          })
+        );
+      }
+      config.onInit?.(context);
+      isInitialized = true;
+    },
+    resetScenario() {
+      for (const release of subscriptions.values()) release();
+      subscriptions.clear();
+      isInitialized = false;
+      config.onReset?.(config.context());
+    }
+  };
+};
+
+// src/viewmodel/_internal/create-lanka-tracked-hook/createLankaTrackedHook.ts
+import { useCallback, useRef, useSyncExternalStore } from "react";
+var asRecord = (state) => state;
+var createLankaTrackedHook = (config) => {
+  return (selector) => {
+    const selectorRef = useRef(selector);
+    selectorRef.current = selector;
+    const trackedKeysRef = useRef(/* @__PURE__ */ new Set());
+    const trackedStateRef = useRef(null);
+    const trackedProxyRef = useRef(null);
+    const subscribe = useCallback(
+      (onStoreChange) => config.subscribe((nextState, prevState) => {
+        if (selectorRef.current) {
+          onStoreChange();
+          return;
+        }
+        const trackedKeys = trackedKeysRef.current;
+        if (trackedKeys.size === 0) {
+          onStoreChange();
+          return;
+        }
+        const next = asRecord(nextState);
+        const prev = asRecord(prevState);
+        for (const key of trackedKeys) {
+          if (!Object.is(next[key], prev[key])) {
+            onStoreChange();
+            return;
+          }
+        }
+        config.onUntrackedChange?.(trackedKeys, next, prev);
+      }),
+      []
+    );
+    return useSyncExternalStore(subscribe, readTracked, readUntracked);
+    function readTracked() {
+      const state = config.readState();
+      const activeSelector = selectorRef.current;
+      if (activeSelector) return activeSelector(state);
+      if (trackedStateRef.current === state && trackedProxyRef.current) {
+        return trackedProxyRef.current;
+      }
+      const trackedKeys = /* @__PURE__ */ new Set();
+      const proxyState = new Proxy(state, {
+        get(target, prop, receiver) {
+          if (typeof prop === "string") {
+            trackedKeys.add(prop);
+          }
+          return Reflect.get(target, prop, receiver);
+        }
+      });
+      trackedKeysRef.current = trackedKeys;
+      trackedStateRef.current = state;
+      trackedProxyRef.current = proxyState;
+      return proxyState;
+    }
+    function readUntracked() {
+      const state = config.readState();
+      const activeSelector = selectorRef.current;
+      return activeSelector ? activeSelector(state) : state;
+    }
+  };
+};
+
+// src/viewmodel/_abstractions/lanka-vm/ALankaVM.ts
+var ALankaVM = class extends ALankaVMEnvironment {
+  /**
+   * Turn off when one broad consumer reads most fields, or when an action derives
+   * what the screen shows — proxy tracking then costs more than it saves, and in
+   * the second case it cannot see the read at all.
+   */
+  enableAccessTrackingOptimization = true;
+  /** Writes state. Available from `createActions` onwards, never before. */
+  set;
+  /** Reads state. The read a tracked hook cannot see — hence the switch above. */
+  get;
+  /** Fires a scenario, which every ViewModel bound to it then hears. */
+  trigger = (scenario, data) => {
+    scenario.trigger(data);
+  };
+  /** The reactive fields the screen reads. */
+  states() {
+    return {};
+  }
+  /** The scenarios this ViewModel listens to, unsubscribed for it on reset. */
+  scenarioHandlers() {
+    return [];
+  }
+  /** Store middleware — `persist`, `lankaDevtools` — the last one applied outermost. */
+  enhancers() {
+    return [];
+  }
+  /**
+   * The protected surface as an object, for the functional style.
+   *
+   * Assembled INSIDE the class because that is the only place `protected` can be
+   * read — a context built from outside could carry only the public half, which is
+   * the wrong half. Canon: `skills/parity/SKILL.md` section 3a.
+   */
+  toStyleContext() {
+    return {
+      set: this.set,
+      get: this.get,
+      gateways: this.gateways,
+      services: this.services,
+      trigger: this.trigger
+    };
+  }
+  /** Builds the hook a screen calls. One store per call. */
+  build() {
+    lankaLogger.printViewModelLog("START Create VM", this.name);
+    const blindSpot = createLankaBlindSpotTrap(
+      this.name,
+      getLankaFlags().isDevelopment === true
+    );
+    const bindings = this.scenarioHandlers();
+    const stateCreator = (set, get) => {
+      this.set = set;
+      this.get = blindSpot.observeGet(get);
+      this.gateways = this.createGateways();
+      this.services = this.createServices();
+      const actions = blindSpot.observeActions(this.createActions());
+      const { initializeScenario, resetScenario } = createLankaScenarioBinder({
+        name: this.name,
+        bindings,
+        context: () => this.toStyleContext(),
+        onInit: () => {
+          this.onInit();
+        },
+        onReset: () => {
+          this.onReset();
+        }
+      });
+      return {
+        ...this.states(),
+        ...actions,
+        initializeScenario,
+        resetScenario
+      };
+    };
+    const enhancedCreator = this.enhancers().reduce(
+      (creator, enhance) => enhance(creator),
+      stateCreator
+    );
+    const store = create()(enhancedCreator);
+    const registerScenarioViewModel = (viewModel) => {
+      if (bindings.length > 0) {
+        lankaScenarioBootstrap.registerViewModel(viewModel, this.name);
+      }
+    };
+    if (!this.enableAccessTrackingOptimization) {
+      registerScenarioViewModel(store.getState());
+      lankaLogger.printViewModelLog("FINISH Create VM", this.name);
+      return store;
+    }
+    const useOptimizedViewModel = createLankaTrackedHook({
+      subscribe: (onChange) => store.subscribe(onChange),
+      readState: () => store.getState(),
+      onUntrackedChange: blindSpot.isArmed ? blindSpot.report : void 0
+    });
+    useOptimizedViewModel.setState = store.setState;
+    useOptimizedViewModel.getState = store.getState;
+    useOptimizedViewModel.getInitialState = store.getInitialState;
+    useOptimizedViewModel.subscribe = store.subscribe;
+    registerScenarioViewModel(useOptimizedViewModel.getState());
+    lankaLogger.printViewModelLog("FINISH Create VM", this.name);
+    return useOptimizedViewModel;
+  }
+};
+
+// src/viewmodel/_utils/resolve-lanka-dependency/resolveLankaDependency.ts
+var resolveLankaDependency = (declared) => {
+  if (typeof declared === "function") return declared();
+  return declared ?? {};
+};
+
+// src/viewmodel/_factories/create-lanka-vm/createLankaVM.ts
+function createLankaVM(config) {
+  class FunctionalVM extends ALankaVM {
+    name = config.name;
+    enableAccessTrackingOptimization = config.enableAccessTrackingOptimization ?? true;
+    states() {
+      return config.states ?? {};
+    }
+    scenarioHandlers() {
+      return config.scenarioHandlers ?? [];
+    }
+    enhancers() {
+      return config.enhancers ?? [];
+    }
+    createGateways() {
+      return resolveLankaDependency(config.gateways);
+    }
+    createServices() {
+      return resolveLankaDependency(config.services);
+    }
+    createActions() {
+      return config.createActions(this.toStyleContext());
+    }
+    onInit() {
+      config.onInit?.(this.toStyleContext());
+    }
+    onReset() {
+      config.onReset?.(this.toStyleContext());
+    }
+  }
+  return new FunctionalVM().build();
+}
+
+// src/viewmodel/_internal/create-lazy-lanka-hook/createLazyLankaHook.ts
+var lazySlot = (config) => {
+  let store = null;
+  return {
+    get: () => {
+      if (!store) {
+        lankaLogger.printViewModelLog(
+          `LAZY: Creating ${config.kind} on first access`,
+          config.name
+        );
+        store = config.create();
+      }
+      return store;
+    },
+    /**
+     * Releases the store. The next access builds a new one.
+     *
+     * Scenario subscriptions go first, through `resetScenario` — the same path
+     * the between-tests reset uses. Dropping the reference without
+     * unsubscribing would leave the bus holding handlers that write into a
+     * discarded store.
+     *
+     * On a slot that never built, this does NOTHING: building a store in order
+     * to destroy it is work with no result, and it would resurrect a ViewModel
+     * a closed screen had just released.
+     */
+    release: () => {
+      if (!store) return;
+      store.getState().resetScenario();
+      store = null;
+    }
+  };
+};
+var forwardEveryMember = (slot) => (_target, property) => {
+  if (property === "dispose") return slot.release;
+  return (...args) => {
+    const built = slot.get();
+    const member = built[property];
+    return typeof member === "function" ? member.apply(built, args) : member;
+  };
+};
+var createLazyLankaHook = (config) => {
+  const slot = lazySlot(config);
+  const hook = (selector) => {
+    const built = slot.get();
+    return selector ? built(selector) : built();
+  };
+  return new Proxy(hook, { get: forwardEveryMember(slot) });
+};
+
+// src/viewmodel/_factories/create-lazy-lanka-vm/createLazyLankaVM.ts
+function createLazyLankaVM(config) {
+  return createLazyLankaHook({
+    name: config.name,
+    kind: "VM",
+    create: () => createLankaVM(config)
+  });
+}
+
+// src/viewmodel/_abstractions/lanka-stateless-vm/ALankaStatelessVM.ts
+var ALankaStatelessVM = class extends ALankaVMEnvironment {
+  /** Writes state. Available from `createActions` onwards, never before. */
+  set;
+  /** Reads what the actions have written, including the actions themselves. */
+  get;
+  /** Fires a scenario, which every ViewModel bound to it then hears. */
+  trigger = (scenario, data) => {
+    scenario.trigger(data);
+  };
+  /** The scenarios this ViewModel listens to, unsubscribed for it on reset. */
+  scenarioHandlers() {
+    return [];
+  }
+  /**
+   * The protected surface as an object, for the functional style.
+   *
+   * Assembled INSIDE the class because that is the only place `protected` can be
+   * read. Canon: `skills/parity/SKILL.md` section 3a.
+   */
+  toStyleContext() {
+    return {
+      set: this.set,
+      get: this.get,
+      gateways: this.gateways,
+      services: this.services,
+      trigger: this.trigger
+    };
+  }
+  /** Builds the hook a screen calls. One ViewModel per call. */
+  build() {
+    lankaLogger.printViewModelLog("START Create slVM", this.name);
+    let state = {};
+    this.get = () => state;
+    this.set = (partial, replace) => {
+      const next = typeof partial === "function" ? partial(state) : partial;
+      state = replace ? next : { ...state, ...next };
+    };
+    this.gateways = this.createGateways();
+    this.services = this.createServices();
+    const actions = this.createActions();
+    const bindings = this.scenarioHandlers();
+    const { initializeScenario, resetScenario } = createLankaScenarioBinder({
+      name: this.name,
+      bindings,
+      context: () => this.toStyleContext(),
+      onInit: () => {
+        this.onInit();
+      },
+      onReset: () => {
+        this.onReset();
+      }
+    });
+    state = { ...state, ...actions, initializeScenario, resetScenario };
+    if (bindings.length > 0) {
+      lankaScenarioBootstrap.registerViewModel(state, this.name);
+    }
+    const useStatelessViewModel = ((selector) => selector ? selector(state) : state);
+    useStatelessViewModel.getState = () => state;
+    lankaLogger.printViewModelLog("FINISH Create slVM", this.name);
+    return useStatelessViewModel;
+  }
+};
+
+// src/viewmodel/_factories/create-stateless-lanka-vm/createStatelessLankaVM.ts
+function createStatelessLankaVM(config) {
+  class FunctionalStatelessVM extends ALankaStatelessVM {
+    name = config.name;
+    scenarioHandlers() {
+      return config.scenarioHandlers ?? [];
+    }
+    createGateways() {
+      return resolveLankaDependency(config.gateways);
+    }
+    createServices() {
+      return resolveLankaDependency(config.services);
+    }
+    createActions() {
+      return config.createActions(this.toStyleContext());
+    }
+    onInit() {
+      config.onInit?.(this.toStyleContext());
+    }
+    onReset() {
+      config.onReset?.(this.toStyleContext());
+    }
+  }
+  return new FunctionalStatelessVM().build();
+}
+
+// src/viewmodel/_factories/create-lazy-stateless-lanka-vm/createLazyStatelessLankaVM.ts
+function createLazyStatelessLankaVM(config) {
+  return createLazyLankaHook({
+    name: config.name,
+    kind: "slVM",
+    create: () => createStatelessLankaVM(config)
+  });
+}
+
+// src/viewmodel/_factories/create-shared-store-lanka-vm/createSharedStoreLankaVM.ts
+import { useStore } from "zustand";
+function createSharedStoreLankaVM(config) {
+  lankaLogger.printViewModelLog("START Create ssVM", config.name);
+  let actions = {};
+  const gateways = resolveLankaDependency(config.gateways);
+  const services = resolveLankaDependency(config.services);
+  let lastStoreStateRef = null;
+  let lastFullStateRef = null;
+  const buildFullState = (storeState) => {
+    if (lastStoreStateRef === storeState && lastFullStateRef) {
+      return lastFullStateRef;
+    }
+    lastStoreStateRef = storeState;
+    lastFullStateRef = {
+      ...storeState,
+      ...actions,
+      initializeScenario,
+      resetScenario
+    };
+    return lastFullStateRef;
+  };
+  const getFullState = () => buildFullState(config.store.getState());
+  const ctx = {
+    set: (partial, replace) => config.store.setState(partial, replace),
+    getStore: () => config.store.getState(),
+    get: () => getFullState(),
+    store: config.store,
+    gateways,
+    services,
+    trigger: (scenario, data) => scenario.trigger(data)
+  };
+  const { initializeScenario, resetScenario } = createLankaScenarioBinder({
+    name: config.name,
+    bindings: config.scenarioHandlers,
+    context: () => ctx,
+    onInit: config.onInit,
+    onReset: config.onReset
+  });
+  actions = config.createActions(ctx);
+  lastStoreStateRef = null;
+  lastFullStateRef = null;
+  const isAccessTrackingEnabled = config.enableAccessTrackingOptimization ?? true;
+  const useTrackedSharedStoreViewModel = createLankaTrackedHook({
+    subscribe: (onChange) => config.store.subscribe((storeState, prevStoreState) => {
+      onChange(buildFullState(storeState), buildFullState(prevStoreState));
+    }),
+    readState: getFullState
+  });
+  const useUntrackedSharedStoreViewModel = ((selector) => useStore(config.store.getApi(), (storeState) => {
+    const fullState = buildFullState(storeState);
+    if (selector) {
+      return selector(fullState);
+    }
+    return fullState;
+  }));
+  const useSharedStoreViewModel = isAccessTrackingEnabled ? useTrackedSharedStoreViewModel : useUntrackedSharedStoreViewModel;
+  useSharedStoreViewModel.getState = () => getFullState();
+  useSharedStoreViewModel.getStoreState = () => config.store.getState();
+  if (config.scenarioHandlers && config.scenarioHandlers.length > 0) {
+    const scenarioViewModel = {
+      initializeScenario,
+      resetScenario
+    };
+    lankaScenarioBootstrap.registerViewModel(scenarioViewModel, config.name);
+  }
+  lankaLogger.printViewModelLog("FINISH Create ssVM", config.name);
+  return useSharedStoreViewModel;
+}
+
+// src/viewmodel/_factories/create-lazy-shared-store-lanka-vm/createLazySharedStoreLankaVM.ts
+function createLazySharedStoreLankaVM(config) {
+  return createLazyLankaHook({
+    name: config.name,
+    kind: "ssVM",
+    create: () => createSharedStoreLankaVM(config)
+  });
+}
+
+// src/viewmodel/_abstractions/lanka-shared-store-vm/ALankaSharedStoreVM.ts
+var ALankaSharedStoreVM = class extends ALankaVMEnvironment {
+  /** The store this ViewModel and its siblings share. */
+  store;
+  /** Writes into the shared store, which every reader of it hears about. */
+  set;
+  /** Reads the store's own state, without this ViewModel's actions on top. */
+  getStore;
+  /** Reads the store's state WITH the actions, which is what a screen sees. */
+  get;
+  /** Fires a scenario, which every ViewModel bound to it then hears. */
+  trigger;
+  constructor(store) {
+    super();
+    this.store = store;
+  }
+  /**
+   * Turn off when one broad consumer reads most fields of the store — proxy
+   * tracking then costs more than it saves.
+   */
+  enableAccessTrackingOptimization = true;
+  /** The scenarios this ViewModel listens to, unsubscribed for it on reset. */
+  scenarioHandlers() {
+    return [];
+  }
+  /** Builds the hook a screen calls. One ViewModel per call. */
+  build() {
+    return createSharedStoreLankaVM({
+      name: this.name,
+      store: this.store,
+      enableAccessTrackingOptimization: this.enableAccessTrackingOptimization,
+      gateways: () => this.createGateways(),
+      services: () => this.createServices(),
+      scenarioHandlers: this.scenarioHandlers(),
+      createActions: (context) => {
+        this.set = context.set;
+        this.getStore = context.getStore;
+        this.get = context.get;
+        this.gateways = context.gateways;
+        this.services = context.services;
+        this.trigger = context.trigger;
+        return this.createActions();
+      },
+      onInit: () => {
+        this.onInit();
+      },
+      onReset: () => {
+        this.onReset();
+      }
+    });
+  }
+};
+
+// src/viewmodel/_abstractions/lanka-shared-store/ALankaSharedStore.ts
+import { createStore } from "zustand/vanilla";
+var ALankaSharedStore = class {
+  api;
+  createInitialState;
+  constructor(createInitialState) {
+    this.createInitialState = createInitialState;
+    this.api = createStore()(() => this.createInitialState());
+  }
+  getApi() {
+    return this.api;
+  }
+  getState() {
+    return this.api.getState();
+  }
+  setState(partial, replace) {
+    const resolved = typeof partial === "function" ? partial(this.api.getState()) : partial;
+    if (replace) {
+      this.api.setState(resolved, true);
+      return;
+    }
+    this.api.setState(resolved);
+  }
+  subscribe(listener) {
+    return this.api.subscribe(listener);
+  }
+  /**
+   * Back to what the store was built with.
+   *
+   * Public, and it was not: while this was `protected` only a subclass could
+   * reset, so the class style had a capability the functional one could not
+   * reach — the asymmetry `skills/parity/SKILL.md` forbids. A shared store needs
+   * explicit reset points (see the ladder in `core/README.md`), and the
+   * application that owns them is outside the class either way.
+   */
+  reset() {
+    this.api.setState(this.createInitialState(), true);
+  }
+};
+
+// src/viewmodel/_factories/create-lanka-shared-store/createLankaSharedStore.ts
+var createLankaSharedStore = (createInitialState) => {
+  class FunctionalSharedStore extends ALankaSharedStore {
+    constructor() {
+      super(createInitialState);
+    }
+  }
+  return new FunctionalSharedStore();
+};
+export {
+  ALankaSharedStore,
+  ALankaSharedStoreVM,
+  ALankaStatelessVM,
+  ALankaVM,
+  createLankaSharedStore,
+  createLankaVM,
+  createLazyLankaVM,
+  createLazySharedStoreLankaVM,
+  createLazyStatelessLankaVM,
+  createSharedStoreLankaVM,
+  createStatelessLankaVM
+};
+//# sourceMappingURL=index.js.map