narraleaf-react 1.0.0 → 1.1.0

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

@@ -16,6 +16,7 @@ import type { Transition } from "../elements/transition/transition";
 import type { ImageTransition } from "../elements/transition/transitions/image/imageTransition";
 import type { Layer } from "../elements/layer";
 import type { VfxFadeOptions } from "../elements/vfx";
+import type { VideoFadeOptions } from "../elements/video";
 import type { PuppetCommandOptions } from "../elements/displayable/puppet";
 export declare const DisplayableActionTypes: {
     readonly action: "displayable:action";
@@ -162,7 +163,7 @@ export declare const VideoActionTypes: {
     readonly seek: "video:seek";
 };
 export type VideoActionContentType = {
-    [K in typeof VideoActionTypes[keyof typeof VideoActionTypes]]: K extends "video:action" ? any : K extends "video:preload" | "video:show" | "video:hide" | "video:play" | "video:pause" | "video:stop" | "video:resume" ? [] : K extends "video:seek" ? [number] : any;
+    [K in typeof VideoActionTypes[keyof typeof VideoActionTypes]]: K extends "video:action" ? any : K extends "video:show" | "video:hide" ? [VideoFadeOptions?] : K extends "video:preload" | "video:play" | "video:pause" | "video:stop" | "video:resume" ? [] : K extends "video:seek" ? [number] : any;
 };
 export declare const VfxActionTypes: {
     readonly action: "vfx:action";

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

@@ -21,6 +21,17 @@ export declare class VideoAction<T extends Values<typeof VideoActionTypes> = Val
     };
     executeAction(gameState: GameState, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
     private changeStateBase;
+    /**
+     * {@link changeStateBase} for a fade, which the player can walk away from halfway.
+     *
+     * Aborting the action - stepping back, loading a save, starting a new game - abandons the fade
+     * where it stands, and the element goes back to showing what `video.state.display` says: the undo
+     * that follows the abort then decides what that is. The handler is told through `signal`, so the
+     * part of it that records the change never runs for a change that did not happen.
+     */
+    private changeStateFading;
+    /** Whether a show or hide was asked to fade, rather than to happen at once. */
+    private static fades;
     private changeState;
     private changeStateAsync;
     stringify(_story: Story, _seen: Set<LogicAction.Actions>, _strict: boolean): string;

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

@@ -23,6 +23,7 @@ import { Puppet } from "../elements/displayable/puppet";
 import { NVLToken } from "../elements/nvl";
 export { Character, Narrator, Condition, Control, Image, Lambda, Menu, NVLToken, Scene, Script, Sentence, Sound, Story, Transform, Word, Text, Pause, TextEvent, Persistent, Service, Layer, Camera, Video, Vfx, Puppet, };
 export type { VfxConfig, VfxBlendMode, VfxFadeOptions } from "../elements/vfx";
+export type { VideoFadeOptions } from "../elements/video";
 export type { IPuppetUserConfig, PuppetConfig, PuppetCommandOptions, } from "../elements/displayable/puppet";
 export type { PuppetBackend, PuppetDescription, PuppetInstance, PuppetMountContext, PuppetSize, PuppetState, PuppetStatus, } from "../game/puppet/puppetBackend";
 export type { LayeredDefinition, LayerGroupDefinition, LayerResolver, LayerSlot, LayerTagsOf, LayerVariants, } from "../elements/displayable/image";

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

@@ -1,10 +1,27 @@
 import { Actionable } from "../action/actionable";
 import { Chained, Proxied } from "../action/chain";
 import { LogicAction } from "../game";
+import type { TransformDefinitions } from "../elements/transform/type";
 export type VideoConfig = {
     src: string;
     muted: boolean;
 };
+/**
+ * How {@link Video.show} or {@link Video.hide} fades the clip in or out.
+ *
+ * Omitted, or with no positive `duration`, the clip appears or disappears at once - which is what
+ * `show()` and `hide()` have always done.
+ */
+export type VideoFadeOptions = {
+    /** How long the fade takes, in milliseconds. */
+    duration?: number;
+    /**
+     * The curve of the fade: a named easing (`"linear"`, `"easeIn"`, `"easeOut"`, `"easeInOut"`) or a
+     * cubic-bezier as four numbers. Linear when omitted. A named easing with no CSS equivalent falls
+     * back to `"ease"`, as it does for a `Vfx` fade.
+     */
+    easing?: TransformDefinitions.EasingDefinition;
+};
 export type VideoState = {
     display: boolean;
 };
@@ -33,15 +50,38 @@ export declare class Video extends Actionable<VideoStateRaw> {
      */
     preload(): Proxied<Video, Chained<LogicAction.Actions>>;
     /**
-     * Show the video element.
+     * Show the video element, putting it on the stage first if it is not there yet.
+     *
+     * With `options.duration`, the clip fades in over that many milliseconds and the action waits for
+     * the fade to finish; it starts once the clip can present a frame, so what fades in is the picture
+     * and not an empty rectangle. Without it the clip appears at once.
      * @chainable
+     * @example
+     * ```ts
+     * video.show({duration: 500});
+     * ```
      */
-    show(): Proxied<Video, Chained<LogicAction.Actions>>;
+    show(options?: VideoFadeOptions): Proxied<Video, Chained<LogicAction.Actions>>;
     /**
-     * Hide the video element.
+     * Hide the video element and take it off the stage.
+     *
+     * With `options.duration`, the clip fades out over that many milliseconds - holding whatever frame
+     * it is on, which after {@link play} is its last - and leaves the stage once the fade is over; the
+     * action waits for that. Without it the clip disappears at once.
+     *
+     * A clip that is not on the stage has nothing to hide, and the call does nothing.
      * @chainable
+     * @example
+     * ```ts
+     * // A cutscene that clears itself away when it ends
+     * scene.action([
+     *     video.show(),
+     *     video.play(),
+     *     video.hide({duration: 600}),
+     * ]);
+     * ```
      */
-    hide(): Proxied<Video, Chained<LogicAction.Actions>>;
+    hide(options?: VideoFadeOptions): Proxied<Video, Chained<LogicAction.Actions>>;
     /**
      * Play the video and wait until it finishes.
      * @chainable

package/dist/game/player/elements/image/Image.d.ts

@@ -1,10 +1,76 @@
 import { Image as GameImage } from "../../../nlcore/elements/displayable/image";
 import React from "react";
 import { GameState } from "../../gameState";
+import { ElementProp, TransitionTask } from "../../../nlcore/elements/transition/type";
 export type ImageEvents = {
     "event:image.onLoad": [];
 };
+/** A laid-out size, in CSS pixels. */
+export type GroupSize = {
+    width: number;
+    height: number;
+};
+/**
+ * Where a transition puts a group that does not size the box: on the very pixels it will cover
+ * once it is the image at rest. `null` means exactly where a picture at rest sits.
+ *
+ * The box takes the sizing group's size, and the wrapper around it is placed by a layout anchor (a
+ * percentage of the stage, measured from the top - or from the bottom on an inverted axis) plus a
+ * `translate` of half its own size. The stage is scaled by a non-integer factor, so these lengths
+ * fall between device pixels, and the browser snaps layout positions to the pixel grid while
+ * leaving translations where they are. A group of the box's size therefore sits in it exactly as
+ * an image at rest does - by layout, on its corner, with no transform of its own - and comes out
+ * on the same pixels. That is the common case (two backgrounds of one size, a picture fading into
+ * itself, a character's expressions), and adding anything to it, even a translate of nothing, can
+ * change how a scaled wrapper's content is sampled.
+ *
+ * A group of another size has to make up the difference inside the box, and how it does so decides
+ * what the browser draws. Centred by layout (`top: 50%`, a flex box, auto margins), or by a
+ * transform alone, it lands within a pixel of its resting place but on the other side of a
+ * rounding; it is drawn resampled at a slightly different offset, and when the transition ends and
+ * the box takes its size, the whole picture steps by a fraction of a pixel and changes sharpness.
+ * So the difference is split the way the wrapper will split it at rest. On an axis anchored at the
+ * top or left the wrapper's layout position does not depend on its size: the group sits on that
+ * edge of the box and a translate moves it by half the size difference - the half the wrapper's own
+ * translate stops adding once the box has the group's size. On an inverted axis the wrapper is
+ * anchored at its bottom or right edge, so its layout position moves with its size: the group sits
+ * on that edge instead, which puts its layout position where the wrapper's will be, and the
+ * translate takes the other half back. Every length that gets snapped is then one that will be
+ * snapped at rest, and the unsnapped ones add up to the translate the wrapper will carry.
+ *
+ * Under a wrapper that also scales or rotates, the browser drops the fraction of the wrapper's own
+ * layout position before transforming, so on an inverted axis a group of another size can still be
+ * sampled a little differently from the way it will be at rest; it is never displaced.
+ *
+ * Transitions that move a group write the independent `translate` property, which composes with
+ * this.
+ */
+export declare function transitionGroupPlacement(box: GroupSize, own: GroupSize, invertX: boolean, invertY: boolean): React.CSSProperties | null;
 export declare function stackStyle(darkness: number): React.CSSProperties;
+/**
+ * The props each group of a running transition sits on, index-aligned with the transition's
+ * resolvers; a resolver's own frame is merged over them.
+ *
+ * The group that sizes the box stays exactly as it is at rest, and every other group the transition
+ * shows sits where it will rest once it sizes the box itself (see `transitionGroupPlacement`), so
+ * neither moves, nor changes how it is sampled, when the transition starts or when it ends. A
+ * group whose size is not known yet has not loaded and shows nothing; it is placed as at rest until
+ * it has. A keyed resolver drives a picture - a stack wrapper on the layered path - and an unkeyed
+ * one drives an element of the transition's own (ThroughColor's colour frame), centred over the box
+ * and gone once the transition ends.
+ *
+ * None of these names a `src`: each side's resolver carries its own. A base that named one would
+ * point the outgoing picture somewhere else for the moment between the two writes, which is long
+ * enough for the browser to drop the decoded picture and paint a frame without it.
+ */
+export declare function transitionGroupProps(resolve: TransitionTask<HTMLImageElement, any>["resolve"], options: {
+    layered: boolean;
+    darkness: number;
+    invertX: boolean;
+    invertY: boolean;
+    /** The laid-out size of each group, index-aligned with `resolve`, where it is known. */
+    sizes: (GroupSize | undefined)[];
+}): ElementProp<HTMLImageElement>[];
 declare function ImageComponent({ image, state, }: Readonly<{
     image: GameImage;
     state: GameState;

package/dist/game/player/lib/visibilityFader.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -11,7 +11,7 @@ import { Text } from "../nlcore/elements/displayable/text";
 import { Displayable } from "../nlcore/elements/displayable/displayable";
 import { Scene } from "../nlcore/elements/scene";
 import { Sound } from "../nlcore/elements/sound";
-import { Video } from "../nlcore/elements/video";
+import { Video, VideoFadeOptions } from "../nlcore/elements/video";
 import { Vfx, VfxFadeOptions } from "../nlcore/elements/vfx";
 import { Puppet } from "../nlcore/elements/displayable/puppet";
 import { Timeline } from "./Tasks";
@@ -80,8 +80,12 @@ export type ExposedState = {
         setBackgroundMusic: (music: Sound | null, fade: number) => Promise<void>;
     };
     [ExposedStateType.video]: {
-        show: () => void;
-        hide: () => void;
+        /** Resolves once the clip is showing: at once, or when a fade in ends, is skipped or is abandoned. */
+        show: (options?: VideoFadeOptions) => Promise<void>;
+        /** Resolves once the clip is hidden: at once, or when a fade out ends, is skipped or is abandoned. */
+        hide: (options?: VideoFadeOptions) => Promise<void>;
+        /** Abandon a fade in flight and show the clip as `video.state.display` says. */
+        cancelFade: () => void;
         play: () => Promise<void>;
         pause: () => void;
         resume: () => Promise<void>;