@novely/core 0.52.0-next → 0.52.0-next.2

package/dist/index.d.ts

@@ -66,10 +66,6 @@ type CustomActionHandle = {
      * Function that will give action root (element which you should add to the screen because custom actions rendered into that element)
      */
     setMountElement: (mountElement: null | HTMLDivElement) => void;
-    /**
-     * Function that will give you clean function provided by custom action.
-     */
-    setClear: (clear: () => void) => void;
 };
 type AudioHandle = {
     stop: () => void;
@@ -222,7 +218,7 @@ type RendererInit<$Language extends Lang, $Characters extends Record<string, Cha
     preview: (save: Save<State>, name: string) => Promise<RendererInitPreviewReturn>;
     removeContext: (name: string) => void;
     getStateFunction: (context: string) => StateFunction<State>;
-    clearCustomAction: (ctx: Context, customAction: CustomHandler) => void;
+    clearCustomActionsAtContext: (ctx: Context) => void;
     getLanguageDisplayName: (lang: Lang) => string;
     getCharacterColor: (character: string) => string;
     getCharacterAssets: (character: string, emotion: string) => string[];
@@ -685,13 +681,9 @@ type CustomHandlerFunctionParameters<L extends string, S extends State> = {
      */
     getDomNodes: CustomHandlerFunctionGetFn;
     /**
-     * @deprecated use `getSave` instead
-     */
-    getPath: () => Path;
-    /**
-     * Function to get current Save. It can be mutated.
+     * Function to get current Save. It can be mutated. Only use it when you know what you do
      *
-     * Only use it when you know what you do
+     * @deprecated
      */
     getSave: () => Save<S>;
     /**
@@ -704,22 +696,68 @@ type CustomHandlerFunctionParameters<L extends string, S extends State> = {
     contextKey: string;
     /**
      * Function to work with custom action's state
+     *
+     * @example
+     * ```ts
+     * type Data = { name: string };
+     *
+     * const handler: CustomHandler = async ({ data }) => {
+     *   const _data = data<Data>();
+     *
+     *   if (!_data.name) {
+     *     _data.name = 'Mr. Crabs'
+     *   }
+     *
+     *   data<Data>().name // 'Mr. Crabs'
+     *
+     *   data<Data>() == _data // true
+     *
+     *   // passing object will replace object
+     *   data<Data>({ name: 'Mr. Crabs' })
+     *   data<Data>() == _data // false
+     * }
+     * ```
      */
     data: CustomHandlerGetResultDataFunction;
     /**
-     * Function to set cleanup handler
+     * Function to access data stored at specific key.
+     * @example
+     * ```ts
+     * const handler: CustomHandler = async ({ dataAtKey }) => {
+     *   // peek at data at action with key 'action-2'
+     *   console.log(dataAtKey('action-2'))
+     * }
+     *
+     * handler.key = 'action-1'
+     * ```
+     * @deprecated
+     */
+    dataAtKey: <T extends Record<string, unknown>>(key: string) => T | null;
+    /**
+     * Function to set cleanup functions.
+     *
+     * @example
+     * ```ts
+     * const handler: CustomHandler = async ({ clear, paused }) => {
+     *   const unsubscribe = paused.subscribe((paused) => {
+     *
+     *   })
+     *
+     *   clear(paused);
+     * }
+     * ```
      */
     clear: (fn: () => void) => void;
     /**
-     * Remove's custom handler instance
+     * It will call all clear actions and remove HTML element from `getDomNodes` function
      */
     remove: () => void;
     /**
-     * Context's state function
+     * State function
      */
     state: StateFunction<S>;
     /**
-     * Game flags (aka game states)
+     * Game state
      */
     flags: {
         restoring: boolean;
@@ -732,10 +770,27 @@ type CustomHandlerFunctionParameters<L extends string, S extends State> = {
     lang: L;
     /**
      * Function to replace template content
+     *
+     * @example
+     * ```ts
+     * const handler: CustomHandler = async ({ state, templateReplace }) => {
+     *   const text = templateReplace({ en: '' }, state())
+     * }
+     * ```
      */
     templateReplace: (content: TextContent<L, State>, values?: State) => string;
     /**
      * Is game currently paused
+     *
+     * @example
+     * ```ts
+     * const handler: CustomHandler = async ({ clear, paused }) => {
+     *   const unsubscribe = paused.subscribe((paused) => {
+     *     // Here you can pause/resume animations, sounds, etc, etc
+     *   })
+     *
+     *   clear(paused);
+     * }
      */
     paused: Derived<boolean>;
 };
@@ -766,16 +821,12 @@ type CustomHandlerInfo = CustomHandlerCalling & {
      * When true interacting with it will be saved in history
      */
     requireUserAction?: boolean;
-    /**
-     * When player is going back we clear every custom action. But we can ignore clearing that.
-     */
-    skipClearOnGoingBack?: boolean;
     /**
      * Id by which we will determine what action is which
      */
     id: string | symbol;
     /**
-     * Key by which we will save the data in the `get` function provided to custom action.
+     * Key by which we will save the custom action's data. It includes cleanup function's provided by `clear` and data in `data` function
      *
      * It can be a name of action or more specific thing. In example for custom `showCharacter` it may be `show-character-${character}
      */

package/dist/index.js

@@ -122,6 +122,7 @@ var MAIN_CONTEXT_KEY = "$MAIN";
 // src/shared.ts
 var STACK_MAP = /* @__PURE__ */ new Map();
 var CUSTOM_ACTION_MAP = /* @__PURE__ */ new Map();
+var CUSTOM_ACTION_CLEANUP_MAP = /* @__PURE__ */ new Map();
 var PRELOADED_ASSETS = /* @__PURE__ */ new Set();
 var ASSETS_TO_PRELOAD = /* @__PURE__ */ new Set();
 
@@ -674,7 +675,7 @@ var createQueueProcessor = (queue, options) => {
     if (action === "function" || action === "custom") {
       if (action === "custom") {
         const fn = params[0];
-        if ("callOnlyLatest" in fn && fn.callOnlyLatest) {
+        if (fn.callOnlyLatest) {
           const notLatest = next(i).some(([name, func]) => {
             if (name !== "custom") return;
             const isIdenticalId = Boolean(func.id && fn.id && func.id === fn.id);
@@ -683,7 +684,7 @@ var createQueueProcessor = (queue, options) => {
             return isIdenticalId || isIdenticalByReference || isIdenticalByCode;
           });
           if (notLatest) continue;
-        } else if ("skipOnRestore" in fn && fn.skipOnRestore) {
+        } else if (fn.skipOnRestore) {
           if (fn.skipOnRestore(next(i))) {
             continue;
           }
@@ -922,7 +923,7 @@ var capitalize = (str) => {
   return str[0].toUpperCase() + str.slice(1);
 };
 
-// src/utilities/functions.ts
+// src/utilities/noop.ts
 var noop = () => {
 };
 
@@ -997,6 +998,7 @@ var immutable = (value) => {
 };
 
 // src/custom-action.ts
+import { once as once2 } from "es-toolkit/function";
 var createCustomActionNode = (id) => {
   const div = document.createElement("div");
   div.setAttribute("data-id", id);
@@ -1008,7 +1010,6 @@ var getCustomActionHolder = (ctx, fn) => {
     return cached;
   }
   const holder = {
-    cleanup: noop,
     node: null,
     fn,
     localData: {}
@@ -1016,17 +1017,38 @@ var getCustomActionHolder = (ctx, fn) => {
   CUSTOM_ACTION_MAP.set(ctx.id + fn.key, holder);
   return holder;
 };
+var getCustomActionCleanupHolder = (ctx) => {
+  const existing = CUSTOM_ACTION_CLEANUP_MAP.get(ctx.id);
+  if (existing) {
+    return existing;
+  }
+  const holder = [];
+  CUSTOM_ACTION_CLEANUP_MAP.set(ctx.id, holder);
+  return holder;
+};
 var handleCustomAction = (ctx, fn, {
   lang,
   state,
   setMountElement,
-  setClear,
   remove: renderersRemove,
   getStack: getStack2,
   templateReplace,
   paused
 }) => {
   const holder = getCustomActionHolder(ctx, fn);
+  const cleanupHolder = getCustomActionCleanupHolder(ctx);
+  const cleanupNode = () => {
+    if (!cleanupHolder.some((item) => item.fn.id === fn.id && item.fn.key === fn.key)) {
+      holder.node = null;
+      setMountElement(null);
+    }
+  };
+  const cleanupSource = {
+    fn,
+    list: /* @__PURE__ */ new Set(),
+    dom: cleanupNode
+  };
+  cleanupHolder.push(cleanupSource);
   const flags = {
     ...ctx.meta
   };
@@ -1045,15 +1067,7 @@ var handleCustomAction = (ctx, fn, {
     };
   };
   const clear = (func) => {
-    setClear(
-      holder.cleanup = () => {
-        func();
-        holder.node = null;
-        holder.cleanup = noop;
-        setMountElement(null);
-        setClear(noop);
-      }
-    );
+    cleanupSource.list.add(once2(func));
   };
   const data = (updatedData) => {
     if (updatedData) {
@@ -1062,13 +1076,12 @@ var handleCustomAction = (ctx, fn, {
     return holder.localData;
   };
   const remove = () => {
-    holder.cleanup();
+    cleanupSource.list.forEach((fn2) => fn2());
+    cleanupSource.list.clear();
+    cleanupSource.dom();
     renderersRemove();
   };
   const stack = getStack2(ctx);
-  const getPath = () => {
-    return stack.value[0];
-  };
   const getSave = () => {
     return stack.value;
   };
@@ -1077,13 +1090,13 @@ var handleCustomAction = (ctx, fn, {
     lang,
     state,
     data,
+    dataAtKey: (key) => CUSTOM_ACTION_MAP.get(ctx.id + key)?.localData || null,
     templateReplace,
     clear,
     remove,
     rendererContext: ctx,
     getDomNodes,
     getSave,
-    getPath,
     contextKey: ctx.id,
     paused: flags.preview ? immutable(false) : paused
   });
@@ -1610,13 +1623,7 @@ var novely = ({
       filter: false,
       referGuarded
     });
-    const {
-      run,
-      keep: { keep, characters: characters2, audio: audio2 }
-    } = createQueueProcessor(queue, {
-      skip,
-      skipPreserve
-    });
+    const cleanupHolder = getCustomActionCleanupHolder(context);
     if (previous) {
       const { queue: prevQueue } = await getActionsFromPath({
         story,
@@ -1624,17 +1631,38 @@ var novely = ({
         filter: false,
         referGuarded
       });
-      for (let i = prevQueue.length - 1; i > queue.length - 1; i--) {
-        const element = prevQueue[i];
-        if (!isAction(element)) {
-          continue;
-        }
-        const [action2, fn] = element;
+      const futures = [];
+      const isFromDifferentBranches = previous[0][0][1] !== path[0][1];
+      const end = isFromDifferentBranches ? 0 : queue.length - 1;
+      for (let i = prevQueue.length - 1; i >= end; i--) {
+        const [action2, fn] = prevQueue[i];
         if (action2 === "custom") {
-          getCustomActionHolder(context, fn).cleanup();
+          futures.push(fn);
+        }
+      }
+      futures.reverse();
+      const dom = /* @__PURE__ */ new Set();
+      for (const future of futures) {
+        inner: for (let i = cleanupHolder.length - 1; i >= 0; i--) {
+          const item = cleanupHolder[i];
+          if (future === item.fn) {
+            item.list.forEach((fn) => fn());
+            item.list.clear();
+            cleanupHolder.splice(i, 1);
+            dom.add(item.dom);
+            break inner;
+          }
         }
       }
+      dom.forEach((f) => f());
     }
+    const {
+      run,
+      keep: { keep, characters: characters2, audio: audio2 }
+    } = createQueueProcessor(queue, {
+      skip,
+      skipPreserve
+    });
     if (context.meta.goingBack) {
       match("clear", [keep, characters2, audio2], {
         ctx: context,
@@ -1650,6 +1678,11 @@ var novely = ({
         return;
       }
       const [action2, ...props] = item;
+      if (action2 === "custom") {
+        if (cleanupHolder.some((holder) => holder.fn === props[0])) {
+          return;
+        }
+      }
       return match(action2, props, {
         ctx: context,
         data: latest[1]
@@ -1783,8 +1816,16 @@ var novely = ({
     }
     return capitalize(language.nameOverride || getIntlLanguageDisplayName(lang));
   };
-  const clearCustomAction = (ctx, fn) => {
-    getCustomActionHolder(ctx, fn).cleanup();
+  const clearCustomActionsAtContext = (ctx) => {
+    const cleanupHolder = getCustomActionCleanupHolder(ctx);
+    const dom = /* @__PURE__ */ new Set();
+    for (const item of cleanupHolder) {
+      item.list.forEach((fn) => fn());
+      item.list.clear();
+      dom.add(item.dom);
+    }
+    cleanupHolder.length = 0;
+    dom.forEach((fn) => fn());
   };
   const getResourseTypeWrapper = (url) => {
     return getResourseType({
@@ -1839,7 +1880,7 @@ var novely = ({
     preview,
     removeContext,
     getStateFunction,
-    clearCustomAction,
+    clearCustomActionsAtContext,
     languages,
     storageData,
     coreData,