@drincs/pixi-vn 1.8.25 → 1.9.1

package/dist/narration.d.cts

@@ -1,14 +1,156 @@
 import { S as StorageElementType, a as StorageObjectType } from './StorageElementType-C7ETezlL.cjs';
-import { L as LabelIdType, D as DialogueInterface, H as HistoryStep } from './HistoryStep-G9dUn0Lf.cjs';
-export { P as PixivnLabelIds } from './HistoryStep-G9dUn0Lf.cjs';
+import { L as LabelIdType, D as DialogueInterface, H as HistoryStep } from './HistoryStep-WGB6nA4N.cjs';
+export { P as PixivnLabelIds } from './HistoryStep-WGB6nA4N.cjs';
 import { ChoiceInterface as ChoiceInterface$1 } from '@drincs/pixi-vn';
-import { L as LabelRunModeType, C as CloseType } from './HistoryChoiceMenuOption-DVMD78W7.cjs';
-export { H as HistoryChoiceMenuOption, N as NarrationHistory } from './HistoryChoiceMenuOption-DVMD78W7.cjs';
+import { L as LabelRunModeType, C as CloseType } from './HistoryChoiceMenuOption-BxMSXnyI.cjs';
+export { H as HistoryChoiceMenuOption, N as NarrationHistory } from './HistoryChoiceMenuOption-BxMSXnyI.cjs';
 import { S as StepLabelPropsType, a as StepLabelResultType, b as StepLabelType } from './StepLabelType-CN97wZzm.cjs';
-import { O as OpenedLabel } from './OpenedLabel-BxfL31aQ.cjs';
+import { O as OpenedLabel } from './OpenedLabel-Cmd675NI.cjs';
 import { LabelProps as LabelProps$1 } from '@drincs/pixi-vn/canvas';
 import 'microdiff';
 
