@novely/core 0.29.1 → 0.30.0

package/dist/index.d.ts

@@ -1,11 +1,3 @@
-type Name<Keys extends string = string> = string | Record<Keys, string>;
-type Emotions<Keys extends string = string> = Record<Keys, string | string[]>;
-type Character<LanguageKeys extends string = string> = {
-    name: Name<LanguageKeys>;
-    color: string;
-    emotions: Emotions;
-};
-
 interface LocalStorageStorageSettings {
     key: string;
 }
@@ -17,7 +9,7 @@ declare const localStorageStorage: (options: LocalStorageStorageSettings) => Sto
 
 type PluralType = Intl.LDMLPluralRule;
 type Pluralization = Partial<Record<PluralType, string>>;
-type AllowedContent = string | ((state: State) => string | string[]) | string[] | (string | ((state: State) => string | string[]))[];
+type AllowedContent = string | ((state: State | Data) => string | string[]) | string[] | (string | ((state: State | Data) => string | string[]))[];
 type TranslationActions = Partial<Record<string, (str: string) => string>>;
 
 declare const RU: {
@@ -215,6 +207,7 @@ type RendererInit = {
     preview: (save: Save<State>, name: string) => Promise<void>;
     removeContext: (name: string) => void;
     getStateFunction: (context: string) => StateFunction<State>;
+    getLanguageDisplayName: (lang: Lang) => string;
 };
 
 declare const getLanguage: (languages: string[]) => string;
@@ -236,7 +229,7 @@ type Save<S extends State = State> = [
 type Lang = string;
 type TypewriterSpeed = 'Slow' | 'Medium' | 'Fast' | 'Auto';
 type SoundVolume = number;
-type StorageMeta<L extends string = string> = [
+type StorageMeta<L extends Lang = string> = [
     lang: L,
     typewriter_speed: TypewriterSpeed,
     music_volume: SoundVolume,
@@ -244,7 +237,7 @@ type StorageMeta<L extends string = string> = [
     voice_volume: SoundVolume
 ];
 type Migration = (save: unknown) => unknown;
-type StorageData<L extends string = string, D extends Data = Data> = {
+type StorageData<L extends Lang = string, D extends Data = Data> = {
     saves: Save[];
     data: D;
     meta: StorageMeta<L>;
@@ -275,6 +268,10 @@ type TranslationDescription = {
      * IETF BCP 47 language tag
      */
     tag?: string;
+    /**
+     * Custom name
+     */
+    nameOverride?: string;
     plural?: Record<string, Pluralization>;
     actions?: TranslationActions;
 };
@@ -298,6 +295,36 @@ interface NovelyInit<$Language extends Lang, Characters extends Record<string, C
      * ```
      */
     characters: Characters;
+    /**
+     * Define default emotions for characters
+     * @example
+     * ```ts
+     * const engine = novely({
+     *  characters: {
+     *   Yuki: {
+     *    name: 'Yuki',
+     *    color: '#f595f6',
+     *    emotions: {
+     *     normal: './normal.png'
+     *    }
+     *   }
+     *  },
+     *  defaultEmotions: {
+     *   Yuki: 'normal'
+     *  }
+     * });
+     *
+     * engine.script({
+     *  start: [
+     *    // Without emotion!
+     *    engine.action.showCharacter('Yuki')
+     *  ]
+     * })
+     * ```
+     */
+    defaultEmotions?: {
+        [Character in keyof NoInfer<Characters>]?: (keyof NoInfer<Characters>[Character]['emotions'] & string);
+    };
     /**
      * An object that provides access to the game's storage system.
      * @default localStorage // at key `novely-game-storage`
@@ -409,12 +436,40 @@ interface NovelyInit<$Language extends Lang, Characters extends Record<string, C
      * @default true
      */
     saveOnUnload?: boolean | 'prod';
+    /**
+     * The key that signifies the start of the game. It is not recommended to override this parameter.
+     *
+     * @default 'start'
+     * @example
+     * ```ts
+     * const engine = novely({
+     *   ...,
+     *   startKey: 'PART_1'
+     * })
+     *
+     * engine.script({
+     *   // now game will start from here
+     *   PART_1: [
+     *
+     *   ]
+     * })
+     * ```
+     */
+    startKey?: 'start' | (string & Record<never, never>);
 }
 type StateFunction<S extends State> = {
     (value: DeepPartial<S> | ((prev: S) => S)): void;
     (): S;
 };
 
+type Name<$Lang extends Lang> = string | Record<$Lang, string>;
+type Emotions<Emotion extends string = string> = Record<Emotion, string | string[]>;
+type Character<$Lang extends Lang = string> = {
+    name: Name<$Lang>;
+    color: string;
+    emotions: Emotions;
+};
+
 type ValidAction = ['choice', number] | ['clear', Set<keyof DefaultActionProxy>?, Set<string>?, {
     music: Set<string>;
     sounds: Set<string>;
@@ -515,10 +570,11 @@ 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 BackgroundImage = Partial<Record<'portrait' | 'landscape' | 'all', string>> & Record<string, string>;
-type ActionProxy<Characters extends Record<string, Character>, Languages extends string, S extends State> = {
+type ActionProxy<Characters extends Record<string, Character>, Languages extends Lang, S extends State> = {
     choice: {
         (...choices: [name: TextContent<Languages, S>, actions: ValidAction[], active?: ChoiceCheckFunction<Languages, S>][]): ValidAction;
         (question: TextContent<Languages, S>, ...choices: [name: TextContent<Languages, S>, actions: ValidAction[], active?: ChoiceCheckFunction<Languages, S>][]): ValidAction;
@@ -527,7 +583,7 @@ type ActionProxy<Characters extends Record<string, Character>, Languages extends
         music: Set<string>;
         sounds: Set<string>;
     }) => ValidAction;
-    condition: <T extends string | true | false>(condition: (state: S) => T, variants: Record<T extends true ? 'true' : T extends false ? 'false' : T, ValidAction[]>) => ValidAction;
+    condition: <T extends string | true | false>(condition: ConditionCheckFunction<S, T>, variants: Record<T extends true ? 'true' : T extends false ? 'false' : T, ValidAction[]>) => ValidAction;
     exit: () => ValidAction;
     dialog: {
         <C extends keyof Characters>(character: C, content: TextContent<Languages, S>, emotion?: keyof Characters[C]['emotions']): ValidAction;
@@ -553,7 +609,7 @@ type ActionProxy<Characters extends Record<string, Character>, Languages extends
     stopVoice: () => ValidAction;
     jump: (scene: string) => ValidAction;
     showCharacter: {
-        <C extends keyof Characters>(character: C, emotion: keyof Characters[C]['emotions'], className?: string, style?: string): ValidAction;
+        <C extends keyof Characters>(character: C, emotion?: keyof Characters[C]['emotions'], className?: string, style?: string): ValidAction;
     };
     hideCharacter: (character: keyof Characters, className?: string, style?: string, duration?: number) => ValidAction;
     animateCharacter: (character: keyof Characters, timeout: number, ...classes: string[]) => ValidAction;
@@ -567,10 +623,12 @@ type ActionProxy<Characters extends Record<string, Character>, Languages extends
     preload: (source: string) => ValidAction;
     block: (scene: string) => ValidAction;
 };
-type DefaultActionProxy = ActionProxy<Record<string, Character>, string, State>;
+type DefaultActionProxy = ActionProxy<Record<string, Character>, Lang, State>;
 type GetActionParameters<T extends Capitalize<keyof DefaultActionProxy>> = Parameters<DefaultActionProxy[Uncapitalize<T>]>;
 
-declare const novely: <Languages extends string, Characters extends Record<string, Character<Languages>>, StateScheme extends State, DataScheme extends Data>({ characters, storage, storageDelay, renderer: createRenderer, initialScreen, translation, state: defaultState, data: defaultData, autosaves, migrations, throttleTimeout, getLanguage, overrideLanguage, askBeforeExit, preloadAssets, parallelAssetsDownloadLimit, fetch: request, saveOnUnload }: NovelyInit<Languages, Characters, StateScheme, DataScheme>) => {
+type ConditionParams<T> = T extends ActionProxy<Record<string, Character>, Lang, infer $State> ? Parameters<ConditionCheckFunction<$State, string | boolean>>[0] : never;
+
+declare const novely: <$Language extends string, Characters extends Record<string, Character<$Language>>, StateScheme extends State, DataScheme extends Data>({ characters, defaultEmotions, storage, storageDelay, renderer: createRenderer, initialScreen, translation, state: defaultState, data: defaultData, autosaves, migrations, throttleTimeout, getLanguage, overrideLanguage, askBeforeExit, preloadAssets, parallelAssetsDownloadLimit, fetch: request, saveOnUnload, startKey }: NovelyInit<$Language, Characters, StateScheme, DataScheme>) => {
     /**
      * Function to set game script
      *
@@ -596,7 +654,7 @@ declare const novely: <Languages extends string, Characters extends Record<strin
      * })
      * ```
      */
-    action: ActionProxy<Characters, Languages, StateScheme>;
+    action: ActionProxy<Characters, $Language, StateScheme>;
     /**
      * @deprecated Will be removed BUT replaced with state passed into actions as a parameter
      */
@@ -621,7 +679,7 @@ declare const novely: <Languages extends string, Characters extends Record<strin
     /**
      * @deprecated Renamed into `templateReplace`
      */
-    unwrap(content: TextContent<Languages, DataScheme>): string;
+    unwrap(content: TextContent<$Language, DataScheme>): string;
     /**
      * Replaces content inside {{braces}} with using global data
      * @example
@@ -634,7 +692,7 @@ declare const novely: <Languages extends string, Characters extends Record<strin
      * })
      * ```
      */
-    templateReplace(content: TextContent<Languages, DataScheme>): string;
+    templateReplace(content: TextContent<$Language, DataScheme>): string;
     /**
      * Cancel data loading, hide UI, ignore page change events
      * Data updates still will work in case Novely already was loaded
@@ -642,4 +700,4 @@ declare const novely: <Languages extends string, Characters extends Record<strin
     destroy(): void;
 };
 
-export { type ActionInputOnInputMeta, type ActionInputSetup, type ActionProxy, type AllowedContent, type AudioHandle, type BackgroundImage, type BaseTranslationStrings, type Character, type CharacterHandle, 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, 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 TypewriterSpeed, type ValidAction, localStorageStorage, novely };
+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, 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 TypewriterSpeed, type ValidAction, localStorageStorage, novely };

package/dist/index.global.js

@@ -209,6 +209,7 @@ var Novely = (() => {
 
   // src/shared.ts
   var STACK_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
   var DEV = false;
@@ -628,6 +629,19 @@ var Novely = (() => {
     }
     return "other";
   };
+  var capitalize = (str2) => {
+    return str2[0].toUpperCase() + str2.slice(1);
+  };
+  var getIntlLanguageDisplayName = (lang) => {
+    try {
+      const intl = new Intl.DisplayNames([lang], {
+        type: "language"
+      });
+      return intl.of(lang) || lang;
+    } catch {
+      return lang;
+    }
+  };
 
   // ../../node_modules/.pnpm/dequal@2.0.3/node_modules/dequal/lite/index.mjs
   var has = Object.prototype.hasOwnProperty;
@@ -661,9 +675,6 @@ var Novely = (() => {
     return foo !== foo && bar !== bar;
   }
 
-  // src/global.ts
-  var PRELOADED_ASSETS = /* @__PURE__ */ new Set();
-
   // src/store.ts
   var store = (current, subscribers = /* @__PURE__ */ new Set()) => {
     const subscribe = (cb) => {
@@ -688,7 +699,7 @@ var Novely = (() => {
     return { subscribe, update, set, get };
   };
 
-  // ../deepmerge/dist/index.js
+  // ../../node_modules/.pnpm/@novely+deepmerge@0.0.0/node_modules/@novely/deepmerge/dist/index.js
   var { isArray } = Array;
   var { hasOwnProperty, propertyIsEnumerable, getOwnPropertySymbols } = Object;
   var propertyIsOnObject = (object, property) => {
@@ -811,10 +822,10 @@ var Novely = (() => {
     }
     return c;
   };
-  var replace = (str2, obj, pluralization, actions, pr) => {
-    return str2.replaceAll(RGX, (x, key, y) => {
+  var replace = (input, data, pluralization, actions, pr) => {
+    return input.replaceAll(RGX, (x, key, y) => {
       x = 0;
-      y = obj;
+      y = data;
       const [pathstr, plural, action] = split(key.trim(), ["@", "%"]);
       if (!pathstr) {
         return "";
@@ -825,7 +836,7 @@ var Novely = (() => {
       if (plural && pluralization && y && pr) {
         y = pluralization[plural][pr.select(y)];
       }
-      const actionHandler = actions && action && actions[action];
+      const actionHandler = actions && action ? actions[action] : void 0;
       if (actionHandler)
         y = actionHandler(y);
       return y == null ? "" : y;
@@ -853,10 +864,28 @@ var Novely = (() => {
     };
   };
 
+  // src/browser.ts
+  var setupBrowserVisibilityChangeListeners = ({ onChange }) => {
+    if (typeof document === "undefined")
+      return noop;
+    const onVisibilityChange = () => {
+      if (document.visibilityState === "hidden") {
+        onChange();
+      }
+    };
+    addEventListener("visibilitychange", onVisibilityChange);
+    addEventListener("beforeunload", onChange);
+    return () => {
+      removeEventListener("visibilitychange", onVisibilityChange);
+      removeEventListener("beforeunload", onChange);
+    };
+  };
+
   // src/novely.ts
   var import_p_limit = __toESM(require_p_limit(), 1);
   var novely = ({
     characters,
+    defaultEmotions = {},
     storage = localStorageStorage({ key: "novely-game-storage" }),
     storageDelay = Promise.resolve(),
     renderer: createRenderer,
@@ -873,7 +902,8 @@ var Novely = (() => {
     preloadAssets = "lazy",
     parallelAssetsDownloadLimit = 15,
     fetch: request = fetch,
-    saveOnUnload = true
+    saveOnUnload = true,
+    startKey = "start"
   }) => {
     const languages = Object.keys(translation);
     const limitScript = (0, import_p_limit.default)(1);
@@ -969,7 +999,7 @@ var Novely = (() => {
     const getDefaultSave = (state = {}) => {
       return [
         [
-          ["jump", "start"],
+          ["jump", startKey],
           [null, 0]
         ],
         state,
@@ -1037,13 +1067,9 @@ var Novely = (() => {
     };
     storageDelay.then(getStoredData);
     const initial = getDefaultSave(klona(defaultState));
-    const onVisibilityChange = () => {
-      if (document.visibilityState === "hidden") {
-        throttledEmergencyOnStorageDataChange();
-      }
-    };
-    addEventListener("visibilitychange", onVisibilityChange);
-    addEventListener("beforeunload", throttledEmergencyOnStorageDataChange);
+    const unsubscribeFromBrowserVisibilityChange = setupBrowserVisibilityChangeListeners({
+      onChange: throttledEmergencyOnStorageDataChange
+    });
     const save = (type) => {
       if (!coreData.get().dataLoaded)
         return;
@@ -1097,6 +1123,12 @@ var Novely = (() => {
     };
     let interacted = 0;
     const restore = async (save2) => {
+      if (isEmpty(story)) {
+        if (DEV) {
+          throw new Error("Story is empty. You should call an `enine.script` function [https://novely.pages.dev/guide/story.html]");
+        }
+        return;
+      }
       if (!coreData.get().dataLoaded)
         return;
       let latest = save2 || storageData.get().saves.at(-1);
@@ -1206,20 +1238,26 @@ var Novely = (() => {
     };
     const back = async () => {
       const stack = useStack(MAIN_CONTEXT_KEY);
+      const valueBeforeBack = stack.value;
       stack.back();
+      if (dequal(valueBeforeBack, stack.value) && !stack.previous) {
+        return;
+      }
       await restore(stack.value);
     };
     const t = (key, lang) => {
       return translation[lang].internal[key];
     };
     const preview = async (save2, name) => {
+      if (isEmpty(story))
+        return;
       const [path, data2] = save2;
       const { queue } = getActionsFromPath(story, path, true);
       const ctx = renderer.getContext(name);
       ctx.meta.restoring = true;
       ctx.meta.preview = true;
       const processor = createQueueProcessor(queue, {
-        skip: /* @__PURE__ */ new Set()
+        skip: EMPTY_SET
       });
       useStack(ctx).push(klona(save2));
       await processor.run(([action2, ...props]) => {
@@ -1255,6 +1293,13 @@ var Novely = (() => {
       };
       return state;
     };
+    const getLanguageDisplayName = (lang) => {
+      const language = translation[lang];
+      if (DEV && !language) {
+        throw new Error(`Attempt to use unsupported language "${language}". Supported languages: ${languages.join(", ")}.`);
+      }
+      return capitalize(language.nameOverride || getIntlLanguageDisplayName(lang));
+    };
     const renderer = createRenderer({
       mainContextKey: MAIN_CONTEXT_KEY,
       characters,
@@ -1270,7 +1315,8 @@ var Novely = (() => {
       getStateFunction,
       languages,
       storageData,
-      coreData
+      coreData,
+      getLanguageDisplayName
     });
     const useStack = createUseStackFunction(renderer);
     useStack(MAIN_CONTEXT_KEY).push(initial);
@@ -1357,6 +1403,12 @@ var Novely = (() => {
         push();
       },
       showCharacter({ ctx, push }, [character, emotion, className, style]) {
+        emotion ??= defaultEmotions[character];
+        if (DEV && !emotion) {
+          throw new Error(`Attemp to show character "${character}" without emotion provided.`);
+        }
+        if (!emotion)
+          return;
         if (DEV && !characters[character].emotions[emotion]) {
           throw new Error(`Attempt to show character "${character}" with unknown emotion "${emotion}"`);
         }
@@ -1494,11 +1546,7 @@ var Novely = (() => {
       end({ ctx }) {
         if (ctx.meta.preview)
           return;
-        ctx.vibrate(0);
-        ctx.clear(EMPTY_SET, EMPTY_SET, { music: EMPTY_SET, sounds: EMPTY_SET }, noop);
-        renderer.ui.showScreen("mainmenu");
-        interactivity(false);
-        times.clear();
+        exit(true);
       },
       input({ ctx, data: data2, forward }, [question, onInput, setup]) {
         ctx.input(
@@ -1622,6 +1670,11 @@ var Novely = (() => {
           ctx,
           data: stack.value[1]
         });
+      } else if (Object.values(story).some((branch) => branch === referred)) {
+        match("end", [], {
+          ctx,
+          data: stack.value[1]
+        });
       } else {
         match("exit", [], {
           ctx,
@@ -1633,14 +1686,10 @@ var Novely = (() => {
       interacted = value ? interacted + 1 : 0;
     };
     const templateReplace = (content, values) => {
-      const {
-        data: data2,
-        meta: [lang]
-      } = storageData.get();
+      const { data: data2, meta: [lang] } = storageData.get();
       const obj = values || data2;
-      const cnt = isFunction(content) ? content(obj) : typeof content === "string" ? content : content[lang];
       const str2 = flattenAllowedContent(
-        isFunction(cnt) ? cnt(obj) : cnt,
+        !isFunction(content) && !isString(content) ? content[lang] : content,
         obj
       );
       const t2 = translation[lang];
@@ -1740,8 +1789,7 @@ var Novely = (() => {
       destroy() {
         dataLoaded.cancel();
         UIInstance.unmount();
-        removeEventListener("visibilitychange", onVisibilityChange);
-        removeEventListener("beforeunload", throttledEmergencyOnStorageDataChange);
+        unsubscribeFromBrowserVisibilityChange();
       }
     };
   };