@novely/core 0.24.0 → 0.25.0

package/dist/index.d.ts

@@ -17,7 +17,7 @@ declare const localStorageStorage: (options: LocalStorageStorageSettings) => Sto
 
 type PluralType = Intl.LDMLPluralRule;
 type Pluralization = Partial<Record<PluralType, string>>;
-type AllowedContent = string | (() => string | string[]) | string[] | (string | (() => string | string[]))[];
+type AllowedContent = string | ((state: State) => string | string[]) | string[] | (string | ((state: State) => string | string[]))[];
 type TranslationActions = Partial<Record<string, (str: string) => string>>;
 
 declare const RU: {
@@ -138,14 +138,14 @@ type Renderer = {
         character: (character: string) => CharacterHandle;
         background: (background: string | BackgroundImage) => void;
         dialog: (content: string, name: string, character: string | undefined, emotion: string | undefined, resolve: () => void) => void;
-        choices: (question: string, choices: ([string, ValidAction[]] | [string, ValidAction[], () => boolean])[], resolve: (selected: number) => void) => void;
-        input: (question: string, onInput: (meta: ActionInputOnInputMeta<string>) => void, setup: ActionInputSetup, resolve: () => void) => void;
-        clear: (keep: Set<keyof DefaultActionProxyProvider>, keepCharacters: Set<string>, keepAudio: {
+        choices: (question: string, choices: [name: string, actions: ValidAction[], active?: boolean][], resolve: (selected: number) => void) => void;
+        input: (question: string, onInput: (meta: ActionInputOnInputMeta<string, State>) => void, setup: ActionInputSetup, resolve: () => void) => void;
+        clear: (keep: Set<keyof DefaultActionProxy>, keepCharacters: Set<string>, keepAudio: {
             music: Set<string>;
             sounds: Set<string>;
         }, resolve: () => void) => void;
-        custom: (fn: Parameters<DefaultActionProxyProvider['custom']>[0], push: () => void) => Thenable<void>;
-        clearCustom: (fn: Parameters<DefaultActionProxyProvider['custom']>[0]) => void;
+        custom: (fn: Parameters<DefaultActionProxy['custom']>[0], push: () => void) => Thenable<void>;
+        clearCustom: (fn: Parameters<DefaultActionProxy['custom']>[0]) => void;
         text: (str: string, resolve: () => void) => void;
         vibrate: (pattern: VibratePattern) => void;
         audio: {
@@ -206,6 +206,7 @@ type RendererInit = {
     mainContextKey: string;
     preview: (save: Save, name: string) => Promise<void>;
     removeContext: (name: string) => void;
+    getStateFunction: (context: string) => StateFunction<State>;
 };
 
 declare const getLanguage: (languages: string[]) => string;
@@ -218,16 +219,26 @@ type Data = Record<string, any>;
 type SaveDate = number;
 type SaveType = 'manual' | 'auto';
 type SaveMeta = [date: SaveDate, type: SaveType];
-type Save = [path: Path, state: State, meta: SaveMeta];
+type Save<S extends State = State> = [
+    path: Path,
+    state: S,
+    meta: SaveMeta
+];
 type Lang = string;
 type TypewriterSpeed = 'Slow' | 'Medium' | 'Fast' | 'Auto' | (string & Record<never, never>);
 type SoundVolume = number;
-type StorageMeta = [lang: Lang, typewriter_speed: TypewriterSpeed, music_volume: SoundVolume, sound_volume: SoundVolume, voice_volume: SoundVolume];
+type StorageMeta<L extends string = string> = [
+    lang: L,
+    typewriter_speed: TypewriterSpeed,
+    music_volume: SoundVolume,
+    sound_volume: SoundVolume,
+    voice_volume: SoundVolume
+];
 type Migration = (save: unknown) => unknown;
-type StorageData = {
+type StorageData<L extends string = string, D extends Data = Data> = {
     saves: Save[];
-    data: Data;
-    meta: StorageMeta;
+    data: D;
+    meta: StorageMeta<L>;
 };
 type Stack = {
     value: Save;
@@ -383,11 +394,24 @@ interface NovelyInit<Languages extends string, Characters extends Record<string,
      * Fetching function
      */
     fetch?: typeof fetch;
+    /**
+     * When page is going to be unloaded will call `storage.set` method
+     * If 'prod' is passed enable only in production env.
+     * @default true
+     */
+    saveOnUnload?: boolean | 'prod';
 }
+type StateFunction<S extends State> = {
+    (value: DeepPartial<S> | ((prev: S) => S)): void;
+    (): S;
+};
 
-type ValidAction = ['choice', [number]] | ['clear', [Set<keyof DefaultActionProxyProvider>?, Set<string>?]] | ['condition', [() => boolean, Record<string, ValidAction[]>]] | ['dialog', [string | undefined, Unwrappable<string>, string | undefined]] | ['end', []] | ['showBackground', [string | NonEmptyRecord<BackgroundImage>]] | ['playMusic', [string]] | ['stopMusic', [string]] | ['voice', [string]] | ['stopVoice', []] | ['jump', [string]] | ['showCharacter', [string, keyof Character['emotions'], string?, string?]] | ['hideCharacter', [string, string?, string?, number?]] | ['animateCharacter', [string, number, ...string[]]] | ['wait', [FunctionableValue<number>]] | ['function', [() => Thenable<void>]] | ['input', [string, (meta: ActionInputOnInputMeta<string>) => void, ActionInputSetup?]] | ['custom', [CustomHandler]] | ['vibrate', [...number[]]] | ['next', []] | ['text', [...string[]]] | ['exit', []] | ['preload', [string]] | ['block', [string]] | ValidAction[];
+type ValidAction = ['choice', number] | ['clear', Set<keyof DefaultActionProxy>?, Set<string>?, {
+    music: Set<string>;
+    sounds: Set<string>;
+}?] | ['condition', (state: State) => boolean, Record<string, ValidAction[]>] | ['dialog', string | undefined, TextContent<string, State>, string | undefined] | ['say', string, TextContent<string, State>] | ['end'] | ['showBackground', string | NonEmptyRecord<BackgroundImage>] | ['playMusic', string] | ['stopMusic', string] | ['playSound', audio: string, loop?: boolean] | ['voice', string] | ['stopVoice'] | ['jump', string] | ['showCharacter', string, keyof Character['emotions'], string?, string?] | ['hideCharacter', string, string?, string?, number?] | ['animateCharacter', string, number, ...string[]] | ['wait', (number | ((state: State) => number))] | ['function', FunctionAction<string, State>] | ['input', string, (meta: ActionInputOnInputMeta<string, State>) => void, ActionInputSetup?] | ['custom', CustomHandler<string, State>] | ['vibrate', ...number[]] | ['next'] | ['text', ...TextContent<string, State>[]] | ['exit'] | ['preload', string] | ['block', string] | ValidAction[];
 type Story = Record<string, ValidAction[]>;
-type Unwrappable<L extends string> = string | (() => string) | Record<L, string | (() => string)>;
+type TextContent<L extends string, S extends State> = string | ((state: S) => string) | Record<L, string | ((state: S) => string)>;
 type FunctionableValue<T> = T | (() => T);
 type CustomHandlerGetResultDataFunction = {
     (data?: Record<string, unknown>): Record<string, unknown>;
@@ -412,21 +436,22 @@ type CustomHandlerGetResult<I extends boolean> = {
     clear: (fn: () => void) => void;
 };
 type CustomHandlerFunctionGetFn = <I extends boolean = true>(insert?: I) => CustomHandlerGetResult<I>;
-type CustomHandlerFunctionParameters = {
+type CustomHandlerFunctionParameters<L extends string, S extends State> = {
     get: CustomHandlerFunctionGetFn;
+    state: StateFunction<S>;
     goingBack: boolean;
     preview: boolean;
-    lang: string;
+    lang: L;
 };
-type CustomHandlerFunction = (parameters: CustomHandlerFunctionParameters) => Thenable<void>;
-type CustomHandler = CustomHandlerFunction & {
+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> & {
     callOnlyLatest?: boolean;
     requireUserAction?: boolean;
     skipClearOnGoingBack?: boolean;
     id?: string | symbol;
     key: string;
 };
-interface ActionInputOnInputMeta<L extends string> {
+interface ActionInputOnInputMeta<L extends string, S extends State> {
     /**
      * Input Element itself
      */
@@ -450,25 +475,57 @@ interface ActionInputOnInputMeta<L extends string> {
      * Language
      */
     lang: L;
+    /**
+     * State function
+     */
+    state: StateFunction<S>;
 }
+type FunctionActionProps<L extends string, S extends State> = {
+    restoring: boolean;
+    goingBack: boolean;
+    preview: boolean;
+    /**
+     * Language
+     */
+    lang: L;
+    /**
+     * State function
+     */
+    state: StateFunction<S>;
+};
+type ChoiceCheckFunctionProps<L extends string, S extends State> = {
+    /**
+     * Language
+     */
+    lang: L;
+    /**
+     * State
+     */
+    state: S;
+};
+type ChoiceCheckFunction<L extends string, S extends State> = {
+    (props: ChoiceCheckFunctionProps<L, S>): boolean;
+};
+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 ActionProxyProvider<Characters extends Record<string, Character>, Languages extends string> = {
+type ActionProxy<Characters extends Record<string, Character>, Languages extends string, S extends State> = {
     choice: {
-        (...choices: ([Unwrappable<Languages>, ValidAction[]] | [Unwrappable<Languages>, ValidAction[], () => boolean])[]): ValidAction;
-        (question: Unwrappable<Languages>, ...choices: ([Unwrappable<Languages>, ValidAction[]] | [Unwrappable<Languages>, ValidAction[], () => boolean])[]): ValidAction;
+        (...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;
     };
-    clear: (keep?: Set<keyof DefaultActionProxyProvider>, keepCharacters?: Set<string>, keepAudio?: {
+    clear: (keep?: Set<keyof DefaultActionProxy>, keepCharacters?: Set<string>, keepAudio?: {
         music: Set<string>;
         sounds: Set<string>;
     }) => ValidAction;
-    condition: <T extends string | true | false>(condition: () => T, variants: Record<T extends true ? 'true' : T extends false ? 'false' : T, ValidAction[]>) => ValidAction;
+    condition: <T extends string | true | false>(condition: (state: S) => T, variants: Record<T extends true ? 'true' : T extends false ? 'false' : T, ValidAction[]>) => ValidAction;
     exit: () => ValidAction;
     dialog: {
-        <C extends keyof Characters>(person: C, content: Unwrappable<Languages>, emotion?: keyof Characters[C]['emotions']): ValidAction;
-        (person: undefined, content: Unwrappable<Languages>, emotion?: undefined): ValidAction;
-        (person: string, content: Unwrappable<Languages>, emotion?: undefined): ValidAction;
+        <C extends keyof Characters>(character: C, content: TextContent<Languages, S>, emotion?: keyof Characters[C]['emotions']): ValidAction;
+        (character: undefined, content: TextContent<Languages, S>, emotion?: undefined): ValidAction;
+        (character: string, content: TextContent<Languages, S>, emotion?: undefined): ValidAction;
     };
+    say: (character: keyof Characters, content: TextContent<Languages, S>) => ValidAction;
     end: () => ValidAction;
     showBackground: <T extends string | BackgroundImage>(background: T extends string ? T : T extends Record<PropertyKey, unknown> ? NonEmptyRecord<T> : never) => ValidAction;
     playMusic: (audio: string) => ValidAction;
@@ -489,46 +546,84 @@ type ActionProxyProvider<Characters extends Record<string, Character>, Languages
     };
     hideCharacter: (character: keyof Characters, className?: string, style?: string, duration?: number) => ValidAction;
     animateCharacter: (character: keyof Characters, timeout: number, ...classes: string[]) => ValidAction;
-    wait: (time: FunctionableValue<number>) => ValidAction;
-    function: (fn: (restoring: boolean, goingBack: boolean, preview: boolean) => Thenable<void>) => ValidAction;
-    input: (question: Unwrappable<Languages>, onInput: (meta: ActionInputOnInputMeta<Languages>) => void, setup?: ActionInputSetup) => ValidAction;
-    custom: (handler: CustomHandler) => ValidAction;
+    wait: (time: number | ((state: State) => number)) => ValidAction;
+    function: (fn: FunctionAction<Languages, S>) => ValidAction;
+    input: (question: TextContent<Languages, S>, onInput: (meta: ActionInputOnInputMeta<Languages, S>) => void, setup?: ActionInputSetup) => ValidAction;
+    custom: (handler: CustomHandler<Languages, S> | CustomHandler) => ValidAction;
     vibrate: (...pattern: number[]) => ValidAction;
     next: () => ValidAction;
-    text: (...text: Unwrappable<Languages>[]) => ValidAction;
+    text: (...text: TextContent<Languages, S>[]) => ValidAction;
     preload: (source: string) => ValidAction;
     block: (scene: string) => ValidAction;
 };
-type DefaultActionProxyProvider = ActionProxyProvider<Record<string, Character>, string>;
-type GetActionParameters<T extends Capitalize<keyof DefaultActionProxyProvider>> = Parameters<DefaultActionProxyProvider[Uncapitalize<T>]>;
+type DefaultActionProxy = ActionProxy<Record<string, Character>, string, 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 }: NovelyInit<Languages, Characters, StateScheme, DataScheme>) => {
+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>) => {
     /**
      * Function to set game script
+     *
+     * @example
+     * ```ts
+     * engine.script({
+     *   start: [
+     *     action.function(() => {})
+     *   ]
+     * })
+     * ```
      */
     script: (part: Story) => Promise<void>;
     /**
-     * Function to get actions
+     * Get actions
+     *
+     * @example
+     * ```ts
+     * engine.script({
+     *   start: [
+     *     action.function(() => {})
+     *   ]
+     * })
+     * ```
      */
-    action: ActionProxyProvider<Characters, Languages>;
+    action: ActionProxy<Characters, Languages, StateScheme>;
     /**
-     * State that belongs to games
+     * @deprecated Will be removed BUT replaced with state passed into actions as a parameter
      */
-    state: {
-        (value: DeepPartial<StateScheme> | ((prev: StateScheme) => StateScheme)): void;
-        (): StateScheme;
-    };
+    state: StateFunction<State>;
+    /**
+     * Store data between games
+     *
+     * @example
+     * ```ts
+     * engine.script({
+     *   start: [
+     *     action.function(() => {
+     *       // Paid content should be purchased only once
+     *       // So it will be available in any save
+     *       data({ paid_content_purchased: true })
+     *     })
+     *   ]
+     * })
+     * ```
+     */
+    data: StateFunction<DataScheme>;
     /**
-     * Unlike `state`, stored at global scope instead and shared between games
+     * @deprecated Renamed into `templateReplace`
      */
-    data: {
-        (value: DeepPartial<DataScheme> | ((prev: DataScheme) => DataScheme)): void;
-        (): DataScheme;
-    };
+    unwrap(content: TextContent<Languages, DataScheme>): string;
     /**
-     * Unwraps translatable content to a string value
+     * Replaces content inside {{braces}} with using global data
+     * @example
+     * ```ts
+     * data({ name: 'Alexei' })
+     *
+     * templateReplace('{{name}} is our hero')
+     * templateReplace({
+     *  en: (data) => 'Hello, ' + data.name
+     * })
+     * ```
      */
-    unwrap(content: string | (() => string) | Exclude<Record<Languages, string | (() => string)>, Record<string, string>> | Record<Languages, string>): string;
+    templateReplace(content: TextContent<Languages, DataScheme>): string;
     /**
      * Cancel data loading, hide UI, ignore page change events
      * Data updates still will work in case Novely already was loaded
@@ -536,4 +631,4 @@ declare const novely: <Languages extends string, Characters extends Record<strin
     destroy(): void;
 };
 
-export { type ActionProxyProvider, type AllowedContent, type AudioHandle, type BaseTranslationStrings, type Character, type CharacterHandle, type Context, type CoreData, type CustomHandler, type CustomHandlerFunctionGetFn, type CustomHandlerFunctionParameters, type CustomHandlerGetResult, type CustomHandlerGetResultDataFunction, type DefaultActionProxyProvider, 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 Storage, type StorageData, type StorageMeta, type Stored, type Story, type Thenable, type TranslationActions, type TypewriterSpeed, type Unwrappable, type ValidAction, localStorageStorage, novely };
+export { type ActionProxy, type AllowedContent, type AudioHandle, type BaseTranslationStrings, type Character, type CharacterHandle, type Context, type CoreData, type CustomHandler, type CustomHandlerFunctionGetFn, type CustomHandlerFunctionParameters, type CustomHandlerGetResult, type CustomHandlerGetResultDataFunction, 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 Storage, type StorageData, type StorageMeta, type Stored, type Story, type TextContent, type Thenable, type TranslationActions, type TypewriterSpeed, type ValidAction, localStorageStorage, novely };