narraleaf-react 0.31.3 → 0.32.0

package/dist/game/nlcore/action/actionTypes.d.ts

@@ -21,11 +21,13 @@ export declare const DisplayableActionTypes: {
     readonly action: "displayable:action";
     readonly applyTransform: "displayable:applyTransform";
     readonly applyTransition: "displayable:applyTransition";
+    readonly applyLoop: "displayable:applyLoop";
+    readonly stopLoop: "displayable:stopLoop";
     readonly init: "displayable:init";
     readonly bringToFront: "displayable:bringToFront";
 };
 export type DisplayableActionContentType<TransitionType extends Transition = Transition> = {
-    [K in typeof DisplayableActionTypes[keyof typeof DisplayableActionTypes]]: K extends "displayable:applyTransform" ? [Transform] : K extends "displayable:applyTransition" ? [TransitionType, ((transition: TransitionType) => TransitionType)?] : K extends "displayable:init" ? [scene: Scene | null, layer: Layer | null, isElement?: boolean] : K extends "displayable:bringToFront" ? [] : any;
+    [K in typeof DisplayableActionTypes[keyof typeof DisplayableActionTypes]]: K extends "displayable:applyTransform" ? [Transform] : K extends "displayable:applyTransition" ? [TransitionType, ((transition: TransitionType) => TransitionType)?] : K extends "displayable:applyLoop" ? [Transform, TransformDefinitions.LoopOptions?] : K extends "displayable:stopLoop" ? [TransformDefinitions.LoopStopOptions?] : K extends "displayable:init" ? [scene: Scene | null, layer: Layer | null, isElement?: boolean] : K extends "displayable:bringToFront" ? [] : any;
 };
 export declare const CharacterActionTypes: {
     readonly say: "character:say";

package/dist/game/nlcore/action/actions/displayableAction.d.ts

@@ -11,16 +11,44 @@ import { Layer } from "../../elements/layer";
 import { LogicAction } from "../../action/logicAction";
 import { ActionExecutionInjection, ExecutedActionResult } from "../../action/action";
 import { Story } from "../../elements/story";
+import type { TransformDefinitions } from "../../elements/transform/type";
 export declare class DisplayableAction<T extends Values<typeof DisplayableActionTypes> = Values<typeof DisplayableActionTypes>, Self extends Displayable<any, any, any> = Displayable<any, any>, TransitionType extends Transition = Transition> extends TypedAction<DisplayableActionContentType<TransitionType>, T, Self> {
     static ActionTypes: {
         readonly action: "displayable:action";
         readonly applyTransform: "displayable:applyTransform";
         readonly applyTransition: "displayable:applyTransition";
+        readonly applyLoop: "displayable:applyLoop";
+        readonly stopLoop: "displayable:stopLoop";
         readonly init: "displayable:init";
         readonly bringToFront: "displayable:bringToFront";
     };
     executeAction(gameState: GameState, injection: ActionExecutionInjection): ExecutedActionResult;
     applyTransform(state: GameState, element: Displayable<any, any>, transform: Transform, injection: ActionExecutionInjection, onFinished?: () => void): Awaitable<CalledActionResult, CalledActionResult>;
+    /**
+     * Start a looping transform on the element, and let the story carry straight on.
+     *
+     * The one action here that resolves without waiting for anything, because there is nothing to
+     * wait for: the motion repeats until something ends it. Nothing is attached to a timeline and
+     * nothing is left unsettled on the stack — a loop is a property the element carries (see
+     * {@link Displayable.loop}), so it is the element's binding, not this action, that a save and a
+     * remount read.
+     */
+    applyLoop(state: GameState, element: Displayable<any, any>, transform: Transform, options: TransformDefinitions.LoopOptions | undefined, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
+    /**
+     * End the element's looping transform and ease it back to the pose it kept underneath.
+     *
+     * Unlike {@link DisplayableAction.applyLoop} this *is* awaited — the way back has a duration,
+     * even when that duration is zero.
+     */
+    stopLoop(state: GameState, element: Displayable<any, any>, options: TransformDefinitions.LoopStopOptions | undefined, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
+    /**
+     * Put an element's loop binding back to what it was, and make the running motion agree.
+     *
+     * Both halves are needed and neither is enough: the binding is what a save and a remount read,
+     * the motion is what the player sees. Undoing past a `loop()` has to stop a motion that is
+     * running right now; undoing past a `stopLoop()` has to start one that is not.
+     */
+    private static restoreLoop;
     applyTransition(state: GameState, element: Displayable<any, any>, transition: TransitionType, injection: ActionExecutionInjection, onFinished?: () => void): Awaitable<CalledActionResult, CalledActionResult>;
     initDisplayable(state: GameState, scene: Scene | null, element: Displayable<any, any>, layer: Layer | null, isElement: boolean | undefined, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
     /**

package/dist/game/nlcore/elements/camera.d.ts

@@ -1,6 +1,6 @@
 import { LogicAction } from "../action/logicAction";
 import { TransformDefinitions } from "../elements/transform/type";
-import { Displayable } from "../elements/displayable/displayable";
+import { Displayable, DisplayableLoopRaw } from "../elements/displayable/displayable";
 import { EventfulDisplayable } from "../../player/elements/displayable/type";
 import { Chained, Proxied } from "../action/chain";
 /**
@@ -14,6 +14,7 @@ import { Chained, Proxied } from "../action/chain";
 export type ICameraUserConfig = TransformDefinitions.CameraTransformProps;
 export type CameraDataRaw = {
     transformState: Record<string, any>;
+    loop?: DisplayableLoopRaw | null;
 };
 /**
  * A stage-wide camera.

package/dist/game/nlcore/elements/displayable/displayable.d.ts

@@ -5,6 +5,28 @@ import { LogicAction } from "../../action/logicAction";
 import { EventfulDisplayable } from "../../../player/elements/displayable/type";
 import type { TransformDefinitions } from "../../elements/transform/type";
 import type { ImageSrc } from "../../types";
+/**
+ * A looping transform as it goes into a save.
+ *
+ * The transform itself is **not** here, and cannot be: its easing may be a function, and a function
+ * does not survive a round trip through JSON. What is stored instead is the id of the action that
+ * started the loop — the transform is authored data hanging off that action's content node, so the
+ * story itself still holds it, and loading resolves the id back to it through the same action map
+ * the stack model is restored with. A save whose action the story no longer has simply loses the
+ * loop rather than failing to load.
+ *
+ * Public, unlike the rest of the loop plumbing, because every displayable's `*DataRaw` names it and
+ * those are public. An internal-tagged type reached from a public signature is deleted from the
+ * emitted declarations while the signature that uses it stays behind naming something that is no
+ * longer declared, and only the consumer's `skipLibCheck` hides the result.
+ *
+ * (Do not write that tag in prose here: `stripInternal` matches it anywhere in the comment, so
+ * merely describing the hazard is enough to cause it.)
+ */
+export type DisplayableLoopRaw = {
+    actionId: string;
+    options: TransformDefinitions.LoopOptions;
+};
 export declare abstract class Displayable<StateData extends Record<string, any>, Self extends Displayable<any, any, any>, TransformType extends TransformDefinitions.Types = TransformDefinitions.Types> extends Actionable<StateData, Self> implements EventfulDisplayable {
     /**
      * Set Image Position
@@ -179,6 +201,60 @@ export declare abstract class Displayable<StateData extends Record<string, any>,
      * ```
      */
     transform(transform: Transform<TransformType>): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Play a transform on this element over and over until something stops it.
+     *
+     * **The line does not wait.** This is the one difference from {@link Displayable.transform}, and
+     * the only one worth remembering: `transform()` is a step of the story and the next line waits
+     * for it to finish, while `loop()` is a property the element carries — it is set, the story
+     * moves on, and the motion keeps running underneath everything that follows.
+     *
+     * An element carries **one** transform at a time, so anything else applied to it takes the
+     * element back: `transform()`, `pos()`, `zoom()`, `show()`, `hide()` and the rest all end the
+     * loop and move on from wherever it had got to. What does *not* end it: the player skipping or
+     * fast-forwarding, a transition changing the picture, changing scene, or saving and loading —
+     * a loaded save puts the loop back.
+     *
+     * The pose the element had when the loop started is what it returns to, and the only thing a
+     * save records; the frames in between are never written down.
+     *
+     * The transform has to be committed, exactly as for {@link Displayable.transform} — a staged
+     * change that was never `commit()`ed is not part of it.
+     *
+     * @param transform - The motion to repeat. For anything that should not snap on each repeat,
+     * either bring it back to where it started or pass `{repeatType: "mirror"}`.
+     * @param options - See {@link TransformDefinitions.LoopOptions}.
+     * @chainable
+     * @example
+     * ```ts
+     * const breathe = Transform.create()
+     *     .scaleY(1.015)
+     *     .commit({ duration: 1900, ease: "easeInOut" });
+     *
+     * scene.action([
+     *     yuko.loop(breathe, { repeatType: "mirror" }),
+     *     yuko.say`...`,                  // plays while she keeps breathing
+     *     yuko.stopLoop({ duration: 300 }),
+     * ]);
+     * ```
+     */
+    loop(transform: Transform<TransformType>, options?: TransformDefinitions.LoopOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * End the element's looping transform and put it back to the pose it had before the loop
+     * started.
+     *
+     * Unlike {@link Displayable.loop}, this **is** something the line waits for — there is a
+     * definite end to wait for. With no duration the element is back in place on the same frame.
+     *
+     * A no-op on an element that is not looping.
+     *
+     * @chainable
+     * @example
+     * ```ts
+     * yuko.stopLoop({ duration: 300, ease: "easeOut" });
+     * ```
+     */
+    stopLoop(options?: TransformDefinitions.LoopStopOptions): Proxied<Self, Chained<LogicAction.Actions, Self>>;
     /**
      * Bring the Displayable to the front of the layer it is on.
      *

package/dist/game/nlcore/elements/displayable/image.d.ts

@@ -3,7 +3,7 @@ import { Color, ImageSrc } from "../../types";
 import { LogicAction } from "../../game";
 import { FlexibleTuple, SelectElementFromEach } from "../../../../util/data";
 import { Chained, Proxied } from "../../action/chain";
-import { Displayable } from "../../elements/displayable/displayable";
+import { Displayable, DisplayableLoopRaw } from "../../elements/displayable/displayable";
 import { EventfulDisplayable } from "../../../player/elements/displayable/type";
 import { ImageTransition } from "../../elements/transition/transitions/image/imageTransition";
 import { Layer } from "../../elements/layer";
@@ -46,6 +46,7 @@ export interface IImageUserConfig<Tag extends TagGroupDefinition | null = TagGro
 export type ImageDataRaw = {
     state: Record<string, any>;
     transformState: Record<string, any>;
+    loop?: DisplayableLoopRaw | null;
 };
 export type TagGroupDefinition = string[][];
 export type TagSrcResolver<T extends TagGroupDefinition> = (...tags: SelectElementFromEach<T>) => string;

package/dist/game/nlcore/elements/displayable/puppet.d.ts

@@ -1,5 +1,5 @@
 import type { TransformDefinitions } from "../../elements/transform/type";
-import { Displayable } from "../../elements/displayable/displayable";
+import { Displayable, DisplayableLoopRaw } from "../../elements/displayable/displayable";
 import { EventfulDisplayable } from "../../../player/elements/displayable/type";
 import { Chained, Proxied } from "../../action/chain";
 import { LogicAction } from "../../action/logicAction";
@@ -80,6 +80,7 @@ export type PuppetCommandOptions = {
 export type PuppetDataRaw = {
     state: Record<string, any>;
     transformState: Record<string, any>;
+    loop?: DisplayableLoopRaw | null;
 };
 /**
  * A displayable whose interior is drawn by a backend the host registered.

package/dist/game/nlcore/elements/displayable/text.d.ts

@@ -2,7 +2,7 @@ import { Color } from "../../types";
 import { Chained, Proxied } from "../../action/chain";
 import { LogicAction } from "../../action/logicAction";
 import type { TransformDefinitions } from "../../elements/transform/type";
-import { Displayable } from "../../elements/displayable/displayable";
+import { Displayable, DisplayableLoopRaw } from "../../elements/displayable/displayable";
 import { EventfulDisplayable } from "../../../player/elements/displayable/type";
 import { Layer } from "../../elements/layer";
 export type TextConfig = {
@@ -52,6 +52,7 @@ export interface ITextUserConfig extends TransformDefinitions.TextTransformProps
 export type TextDataRaw = {
     state: Record<string, any>;
     transformState: Record<string, any>;
+    loop?: DisplayableLoopRaw | null;
 };
 export declare class Text extends Displayable<TextDataRaw, Text, TransformDefinitions.TextTransformProps> implements EventfulDisplayable {
     constructor(config: Partial<ITextUserConfig>);

package/dist/game/nlcore/elements/layer.d.ts

@@ -1,6 +1,6 @@
 import { LogicAction } from "../action/logicAction";
 import { TransformDefinitions } from "../elements/transform/type";
-import { Displayable } from "../elements/displayable/displayable";
+import { Displayable, DisplayableLoopRaw } from "../elements/displayable/displayable";
 import { EventfulDisplayable } from "../../player/elements/displayable/type";
 import { Image } from "../elements/displayable/image";
 import { Text } from "../elements/displayable/text";
@@ -16,6 +16,7 @@ export interface ILayerUserConfig extends TransformDefinitions.ImageTransformPro
 export type LayerDataRaw = {
     state: Record<string, any>;
     transformState: Record<string, any>;
+    loop?: DisplayableLoopRaw | null;
 };
 export declare class Layer extends Displayable<LayerDataRaw, Layer, TransformDefinitions.ImageTransformProps> implements EventfulDisplayable {
     /**

package/dist/game/nlcore/elements/transform/transform.d.ts

@@ -24,6 +24,13 @@ export type TransformCompanion = {
     el: Element;
     project: (props: Partial<TransformDefinitions.Types>) => CSSProps;
 };
+/**
+ * A running looping transform. The only thing a caller can do with one is end it — see
+ * {@link Transform.startLoop}.
+ */
+export type TransformLoopHandle = {
+    stop: () => void;
+};
 /**
  * The same thing before the elements are known — what a React host holds, resolved to
  * {@link TransformCompanion} at the moment the animation is built.

package/dist/game/nlcore/elements/transform/type.d.ts

@@ -13,10 +13,50 @@ export declare namespace TransformDefinitions {
         /**@deprecated */
         sync?: boolean;
     };
+    /**
+     * How a repeat plays each time round.
+     *
+     * - `"loop"` — start over from the first pose. The jump back is instant, so a sequence that
+     *   does not return to where it began shows a snap on every repeat.
+     * - `"reverse"` — play backwards, then forwards again. No snap.
+     * - `"mirror"` — like `"reverse"`, with the easing mirrored too, so an `easeIn` going out is an
+     *   `easeOut` coming back. This is what a breathing or floating motion wants.
+     */
+    type RepeatType = "loop" | "reverse" | "mirror";
     type TransformConfig = {
         sync: boolean;
         repeat?: number;
         repeatDelay?: number;
+        repeatType?: RepeatType;
+    };
+    /**
+     * How a looping transform repeats — see {@link Displayable.loop}.
+     *
+     * There is no "how many times" here on purpose: a loop runs until something stops it. For a
+     * bounded number of repeats use `transform.repeat(n)`, which the line waits for, or
+     * `Control.repeat`.
+     *
+     * This is written into the save as-is, so everything in it has to stay plain JSON.
+     */
+    type LoopOptions = {
+        /**@default "loop" */
+        repeatType?: RepeatType;
+        /**
+         * Milliseconds to hold the last pose before the next repeat starts.
+         * @default 0
+         */
+        repeatDelay?: number;
+    };
+    /**
+     * How an element eases out of its looping transform — see {@link Displayable.stopLoop}.
+     */
+    type LoopStopOptions = {
+        /**
+         * Milliseconds spent returning to the pose the element had before the loop started.
+         * @default 0
+         */
+        duration?: number;
+        ease?: EasingDefinition;
     };
     type VisualEffectTransformProps = {
         maskImage?: React.CSSProperties["maskImage"];

package/dist/game/player/elements/type.d.ts

@@ -2,7 +2,7 @@ import React, { ErrorInfo } from "react";
 import { IDialogProps, SayElementProps } from "../elements/say/type";
 import { IUserMenuProps, MenuElementProps } from "../elements/menu/type";
 import { Story } from "../../nlcore/elements/story";
-import clsx from "clsx";
+import type { ClassValue } from "clsx";
 import { Game, type GameLifecycleEventContext } from "../../nlcore/game";
 import { GameState } from "../gameState";
 import { Storable } from "../../nlcore/elements/persistent/storable";
@@ -33,7 +33,7 @@ export interface PlayerProps {
     story?: Story;
     width?: string | number;
     height?: string | number;
-    className?: clsx.ClassValue;
+    className?: ClassValue;
     /**
      * Once the Player is initialized.
      *

package/dist/game/player/type.d.ts

@@ -3,6 +3,7 @@ import { Image } from "../nlcore/elements/displayable/image";
 import { EventDispatcher } from "../../util/data";
 import { ImageEvents } from "./elements/image/Image";
 import { Transform } from "../nlcore/elements/transform/transform";
+import type { TransformDefinitions } from "../nlcore/elements/transform/type";
 import { Transition } from "../nlcore/elements/transition/transition";
 import { Layer } from "../nlcore/elements/layer";
 import { Camera } from "../nlcore/elements/camera";
@@ -36,12 +37,16 @@ export type ExposedState = {
         events: EventDispatcher<ImageEvents>;
         initDisplayable: (onResolve: () => void) => Timeline;
         applyTransform: (transform: Transform, onResolve: () => void) => Timeline;
+        applyLoop: (transform: Transform, options?: TransformDefinitions.LoopOptions) => void;
+        stopLoop: (options: TransformDefinitions.LoopStopOptions | undefined, onResolve: () => void) => Timeline;
         applyTransition: (transition: Transition<any>, onResolve: () => void) => Timeline;
         updateStyleSync: () => void;
     };
     [ExposedStateType.text]: {
         initDisplayable: (onResolve: () => void) => Timeline;
         applyTransform: (transform: Transform, onResolve: () => void) => Timeline;
+        applyLoop: (transform: Transform, options?: TransformDefinitions.LoopOptions) => void;
+        stopLoop: (options: TransformDefinitions.LoopStopOptions | undefined, onResolve: () => void) => Timeline;
         applyTransition: (transition: Transition<any>, onResolve: () => void) => Timeline;
         updateStyleSync: () => void;
         flush: () => void;
@@ -49,18 +54,24 @@ export type ExposedState = {
     [ExposedStateType.layer]: {
         initDisplayable: (onResolve: () => void) => Timeline;
         applyTransform: (transform: Transform, onResolve: () => void) => Timeline;
+        applyLoop: (transform: Transform, options?: TransformDefinitions.LoopOptions) => void;
+        stopLoop: (options: TransformDefinitions.LoopStopOptions | undefined, onResolve: () => void) => Timeline;
         applyTransition: (transition: Transition<any>, onResolve: () => void) => Timeline;
         updateStyleSync: () => void;
     };
     [ExposedStateType.camera]: {
         initDisplayable: (onResolve: () => void) => Timeline;
         applyTransform: (transform: Transform, onResolve: () => void) => Timeline;
+        applyLoop: (transform: Transform, options?: TransformDefinitions.LoopOptions) => void;
+        stopLoop: (options: TransformDefinitions.LoopStopOptions | undefined, onResolve: () => void) => Timeline;
         applyTransition: (transition: Transition<any>, onResolve: () => void) => Timeline;
         updateStyleSync: () => void;
     };
     [ExposedStateType.puppet]: {
         initDisplayable: (onResolve: () => void) => Timeline;
         applyTransform: (transform: Transform, onResolve: () => void) => Timeline;
+        applyLoop: (transform: Transform, options?: TransformDefinitions.LoopOptions) => void;
+        stopLoop: (options: TransformDefinitions.LoopStopOptions | undefined, onResolve: () => void) => Timeline;
         applyTransition: (transition: Transition<any>, onResolve: () => void) => Timeline;
         updateStyleSync: () => void;
         flush: () => void;