@novely/core 0.33.3 → 0.35.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;
 };
 
@@ -499,46 +513,102 @@ 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>;
-type CustomHandler<L extends string = string, S extends State = State> = CustomHandlerFunction<L, S> & {
+type CustomHandlerCalling = {
+    /**
+     * Call only the last custom action of this type or not. Does not affect other custom actions
+     * @example
+     * ```ts
+     * ['custom', customSomething1]
+     * ['custom', customSomething1]
+     * ['custom', customSomething1] <-- Run only that
+     * ```
+     */
     callOnlyLatest?: boolean;
+    /**
+     * Manually check should be skipped or not during restore
+     * @param getNext Function which will return next actions in queue
+     */
+    skipOnRestore?: (getNext: () => Exclude<ValidAction, ValidAction[]>[]) => boolean;
+};
+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
+     *
+     * It IS recommended to pass this property as it will speed up that check and make it more reliable
+     */
     id?: string | symbol;
+    /**
+     * Key by which we will save the data in the `get` function provided to custom action.
+     *
+     * It can be a name of action or more specific thing. In example for custom `showCharacter` it may be `show-character-${character}
+     */
     key: string;
 };
+type CustomHandler<L extends string = string, S extends State = State> = CustomHandlerFunction<L, S> & CustomHandlerInfo;
 interface ActionInputOnInputMeta<L extends string, S extends State> {
     /**
      * Input Element itself
@@ -594,7 +664,8 @@ type ChoiceCheckFunctionProps<L extends string, S extends State> = {
 type ChoiceCheckFunction<L extends string, S extends State> = (props: ChoiceCheckFunctionProps<L, S>) => boolean;
 type ConditionCheckFunction<S extends State, R extends string | true | false> = (state: S) => R;
 type FunctionAction<L extends string, S extends State> = (props: FunctionActionProps<L, S>) => Thenable<void>;
-type ActionInputSetup = (input: HTMLInputElement, cleanup: (cb: () => void) => void) => void;
+type ActionInputSetupCleanup = () => void;
+type ActionInputSetup = (input: HTMLInputElement) => ActionInputSetupCleanup | void;
 type BackgroundImage = Partial<Record<'portrait' | 'landscape' | 'all', string>> & Record<string, string>;
 type VoiceAction<L extends Lang> = (params: string | Partial<Record<L, string>>) => ValidAction;
 type ActionProxy<Characters extends Record<string, Character>, Languages extends Lang, S extends State> = {
@@ -765,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 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
@@ -496,18 +497,31 @@ var Novely = (() => {
       }
       keep.add(action);
       if (action === "function" || action === "custom") {
-        if (action === "custom" && params[0].callOnlyLatest) {
-          const notLatest = next(i).some(([, func]) => {
-            if (!isFunction(func))
-              return false;
-            const c0 = func;
-            const c1 = params[0];
-            const isIdenticalID = Boolean(c0.id && c1.id && c0.id === c1.id);
-            const isIdenticalByReference = c0 === c1;
-            return isIdenticalID || isIdenticalByReference || str(c0) === str(c1);
-          });
-          if (notLatest)
-            continue;
+        if (action === "custom") {
+          const fn = params[0];
+          if ("callOnlyLatest" in fn && fn.callOnlyLatest) {
+            const notLatest = next(i).some(([, func]) => {
+              if (!isFunction(func))
+                return false;
+              const c0 = func;
+              const c1 = fn;
+              const isIdenticalID = Boolean(c0.id && c1.id && c0.id === c1.id);
+              const isIdenticalByReference = c0 === c1;
+              return isIdenticalID || isIdenticalByReference || str(c0) === str(c1);
+            });
+            if (notLatest)
+              continue;
+          } else if ("skipOnRestore" in fn && fn.skipOnRestore) {
+            let getNext = () => {
+              const nextActions = next(i);
+              getNext = () => {
+                return nextActions;
+              };
+              return nextActions;
+            };
+            if (fn.skipOnRestore(getNext))
+              continue;
+          }
         }
         processedQueue.push(item);
       } else if (action === "showCharacter" || action === "playSound" || action === "playMusic" || action === "voice") {
@@ -930,6 +944,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 {
@@ -1250,7 +1334,7 @@ var Novely = (() => {
           }
           const [action2, fn] = element;
           if (action2 === "custom") {
-            context.clearCustom(fn);
+            getCustomActionHolder(context, fn).cleanup();
           }
         }
       }
@@ -1375,6 +1459,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,
@@ -1388,6 +1475,7 @@ var Novely = (() => {
       preview,
       removeContext,
       getStateFunction,
+      clearCustomAction,
       languages,
       storageData,
       coreData,
@@ -1631,19 +1719,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) {