narraleaf-react 0.34.0 → 0.36.0

package/dist/game/nlcore/elements/transition/transitions/image/darkness.d.ts

@@ -9,6 +9,17 @@ export type DarknessOptions = {
     to: number;
     /** Duration in milliseconds. */
     duration: number;
+    /**
+     * Time held at `from` before the brightness starts moving, in milliseconds, taken out of
+     * `duration`. `{from: 1, to: 0, duration: 3000, holdMs: 2000}` is two seconds of black and
+     * then a one-second lift out of it.
+     *
+     * The hold sits at `from` and not at `to` because `from` is where the image swap happens -
+     * the incoming frame is already on screen at the very first tick. That makes this the same
+     * thing {@link ThroughColor} and {@link Exposure} call a hold: the window the swap hides in.
+     * @default 0
+     */
+    holdMs?: number;
     easing?: TransformDefinitions.EasingDefinition;
 };
 /**
@@ -18,11 +29,24 @@ export type DarknessOptions = {
  *
  * This is what backs `image.darken(amount, duration)` — darkening an image in
  * place is expressed as a transition from its current darkness to the new one.
+ *
+ * ⚠ The brightness is only worn for as long as the transition runs. What a
+ * settled element looks like is the element's own business — an image renders at
+ * `Image.state.darkness`, a scene root at nothing at all — so a run ending at a
+ * `to` above zero snaps back to full brightness on its last frame unless
+ * something else is holding that darkness. Ending dark is what a black
+ * background (or {@link ThroughColor} with no uncover) is for; this is a way
+ * *through* a darkness, not a way to sit in one.
+ *
+ * The channel is a linear 0-1 progress and the easing is applied by hand, so
+ * that {@link DarknessOptions.holdMs} can be real time rather than a share of an
+ * eased curve.
  */
 export declare class Darkness extends ImageTransition<AnimationType> {
     private from;
     private to;
     private duration;
+    private holdMs;
     private easing?;
     constructor(options: DarknessOptions);
     createTask(): TransitionTask<HTMLImageElement, AnimationType>;

package/dist/game/nlcore/elements/transition/transitions/image/exposure.d.ts

@@ -20,7 +20,20 @@ export type ExposureOptions = {
      * carries the shadows up without touching the frame at rest. @default 0.04
      */
     lift?: number;
-    /** Fraction (0–1) of the duration spent fully blown out. @default 0 */
+    /**
+     * Time spent fully blown out, in milliseconds, taken out of `duration` and split evenly off
+     * the burn and the cool-down. `{duration: 3000, holdMs: 1500}` burns for 750ms, holds white
+     * for a second and a half, and comes back down over the last 750ms.
+     *
+     * Real time, not a share of an eased curve - see {@link ThroughColor} for why the run is
+     * linear. @default 0
+     */
+    holdMs?: number;
+    /**
+     * Fraction (0–1) of the duration spent fully blown out.
+     * @default 0
+     * @deprecated Use {@link holdMs}. Read only when `holdMs` is absent.
+     */
     hold?: number;
     easing?: TransformDefinitions.EasingDefinition;
 };
@@ -44,6 +57,7 @@ export declare class Exposure extends ImageTransition<AnimationType> {
     private ev;
     private lift;
     private hold;
+    private holdMs;
     private easing?;
     constructor(options: ExposureOptions);
     /**

package/dist/game/nlcore/elements/transition/transitions/image/throughColor.d.ts

@@ -18,7 +18,22 @@ export type ThroughColorOptions = {
     duration: number;
     /** Hold colour. @default "#000000" */
     color?: string;
-    /** Fraction (0–1) of the duration spent fully covered by the colour. @default 0.3 */
+    /**
+     * Time spent fully covered by the colour, in milliseconds, taken out of `duration` and split
+     * evenly off the cover and uncover halves. `{duration: 4000, holdMs: 2000}` is one second in,
+     * two seconds of solid colour, one second out.
+     *
+     * Real time, not a share of an eased curve: see {@link ThroughColor} on why the run is linear.
+     * @default 0.3 × duration
+     */
+    holdMs?: number;
+    /**
+     * Fraction (0–1) of the duration spent fully covered by the colour.
+     * @default 0.3
+     * @deprecated Use {@link holdMs}. A fraction cannot say how long the colour is actually held:
+     * it is a share of the run, so the seconds it buys move whenever the duration does. Read only
+     * when `holdMs` is absent.
+     */
     hold?: number;
     /**
      * The coverage geometry the colour covers the frame through. See
@@ -44,14 +59,22 @@ export type ThroughColorOptions = {
  *
  * The geometry lives entirely in the `pattern` option (see {@link Mask});
  * without one, the colour simply fades in and out (fade-to-black/white, or a
- * flash with `hold: 0`). {@link Reveal} is the direct-cut counterpart that
+ * flash with `holdMs: 0`). {@link Reveal} is the direct-cut counterpart that
  * takes the same patterns. The `uncover` option picks how the second half
  * plays: see {@link ThroughColorUncover}.
+ *
+ * The animation channel is deliberately **linear** and the easing is applied to
+ * each moving half by hand. Easing the whole run would make the hold a band of
+ * *progress* rather than of time, and every eased curve crosses the middle at
+ * its fastest: under the driver's default `easeInOut` a nominal 30% hold plays
+ * as 17.8% of the wall clock. `holdMs` can only mean milliseconds because of
+ * this - see `heldRunCurve`.
  */
 export declare class ThroughColor extends ImageTransition<AnimationType> {
     private duration;
     private color;
     private hold;
+    private holdMs;
     private pattern;
     private inverted;
     private uncover;

package/dist/game/nlcore/elements/transition/transitions/image/transitionMaskUtils.d.ts

@@ -17,3 +17,50 @@ export declare function overlayBase(color: string): CSSProps;
 export declare function wipeGradientDir(direction: TransformDefinitions.WipeDirection): string;
 /** Gradient axis for blinds slats of a given orientation. */
 export declare function blindsAxis(orientation: BlindsOrientation): string;
+/**
+ * The curve an {@link TransformDefinitions.EasingDefinition} names, as a plain function.
+ *
+ * A transition that carves a *held* segment out of its run cannot let the animation driver ease the
+ * whole 0-1 progress: the hold would then be a band of eased progress rather than of wall-clock
+ * time, and an eased curve crosses the middle - exactly where the hold sits - at its fastest. Such
+ * a transition asks the driver for a linear channel and eases each moving half itself, which is
+ * what this resolves the curve for.
+ *
+ * The fallback is `easeInOut` and not `linear`, because that is what the driver applies when no
+ * ease is given (motion's keyframes generator defaults to it): a transition easing its own halves
+ * has to land on the same feel as one that does not.
+ */
+export declare function resolveEasing(ease?: TransformDefinitions.EasingDefinition): (t: number) => number;
+/**
+ * How far a cover -> hold -> uncover run has travelled at a given point of a LINEAR run: `0` is
+ * untouched, `1` is at the extreme (fully covered by the colour, fully blown out). Shared by
+ * {@link ThroughColor} and {@link Exposure}, which differ only in what they do with the number.
+ *
+ * The hold is wall-clock time, carved out of `duration` and split evenly off the two moving halves,
+ * so `holdMs: 2000` on a 4s run is two seconds at the extreme with a second either side. That is
+ * only true because the run itself is linear and the easing is applied to each half here. Eased as
+ * a whole - which is what asking the driver for an eased channel does - the hold is a band of
+ * *progress* instead, and the curve crosses it at its fastest: under the default `easeInOut` a
+ * nominal 30% hold plays as 17.8% of the wall clock, and 50% as 30.8%.
+ *
+ * `hold`, the fraction of the duration, is the older spelling and is read only when `holdMs` is
+ * absent.
+ */
+export declare function heldRunCurve(options: {
+    duration: number;
+    hold?: number;
+    holdMs?: number;
+    easing?: TransformDefinitions.EasingDefinition;
+}): (progress: number) => number;
+/**
+ * The share of a run spent held at the extreme: `holdMs` measured against the duration, or the
+ * legacy `hold` fraction when no absolute time is given.
+ *
+ * A zero-length run has no share to measure, so any positive hold takes all of it - the transition
+ * is then a cut to the extreme and back, which is what a zero duration asks for.
+ */
+export declare function holdFraction(options: {
+    duration: number;
+    hold?: number;
+    holdMs?: number;
+}): number;

package/dist/game/nlcore/gameTypes.d.ts

@@ -410,6 +410,14 @@ export type GameConfig = {
          */
         guard: GuardConfig;
     };
+    /**
+     * Turn off text scaling for the whole game.
+     *
+     * Dialogue text is kept inside its box by being set down as it is typed. Turning this on
+     * leaves every line at the size it was written at, and a line longer than its box overflows it.
+     * @default false
+     */
+    disableTextScaling: boolean;
     /**
      * Override the default stage
      * @default null

package/dist/game/player/elements/say/Sentence.d.ts

@@ -37,18 +37,25 @@ export type TextAppearanceProps = {
      */
     tateChuYoko?: TateChuYoko;
     /**
-     * Set the line down until the whole of it fits the box it is placed in.
+     * Keep the line inside the box it is placed in by setting it down as it is typed.
      *
-     * `fontSize` becomes a ceiling rather than a fixed size: the line is set at it whenever the
-     * finished line fits, and smaller when it does not, down to {@link autoFitMinFontSize}. Sizes
-     * carried by the sentence or by a single word scale with it, so their relative weights hold.
+     * The line is set at `fontSize` and stays there for as long as it fits, so a short line is
+     * never set small. Once the text reaches the end of the box, every further character is
+     * measured and the size comes down by what it takes to fit, to no less than
+     * {@link autoFitMinFontSize}. A line that still overflows at that size is left overflowing.
      *
-     * The box is the container's parent, which needs a size of its own for anything to be fitted to.
-     * @default false
+     * Sizes carried by the sentence or by a single word are scaled with the line rather than
+     * replaced, so their relative weights hold at any size, and a run set larger or smaller inside
+     * the line is accounted for by having been drawn rather than by being predicted.
+     *
+     * The box is the container's parent, which needs a size of its own for anything to be fitted
+     * to. {@link GameConfig.disableTextScaling} turns this off for the whole game.
+     * @default true
      */
     autoFit?: boolean;
     /**
-     * The smallest size auto fit sets, in px. A line that still overflows at it is left overflowing.
+     * The smallest size text scaling sets, in px. A line that still overflows at it is left
+     * overflowing.
      * @default 12
      */
     autoFitMinFontSize?: number;

package/dist/game/player/elements/say/autoFit.d.ts

@@ -1,43 +1,49 @@
 import React from "react";
-/** Smallest size auto fit sets when the line does not say otherwise. */
+/** Smallest size text scaling sets when the line does not say otherwise. */
 export declare const DEFAULT_AUTO_FIT_MIN_FONT_SIZE = 12;
-/** Set on the measuring copy so every explicit word size scales with one write. */
-export declare const AUTO_FIT_SCALE_VAR = "--nl-auto-fit-scale";
 /**
- * The same length, scaled, whatever unit it was written in.
+ * The multiplier every size in the line is written against.
  *
- * The multiplier is a number for the line on screen and the scale custom property for the copy
- * being measured, where one write has to resize every word at once.
+ * One custom property drives the container and every word inside it, so a candidate size is one
+ * write rather than a walk over the elements, and a word that carries a size of its own keeps its
+ * weight against the rest of the line at every scale.
  */
-export declare function scaledFontSize(value: React.CSSProperties["fontSize"], scale: number | string): React.CSSProperties["fontSize"];
-/** The multiplier the measuring copy scales by, readable from every word inside it. */
-export declare const AUTO_FIT_SCALE_MULTIPLIER = "var(--nl-auto-fit-scale, 1)";
-/** What the line is set at when it inherits its size: a share of the size it inherits. */
-export declare function inheritedScaledFontSize(scale: number): React.CSSProperties["fontSize"] | undefined;
+export declare const AUTO_FIT_SCALE_VAR = "--nl-text-scale";
+export declare const AUTO_FIT_SCALE_MULTIPLIER = "var(--nl-text-scale, 1)";
+/** The same length, scaled by the line's current multiplier, whatever unit it was written in. */
+export declare function scaledFontSize(value: React.CSSProperties["fontSize"]): React.CSSProperties["fontSize"];
+/** What the line is set at when it inherits its size: the inherited size, scaled. */
+export declare function inheritedScaledFontSize(): React.CSSProperties["fontSize"];
 export type AutoFitOptions = {
     enabled: boolean;
     /** The floor, in px. A line that overflows at this size is left overflowing rather than set smaller. */
     minFontSize: number;
     /** Vertical writing swaps the axes: the columns advance across the box, not down it. */
     vertical: boolean;
-    /** Everything that changes the laid-out result without changing the box. */
-    signature: string;
+    /**
+     * What has been typed so far. The line is measured again every time this changes, which is what
+     * makes the size follow the text rather than a guess made before it existed.
+     */
+    revealed: number;
 };
 export type AutoFitState = {
     containerRef: React.MutableRefObject<HTMLDivElement | null>;
-    mirrorRef: React.MutableRefObject<HTMLDivElement | null>;
-    /** The share of the authored size the line is set at. */
+    /** The share of the authored size the line is currently set at. */
     scale: number;
 };
 /**
- * Finds the largest size at which a whole line still fits the box it is placed in.
+ * Keeps a line inside its box while it is being typed.
  *
- * The line being typed is not what has to fit - the finished line is - so the search runs against a
- * hidden copy holding every word, laid out under the same box, the same typeface and the same
- * wrapping rules. The copy is what the bisection resizes; the visible line is set once, when the
- * answer is known, and stays there for the rest of the line.
+ * The line is set at the size it was written at and stays there for as long as it fits, so a short
+ * line is never set small "just in case". The moment the text reaches the bottom of the box, the
+ * next character brings the size down by whatever it takes to fit, and every character after it is
+ * measured again. So the size follows what is actually on screen: a run of larger or smaller words
+ * inside the line is accounted for by having been rendered, not by being predicted.
  *
- * The box is the container's parent: a dialog box has a size of its own, and the line is what has
- * to live inside it. A parent with no height of its own leaves the scale at 1.
+ * Within one line the size only ever comes down, since the text only ever grows. A change in the
+ * size of the box starts the line over at its authored size.
+ *
+ * The box is the container's parent, which is the element the host sized. A parent with no height
+ * of its own leaves the line at its authored size.
  */
-export declare function useAutoFitScale({ enabled, minFontSize, vertical, signature }: AutoFitOptions): AutoFitState;
+export declare function useAutoFitScale({ enabled, minFontSize, vertical, revealed }: AutoFitOptions): AutoFitState;