@novely/core 0.34.0 → 0.36.0-beta.0

package/dist/index.d.ts

@@ -75,6 +75,20 @@ interface CharacterHandle {
     animate: (timeout: number, classes: string[]) => void;
     emotions: Record<string, HTMLImageElement[]>;
 }
+type CustomActionHandle = {
+    /**
+     * Function to remove custom action from screen (and from your state if any completely)
+     */
+    remove: () => void;
+    /**
+     * 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;
     pause: () => void;
@@ -93,8 +107,7 @@ type Context = {
         music: Set<string>;
         sounds: Set<string>;
     }, resolve: () => void) => void;
-    custom: (fn: CustomHandler<Lang, State>, push: () => void) => Thenable<void>;
-    clearCustom: (fn: CustomHandler<Lang, State>) => void;
+    custom: (fn: CustomHandler<Lang, State>) => CustomActionHandle;
     /**
      * Clears all mentioned actions except for preserved one
      * @param preserve Action that should not be cleared
@@ -213,6 +226,7 @@ type RendererInit<$Language extends Lang, $Characters extends Record<string, Cha
     preview: (save: Save<State>, name: string) => Promise<void>;
     removeContext: (name: string) => void;
     getStateFunction: (context: string) => StateFunction<State>;
+    clearCustomAction: (ctx: Context, customAction: CustomHandler) => void;
     getLanguageDisplayName: (lang: Lang) => string;
 };
 
@@ -438,7 +452,7 @@ interface NovelyInit<$Language extends Lang, $Characters extends Record<string,
     /**
      * @default "lazy"
      */
-    preloadAssets?: 'lazy' | 'blocking';
+    preloadAssets?: 'lazy' | 'blocking' | 'automatic';
     /**
      * Fetching function
      */
@@ -499,36 +513,59 @@ type FunctionableValue<T> = T | (() => T);
 type CustomHandlerGetResultDataFunction = (data?: Record<string, unknown>) => Record<string, unknown>;
 type CustomHandlerGetResult<I extends boolean> = {
     /**
-     * Remove's custom handler instance
+     * Element for the custom action to be rendered into
      */
-    remove: () => void;
+    element: I extends true ? HTMLDivElement : null;
     /**
-     * Данные
+     * Root node
      */
-    data: CustomHandlerGetResultDataFunction;
+    root: HTMLElement;
+};
+type CustomHandlerFunctionGetFn = <I extends boolean = true>(insert?: I) => CustomHandlerGetResult<I>;
+type CustomHandlerFunctionParameters<L extends string, S extends State> = {
     /**
-     * Элемент слоя
+     * Returns:
+     * - Root where entire novely is mounted
+     * - Element in which custom action could be mounted
+     *
+     * @example
+     * ```ts
+     * // pass `true` to insert element to the DOM
+     * const { root, element } = getDomNodes(true);
+     * ```
      */
-    element: I extends true ? HTMLDivElement : null;
+    getDomNodes: CustomHandlerFunctionGetFn;
     /**
-     * Корневой элемент Novely
+     * Renderer Context
      */
-    root: HTMLElement;
+    rendererContext: Context;
     /**
-     * Устанавливает обработчик очистки
+     * Function to work with custom action's state
+     */
+    data: CustomHandlerGetResultDataFunction;
+    /**
+     * Function to set cleanup handler
      */
     clear: (fn: () => void) => void;
-    __internals: {
-        ctx: Context;
-    };
-};
-type CustomHandlerFunctionGetFn = <I extends boolean = true>(insert?: I) => CustomHandlerGetResult<I>;
-type CustomHandlerFunctionParameters<L extends string, S extends State> = {
-    get: CustomHandlerFunctionGetFn;
+    /**
+     * Remove's custom handler instance
+     */
+    remove: () => void;
+    /**
+     * Context's state function
+     */
     state: StateFunction<S>;
-    restoring: boolean;
-    goingBack: boolean;
-    preview: boolean;
+    /**
+     * Game flags (aka game states)
+     */
+    flags: {
+        restoring: boolean;
+        goingBack: boolean;
+        preview: boolean;
+    };
+    /**
+     * Game language
+     */
     lang: L;
 };
 type CustomHandlerFunction<L extends string, S extends State> = (parameters: CustomHandlerFunctionParameters<L, S>) => Thenable<void>;
@@ -799,4 +836,4 @@ declare const novely: <$Language extends string, $Characters extends Record<stri
  */
 declare const extendAction: <Part0 extends Record<string, (...args: any[]) => ValidAction>, Part1 extends Record<string, (...args: any[]) => ValidAction>>(base: Part0, extension: Part1) => Readonly<Assign<Part0, Part1>>;
 
-export { type ActionInputOnInputMeta, type ActionInputSetup, type ActionInputSetupCleanup, type ActionProxy, type AllowedContent, type AudioHandle, type BackgroundImage, type BaseTranslationStrings, type Character, type CharacterHandle, type ConditionParams, type Context, type CoreData, type CustomHandler, type CustomHandlerFunctionGetFn, type CustomHandlerFunctionParameters, type CustomHandlerGetResult, type CustomHandlerGetResultDataFunction, type Data, type DeepPartial, type DefaultActionProxy, EN, type Emotions, type FunctionableValue, type GetActionParameters, type InputHandler, JP, KK, type Lang, type NovelyInit, type NovelyScreen, type Path, type PluralType, type Pluralization, RU, type Renderer, type RendererInit, type Save, type Stack, type StackHolder, type State, type StateFunction, type Storage, type StorageData, type StorageMeta, type Stored, type Story, type TextContent, type Thenable, type TranslationActions, type TypeEssentials, type TypewriterSpeed, type ValidAction, extendAction, localStorageStorage, novely };
+export { type ActionInputOnInputMeta, type ActionInputSetup, type ActionInputSetupCleanup, type ActionProxy, type AllowedContent, type AudioHandle, type BackgroundImage, type BaseTranslationStrings, type Character, type CharacterHandle, type ConditionParams, type Context, type CoreData, type CustomActionHandle, type CustomHandler, type CustomHandlerFunctionGetFn, type CustomHandlerFunctionParameters, type CustomHandlerGetResult, type CustomHandlerGetResultDataFunction, type Data, type DeepPartial, type DefaultActionProxy, EN, type Emotions, type FunctionableValue, type GetActionParameters, type InputHandler, JP, KK, type Lang, type NovelyInit, type NovelyScreen, type Path, type PluralType, type Pluralization, RU, type Renderer, type RendererInit, type Save, type Stack, type StackHolder, type State, type StateFunction, type Storage, type StorageData, type StorageMeta, type Stored, type Story, type TextContent, type Thenable, type TranslationActions, type TypeEssentials, type TypewriterSpeed, type ValidAction, extendAction, localStorageStorage, novely };

package/dist/index.global.js

@@ -210,6 +210,7 @@ var Novely = (() => {
 
   // src/shared.ts
   var STACK_MAP = /* @__PURE__ */ new Map();
+  var CUSTOM_ACTION_MAP = /* @__PURE__ */ new Map();
   var PRELOADED_ASSETS = /* @__PURE__ */ new Set();
 
   // ../../node_modules/.pnpm/esm-env@1.0.0/node_modules/esm-env/prod-ssr.js
@@ -244,9 +245,16 @@ var Novely = (() => {
   }
 
   // src/utils.ts
-  var matchAction = ({ getContext, push, forward }, values) => {
+  var matchAction = ({ getContext, onBeforeActionCall, push, forward }, values) => {
     return (action, props, { ctx, data }) => {
       const context = typeof ctx === "string" ? getContext(ctx) : ctx;
+      if (action !== "say") {
+        onBeforeActionCall({
+          action,
+          props,
+          ctx: context
+        });
+      }
       return values[action]({
         ctx: context,
         data,
@@ -411,7 +419,7 @@ var Novely = (() => {
   var getActionsFromPath = (story, path, filter) => {
     let current = story;
     let precurrent;
-    let ignoreNested = false;
+    let ignoreNestedBefore = null;
     let index = 0;
     let skipPreserve = void 0;
     const skip = /* @__PURE__ */ new Set();
@@ -432,11 +440,11 @@ var Novely = (() => {
         if (isNumber(val)) {
           index++;
           let startIndex = 0;
-          if (ignoreNested) {
-            const prev = findLastPathItemBeforeItemOfType(path.slice(0, index), "block");
+          if (ignoreNestedBefore) {
+            const prev = findLastPathItemBeforeItemOfType(path.slice(0, index), ignoreNestedBefore);
             if (prev) {
               startIndex = prev[1];
-              ignoreNested = false;
+              ignoreNestedBefore = null;
             }
           }
           for (let i = startIndex; i <= val; i++) {
@@ -471,7 +479,7 @@ var Novely = (() => {
         current = story[val];
       } else if (type === "block:exit" || type === "choice:exit" || type === "condition:exit") {
         current = blocks.pop();
-        ignoreNested = true;
+        ignoreNestedBefore = type.slice(0, -5);
       }
     }
     return {
@@ -655,6 +663,9 @@ var Novely = (() => {
     }
   };
   var getResourseType = async (request, url) => {
+    if (!isCSSImage(url)) {
+      return "other";
+    }
     const extension = getUrlFileExtension(url);
     if (HOWLER_SUPPORTED_FILE_FORMATS.has(extension)) {
       return "audio";
@@ -768,6 +779,68 @@ var Novely = (() => {
     }
     return path;
   };
+  var isBlockingAction = (action) => {
+    return isUserRequiredAction(action) || isSkippedDuringRestore(action[0]) && action[0] !== "vibrate";
+  };
+  var collectActionsBeforeBlockingAction = ({ path, refer }) => {
+    const collection = [];
+    let action = refer(path);
+    while (true) {
+      if (action == void 0) {
+        const { exitImpossible } = exitPath({
+          path,
+          refer
+        });
+        if (exitImpossible) {
+          break;
+        }
+      }
+      if (!action) {
+        break;
+      }
+      if (isBlockingAction(action)) {
+        const [name, ...props] = action;
+        if (name === "choice") {
+          const choiceProps = props;
+          for (let i = 0; i < choiceProps.length; i++) {
+            const branchContent = choiceProps[i];
+            if (!Array.isArray(branchContent))
+              continue;
+            const virtualPath = klona(path);
+            virtualPath.push(["choice", i], [null, 0]);
+            const innerActions = collectActionsBeforeBlockingAction({
+              path: virtualPath,
+              refer
+            });
+            collection.push(...innerActions);
+          }
+        } else if (name === "condition") {
+          const conditionProps = props;
+          const conditions = Object.keys(conditionProps[1]);
+          for (const condition of conditions) {
+            const virtualPath = klona(path);
+            virtualPath.push(["condition", condition], [null, 0]);
+            const innerActions = collectActionsBeforeBlockingAction({
+              path: virtualPath,
+              refer
+            });
+            collection.push(...innerActions);
+          }
+        }
+        break;
+      }
+      collection.push(action);
+      if (action[0] === "jump") {
+        path = [["jump", action[1]], [null, 0]];
+      } else if (action[0] == "block") {
+        path.push(["block", action[1]], [null, 0]);
+      } else {
+        nextPath(path);
+      }
+      action = refer(path);
+    }
+    return collection;
+  };
 
   // ../../node_modules/.pnpm/dequal@2.0.3/node_modules/dequal/lite/index.mjs
   var has = Object.prototype.hasOwnProperty;
@@ -943,6 +1016,76 @@ var Novely = (() => {
     });
   };
 
+  // src/custom-action.ts
+  var createCustomActionNode = (id) => {
+    const div = document.createElement("div");
+    div.setAttribute("data-id", id);
+    return div;
+  };
+  var getCustomActionHolder = (ctx, fn) => {
+    const cached = CUSTOM_ACTION_MAP.get(ctx.id + fn.key);
+    if (cached) {
+      return cached;
+    }
+    const holder = {
+      cleanup: noop,
+      node: null,
+      fn,
+      localData: {}
+    };
+    CUSTOM_ACTION_MAP.set(ctx.id + fn.key, holder);
+    return holder;
+  };
+  var handleCustomAction = (ctx, fn, { lang, state, setMountElement, setClear, remove: renderersRemove }) => {
+    const holder = getCustomActionHolder(ctx, fn);
+    const flags = {
+      ...ctx.meta
+    };
+    const getDomNodes = (insert = true) => {
+      if (holder.node || !insert) {
+        return {
+          element: holder.node,
+          root: ctx.root
+        };
+      }
+      holder.node = insert ? createCustomActionNode(fn.key) : null;
+      setMountElement(holder.node);
+      return {
+        element: holder.node,
+        root: ctx.root
+      };
+    };
+    const clear = (func) => {
+      setClear(holder.cleanup = () => {
+        func();
+        holder.node = null;
+        holder.cleanup = noop;
+        setMountElement(null);
+        setClear(noop);
+      });
+    };
+    const data = (updatedData) => {
+      if (updatedData) {
+        return holder.localData = updatedData;
+      }
+      return holder.localData;
+    };
+    const remove = () => {
+      holder.cleanup();
+      renderersRemove();
+    };
+    return fn({
+      flags,
+      lang,
+      state,
+      data,
+      clear,
+      remove,
+      rendererContext: ctx,
+      getDomNodes
+    });
+  };
+
   // src/storage.ts
   var localStorageStorage = (options) => {
     return {
@@ -1016,6 +1159,26 @@ var Novely = (() => {
     const intime = (value) => {
       return times.add(value), value;
     };
+    const handleAssetsPreloading = async () => {
+      const { preloadAudioBlocking, preloadImageBlocking } = renderer.misc;
+      const list = mapSet(ASSETS_TO_PRELOAD, (asset) => {
+        return limitAssetsDownload(async () => {
+          const type = await getResourseType(request, asset);
+          switch (type) {
+            case "audio": {
+              await preloadAudioBlocking(asset);
+              break;
+            }
+            case "image": {
+              await preloadImageBlocking(asset);
+              break;
+            }
+          }
+        });
+      });
+      await Promise.allSettled(list);
+      ASSETS_TO_PRELOAD.clear();
+    };
     const scriptBase = async (part) => {
       Object.assign(story, flattenStory(part));
       let loadingIsShown = false;
@@ -1027,31 +1190,14 @@ var Novely = (() => {
         if (!loadingIsShown) {
           renderer.ui.showLoading();
         }
-        const { preloadAudioBlocking, preloadImageBlocking } = renderer.misc;
-        const list = mapSet(ASSETS_TO_PRELOAD, (asset) => {
-          return limitAssetsDownload(async () => {
-            const type = await getResourseType(request, asset);
-            switch (type) {
-              case "audio": {
-                await preloadAudioBlocking(asset);
-                break;
-              }
-              case "image": {
-                await preloadImageBlocking(asset);
-                break;
-              }
-            }
-          });
-        });
-        await Promise.allSettled(list);
+        await handleAssetsPreloading();
       }
-      ASSETS_TO_PRELOAD.clear();
       await dataLoaded.promise;
       renderer.ui.hideLoading();
       if (!initialScreenWasShown) {
         initialScreenWasShown = true;
         if (initialScreen === "game") {
-          restore();
+          restore(void 0);
         } else {
           renderer.ui.showScreen(initialScreen);
         }
@@ -1060,6 +1206,33 @@ var Novely = (() => {
     const script = (part) => {
       return limitScript(() => scriptBase(part));
     };
+    const checkAndAddToPreloadingList = (action2, props) => {
+      if (action2 === "showBackground") {
+        if (isImageAsset(props[0])) {
+          ASSETS_TO_PRELOAD.add(props[0]);
+        }
+        if (props[0] && typeof props[0] === "object") {
+          for (const value of Object.values(props[0])) {
+            if (!isImageAsset(value))
+              continue;
+            ASSETS_TO_PRELOAD.add(value);
+          }
+        }
+      }
+      if (isAudioAction(action2) && isString(props[0])) {
+        ASSETS_TO_PRELOAD.add(props[0]);
+      }
+      if (action2 === "showCharacter" && isString(props[0]) && isString(props[1])) {
+        const images = characters[props[0]].emotions[props[1]];
+        if (Array.isArray(images)) {
+          for (const asset of images) {
+            ASSETS_TO_PRELOAD.add(asset);
+          }
+        } else {
+          ASSETS_TO_PRELOAD.add(images);
+        }
+      }
+    };
     const action = new Proxy({}, {
       get(_, action2) {
         if (action2 in renderer.actions) {
@@ -1067,31 +1240,7 @@ var Novely = (() => {
         }
         return (...props) => {
           if (preloadAssets === "blocking") {
-            if (action2 === "showBackground") {
-              if (isImageAsset(props[0])) {
-                ASSETS_TO_PRELOAD.add(props[0]);
-              }
-              if (props[0] && typeof props[0] === "object") {
-                for (const value of Object.values(props[0])) {
-                  if (!isImageAsset(value))
-                    continue;
-                  ASSETS_TO_PRELOAD.add(value);
-                }
-              }
-            }
-            if (isAudioAction(action2) && isString(props[0])) {
-              ASSETS_TO_PRELOAD.add(props[0]);
-            }
-            if (action2 === "showCharacter" && isString(props[0]) && isString(props[1])) {
-              const images = characters[props[0]].emotions[props[1]];
-              if (Array.isArray(images)) {
-                for (const asset of images) {
-                  ASSETS_TO_PRELOAD.add(asset);
-                }
-              } else {
-                ASSETS_TO_PRELOAD.add(images);
-              }
-            }
+            checkAndAddToPreloadingList(action2, props);
           }
           return [action2, ...props];
         };
@@ -1218,7 +1367,12 @@ var Novely = (() => {
           return prev.saves.push(save2), prev;
         });
       }
-      restore(save2);
+      const context = renderer.getContext(MAIN_CONTEXT_KEY);
+      const stack = useStack(context);
+      stack.value = save2;
+      context.meta.restoring = context.meta.goingBack = false;
+      renderer.ui.showScreen("game");
+      render(context);
     };
     const set = (save2, ctx) => {
       const stack = useStack(ctx || MAIN_CONTEXT_KEY);
@@ -1263,7 +1417,7 @@ var Novely = (() => {
           }
           const [action2, fn] = element;
           if (action2 === "custom") {
-            context.clearCustom(fn);
+            getCustomActionHolder(context, fn).cleanup();
           }
         }
       }
@@ -1273,8 +1427,8 @@ var Novely = (() => {
           data: latest[1]
         });
       }
-      const lastQueueItem = queue.at(-1) || [];
-      const lastQueueItemRequiresUserAction = isSkippedDuringRestore(lastQueueItem[0]) || isUserRequiredAction(lastQueueItem);
+      const lastQueueItem = queue.at(-1);
+      const lastQueueItemRequiresUserAction = lastQueueItem && isBlockingAction(lastQueueItem);
       await run((item) => {
         if (!latest)
           return;
@@ -1388,6 +1542,9 @@ var Novely = (() => {
       }
       return capitalize(language.nameOverride || getIntlLanguageDisplayName(lang));
     };
+    const clearCustomAction = (ctx, fn) => {
+      getCustomActionHolder(ctx, fn).cleanup();
+    };
     const renderer = createRenderer({
       mainContextKey: MAIN_CONTEXT_KEY,
       characters,
@@ -1401,6 +1558,7 @@ var Novely = (() => {
       preview,
       removeContext,
       getStateFunction,
+      clearCustomAction,
       languages,
       storageData,
       coreData,
@@ -1437,6 +1595,40 @@ var Novely = (() => {
         matchActionOptions.push(ctx);
         if (!ctx.meta.preview)
           interactivity(true);
+      },
+      onBeforeActionCall({ action: action2, props, ctx }) {
+        if (preloadAssets !== "automatic")
+          return;
+        if (ctx.meta.preview || ctx.meta.restoring)
+          return;
+        if (!isBlockingAction([action2, ...props]))
+          return;
+        try {
+          const collection = collectActionsBeforeBlockingAction({
+            path: nextPath(klona(useStack(ctx).value[0])),
+            refer
+          });
+          for (const [action3, ...props2] of collection) {
+            checkAndAddToPreloadingList(action3, props2);
+          }
+          const { preloadAudioBlocking, preloadImage } = renderer.misc;
+          ASSETS_TO_PRELOAD.forEach(async (asset) => {
+            ASSETS_TO_PRELOAD.delete(asset);
+            const type = await getResourseType(request, asset);
+            switch (type) {
+              case "audio": {
+                preloadAudioBlocking(asset);
+                break;
+              }
+              case "image": {
+                preloadImage(asset);
+                break;
+              }
+            }
+          });
+        } catch (cause) {
+          console.error(cause);
+        }
       }
     };
     const match = matchAction(matchActionOptions, {
@@ -1644,19 +1836,31 @@ var Novely = (() => {
           forward
         );
       },
-      custom({ ctx, push }, [handler]) {
-        if (handler.requireUserAction) {
+      custom({ ctx, push }, [fn]) {
+        if (fn.requireUserAction) {
           ctx.clearBlockingActions(void 0);
         }
-        const result = ctx.custom(handler, () => {
-          if (ctx.meta.restoring)
-            return;
-          if (handler.requireUserAction && !ctx.meta.preview) {
+        const state = getStateFunction(ctx);
+        const lang = storageData.get().meta[0];
+        const result = handleCustomAction(ctx, fn, {
+          ...ctx.custom(fn),
+          state,
+          lang
+        });
+        const next2 = () => {
+          if (fn.requireUserAction && !ctx.meta.preview) {
             enmemory(ctx);
             interactivity(true);
           }
           push();
-        });
+        };
+        if (!ctx.meta.restoring) {
+          if (isPromise(result)) {
+            result.then(next2);
+          } else {
+            next2();
+          }
+        }
         return result;
       },
       vibrate({ ctx, push }, pattern) {
@@ -1706,6 +1910,9 @@ var Novely = (() => {
         render(ctx);
       },
       preload({ ctx, push }, [source]) {
+        if (DEV && preloadAssets !== "lazy") {
+          console.error(`You do not need a preload action becase "preloadAssets" strategy was set to "${preloadAssets}"`);
+        }
         if (!ctx.meta.goingBack && !ctx.meta.restoring && !PRELOADED_ASSETS.has(source)) {
           PRELOADED_ASSETS.add(renderer.misc.preloadImage(source));
         }