+interface ChoiceOptionInterface extends Omit<ChoiceInterface$1, "label" | "type" | "closeCurrentLabel"> {
+    /**
+     * Label Id to be opened when the option is selected
+     */
+    label: LabelIdType;
+    /**
+     * Type of the label to be opened
+     */
+    type: LabelRunModeType;
+}
+interface CloseChoiceOptionInterface extends Omit<ChoiceInterface$1, "label" | "type" | "closeCurrentLabel"> {
+    /**
+     * Type of the label to be opened
+     */
+    type: CloseType;
+    /**
+     * If true, the current label will be closed
+     */
+    closeCurrentLabel?: boolean;
+}
+type StoredChoiceInterface = ChoiceOptionInterface | CloseChoiceOptionInterface;
+type StoredIndexedChoiceInterface = StoredChoiceInterface & {
+    /**
+     * Is the index of the choice in the menu. It is used to identify the choice when it is selected.
+     */
+    choiceIndex: number;
+};
+
+interface NarrationChoicesInterface {
+    /**
+     * The choices to be shown in the game.
+     */
+    get list(): StoredIndexedChoiceInterface[] | undefined;
+    /**
+     * The choices to be shown in the game.
+     * @throws {PixiError} when a choice contains functions or class instances that cannot be serialized to JSON.
+     */
+    set list(data: StoredChoiceInterface[] | undefined);
+    /**
+     * Select a choice from the choice menu, and close the choice menu.
+     * @param item The choice item selected by the player.
+     * @param props The props to pass to the label.
+     * @returns StepLabelResultType or undefined.
+     * @throws {PixiError} when the choice type is not `"call"`, `"jump"`, or `"close"`.
+     * @example
+     * ```ts
+     * narration.choices.select(item, {
+     *     navigate: navigate,
+     *     // your props
+     *     ...item.props
+     * })
+     *     .then(() => {
+     *         // your code
+     *     })
+     *     .catch((e) => {
+     *         // your code
+     *     })
+     * ```
+     */
+    select<T extends {}>(item: StoredIndexedChoiceInterface, props: StepLabelPropsType<T>): Promise<StepLabelResultType>;
+}
+
+type InputInfo = {
+    isRequired?: boolean;
+    type?: string;
+};
+
+interface NarrationInputInterface {
+    /**
+     * The input value to be inserted by the player.
+     */
+    value: StorageElementType;
+    /**
+     * If true, the player must enter a value.
+     */
+    readonly isRequired: boolean;
+    /**
+     * Returns the type of input prompt requested.
+     */
+    readonly type: string | undefined;
+    /**
+     * Returns `true` if the player must enter a value.
+     * @param info The input value to be inserted by the player.
+     * @param defaultValue The default value to be inserted.
+     */
+    request(info?: Omit<InputInfo, "isRequired">, defaultValue?: StorageElementType): void;
+    /**
+     * Remove the input request.
+     */
+    removeRequest(): void;
+}
+
+interface NarrationLabelsInterface {
+    /**
+     * The stack of the opened labels.
+     */
+    readonly opened: OpenedLabel[];
+    /**
+     * currentLabel is the current label that occurred during the progression of the steps.
+     */
+    readonly current: LabelAbstract<any> | undefined;
+    /**
+     * Close the current label and add it to the history.
+     */
+    closeCurrent(): void;
+    /**
+     * Close all labels and add them to the history. **Attention: This method can cause an unhandled game ending.**
+     */
+    closeAll(): void;
+}
+
+interface NarrationQueriesInterface {
+    /**
+     * Check if the label is already completed.
+     * @param label The label to check.
+     * @returns True if the label is already completed.
+     */
+    isLabelAlreadyCompleted(label: LabelIdType | LabelAbstract<any>): boolean;
+    /**
+     * Get the choices already made in the current step. **Attention**: if the choice step index is edited or the code of choice step is edited, the result will be wrong.
+     * @returns The choices already made in the current step. If there are no choices, it will return undefined.
+     */
+    readonly alreadyCurrentStepMadeChoices: number[] | undefined;
+    /**
+     * Check if the current step is already completed.
+     * @returns True if the current step is already completed.
+     */
+    readonly isCurrentStepAlreadyOpened: boolean;
+    /**
+     * Get times a label has been opened.
+     * @param label The label to check.
+     * @returns times a label has been opened.
+     */
+    timesLabelOpened(label: LabelIdType): number;
+    /**
+     * Get times a choice has been made in the current step.
+     * @param index The index of the choice.
+     * @returns The number of times the choice has been made.
+     */
+    timesChoiceMade(index: number): number;
+}
+
 interface NarrationManagerInterface {
     /**
      * Counter of execution times of the current step. Current execution is also included. Starts from 1.
@@ -43,52 +185,73 @@ interface NarrationManagerInterface {
     readonly stepCounter: number;
     /**
      * The stack of the opened labels.
+     * @deprecated Use {@link labels}.opened instead.
      */
     readonly openedLabels: OpenedLabel[];
     /**
      * currentLabel is the current label that occurred during the progression of the steps.
+     * @deprecated Use {@link labels}.current instead.
      */
     readonly currentLabel: LabelAbstract<any> | undefined;
     /**
      * Close the current label and add it to the history.
      * @returns
+     * @deprecated Use {@link labels}.closeCurrent instead.
      */
     closeCurrentLabel(): void;
     /**
      * Close all labels and add them to the history. **Attention: This method can cause an unhandled game ending.**
+     * @deprecated Use {@link labels}.closeAll instead.
      */
     closeAllLabels(): void;
     /**
      * Check if the label is already completed.
      * @param label The label to check.
      * @returns True if the label is already completed.
+     * @deprecated Use {@link queries}.isLabelAlreadyCompleted instead.
      */
     isLabelAlreadyCompleted(label: LabelIdType | LabelAbstract<any>): boolean;
     /**
      * Get the choices already made in the current step. **Attention**: if the choice step index is edited or the code of choice step is edited, the result will be wrong.
      * @returns The choices already made in the current step. If there are no choices, it will return undefined.
+     * @deprecated Use {@link queries}.alreadyCurrentStepMadeChoices instead.
      */
     readonly alreadyCurrentStepMadeChoices: number[] | undefined;
     /**
      * Check if the current step is already completed.
      * @returns True if the current step is already completed.
+     * @deprecated Use {@link queries}.isCurrentStepAlreadyOpened instead.
      */
     readonly isCurrentStepAlreadyOpened: boolean;
     /**
      * Get times a label has been opened
      * @returns times a label has been opened
+     * @deprecated Use {@link queries}.timesLabelOpened instead.
      */
     getTimesLabelOpened(label: LabelIdType): number;
     /**
      * Get times a choice has been made in the current step.
      * @param index The index of the choice.
      * @returns The number of times the choice has been made.
+     * @deprecated Use {@link queries}.timesChoiceMade instead.
      */
     getTimesChoiceMade(index: number): number;
     /**
      * Save the current step to the history.
      */
     addCurrentStepToHistory(): void;
+    /**
+     * Namespace for operations on the input requested to the player.
+     */
+    readonly input: NarrationInputInterface;
+    /**
+     * Namespace for operations on the opened labels.
+     */
+    readonly labels: NarrationLabelsInterface;
+    /**
+     * Namespace for queries about the current state of the narration.
+     */
+    readonly queries: NarrationQueriesInterface;
     /**
      * Return if can go to the next step. It's `false` when:
      * - A `step` is running
@@ -200,6 +363,7 @@ interface NarrationManagerInterface {
      *         // your code
      *     })
      * ```
+     * @deprecated Use {@link choices}.select instead.
      */
     selectChoice<T extends {}>(item: StoredIndexedChoiceInterface, props: StepLabelPropsType<T>): Promise<StepLabelResultType>;
     /** Old Step Methods */
@@ -213,21 +377,11 @@ interface NarrationManagerInterface {
      */
     set dialogue(props: DialogueInterface | string | string[] | undefined);
     /**
-     * The options to be shown in the game
-     * @example
-     * ```ts
-     * narration.choices = [
-     *     newChoiceOption("Events Test", EventsTestLabel, {}),
-     *     newChoiceOption("Show Image Test", ShowImageTest, { image: "imageId" }, "call"),
-     *     newChoiceOption("Ticker Test", TickerTestLabel, {}),
-     *     newChoiceOption("Tinting Test", TintingTestLabel, {}, "jump"),
-     *     newChoiceOption("Base Canvas Element Test", BaseCanvasElementTestLabel, {})
-     * ]
-     * ```
+     * Namespace for operations on the choices to be shown in the game.
      */
-    get choices(): StoredIndexedChoiceInterface[] | undefined;
+    get choices(): NarrationChoicesInterface;
     /**
-     * The options to be shown in the game
+     * Shortcut for {@link NarrationChoicesInterface.list}.
      * @throws {PixiError} when a choice contains functions or class instances that cannot be serialized to JSON.
      * @example
      * ```ts
@@ -247,24 +401,29 @@ interface NarrationManagerInterface {
     dialogGlue: boolean;
     /**
      * The input value to be inserted by the player.
+     * @deprecated Use {@link input}.value instead.
      */
     inputValue: StorageElementType;
     /**
      * If true, the player must enter a value.
+     * @deprecated Use {@link input}.isRequired instead.
      */
     readonly isRequiredInput: boolean;
     /**
      * Returns the type of input prompt requested.
+     * @deprecated Use {@link input}.type instead.
      */
     readonly inputType: string | undefined;
     /**
      * Returns `true` if the player must enter a value.
      * @param info The input value to be inserted by the player.
      * @param defaultValue The default value to be inserted.
+     * @deprecated Use {@link input}.request instead.
      */
     requestInput(info?: Omit<InputInfo, "isRequired">, defaultValue?: StorageElementType): void;
     /**
      * Remove the input request.
+     * @deprecated Use {@link input}.removeRequest instead.
      */
     removeInputRequest(): void;
     /**
@@ -283,34 +442,6 @@ interface NarrationManagerInterface {
     restore(data: object, lastHistoryStep: Omit<HistoryStep, "diff"> | null): Promise<void>;
 }
 
-interface ChoiceOptionInterface extends Omit<ChoiceInterface$1, "label" | "type" | "closeCurrentLabel"> {
-    /**
-     * Label Id to be opened when the option is selected
-     */
-    label: LabelIdType;
-    /**
-     * Type of the label to be opened
-     */
-    type: LabelRunModeType;
-}
-interface CloseChoiceOptionInterface extends Omit<ChoiceInterface$1, "label" | "type" | "closeCurrentLabel"> {
-    /**
-     * Type of the label to be opened
-     */
-    type: CloseType;
-    /**
-     * If true, the current label will be closed
-     */
-    closeCurrentLabel?: boolean;
-}
-type StoredChoiceInterface = ChoiceOptionInterface | CloseChoiceOptionInterface;
-type StoredIndexedChoiceInterface = StoredChoiceInterface & {
-    /**
-     * Is the index of the choice in the menu. It is used to identify the choice when it is selected.
-     */
-    choiceIndex: number;
-};
-
 interface LabelProps<T, StepIdType = number> {
     /**
      * A function executed before each `step`.
@@ -729,13 +860,26 @@ declare class NarrationManagerStatic {
         closeCurrentLabel?: boolean;
         type: string;
     }, defaultStart: () => Promise<StepLabelResultType>) => StepLabelResultType | Promise<StepLabelResultType>;
+    /**
+     * Is a function that will be executed every time the current label is about to close because it
+     * naturally ran out of steps - either control is returning to the label that called it, or, if
+     * there's no parent label left on the stack, the game is about to end (see {@link Game.onEnd}).
+     *
+     * By default (when this is not set), the label is closed immediately, exactly like before this
+     * hook existed. If you set it, you take control: call `defaultClose()` yourself whenever you want
+     * the label to actually close (right away, or later, e.g. from a subsequent `next()`-like action in
+     * your template). Until `defaultClose()` is called, the label stays open: it is not popped off the
+     * opened labels stack, narration does not continue into the parent label, and the game does not end
+     * even if this was the last label - this is what lets an app show the final paragraph of a story
+     * before actually ending it, instead of both happening within the same `continue()` call.
+     *
+     * This does not fire for a `jump` or a choice's `closeCurrentLabel` option - those close the
+     * current label explicitly as part of starting a new one, so {@link onLabelStarting} already
+     * covers deferring them.
+     */
+    static onLabelClosing?: (labelId: LabelIdType, props: StepLabelPropsType, defaultClose: () => Promise<StepLabelResultType>) => StepLabelResultType | Promise<StepLabelResultType>;
 }
 
-type InputInfo = {
-    isRequired?: boolean;
-    type?: string;
-};
-
 declare const narration: NarrationManagerInterface;
 
-export { type ChoiceInterface, type ChoiceOptionInterface, type CloseChoiceOptionInterface, DialogueInterface, HistoryStep, type InputInfo, Label, LabelAbstract, LabelIdType, type LabelProps, LabelRunModeType, type LabelSteps, type NarrationGameState, type NarrationManagerInterface, NarrationManagerStatic, OpenedLabel, RegisteredLabels, type StepLabelProps, StepLabelPropsType, type StepLabelResult, StepLabelResultType, StepLabelType, type StoredChoiceInterface, type StoredIndexedChoiceInterface, narration, newChoiceOption, newCloseChoiceOption, newLabel };
+export { type ChoiceInterface, type ChoiceOptionInterface, type CloseChoiceOptionInterface, DialogueInterface, HistoryStep, type InputInfo, Label, LabelAbstract, LabelIdType, type LabelProps, LabelRunModeType, type LabelSteps, type NarrationChoicesInterface, type NarrationGameState, type NarrationInputInterface, type NarrationLabelsInterface, type NarrationManagerInterface, NarrationManagerStatic, type NarrationQueriesInterface, OpenedLabel, RegisteredLabels, type StepLabelProps, StepLabelPropsType, type StepLabelResult, StepLabelResultType, StepLabelType, type StoredChoiceInterface, type StoredIndexedChoiceInterface, narration, newChoiceOption, newCloseChoiceOption, newLabel };