narraleaf-react 0.35.0 → 0.37.0

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

@@ -29,4 +29,4 @@ export type { LayeredDefinition, LayerGroupDefinition, LayerResolver, LayerSlot,
 export type { SentenceMetadata } from "../elements/character/sentence";
 export type { TextEventAppearance, TextEventConfig, TextEventExpression, } from "../elements/character/textEvent";
 export type { CharacterPortraitConfig, DialogAvatar, DialogAvatarResolver, DialogAvatarResolverContext, DialogAvatarResolution, DialogAvatarSource, } from "../elements/character/avatar";
-export type { WordConfig, WordRenderProps, WordRenderer, } from "../elements/character/word";
+export type { WordConfig, WordEmphasis, WordRenderProps, WordRenderer, } from "../elements/character/word";

package/dist/game/nlcore/elements/character/word.d.ts

@@ -44,12 +44,50 @@ export type WordRenderProps<T = unknown> = {
  * cannot carry a function. An id that resolves to nothing renders as plain text.
  */
 export type WordRenderer<T = any> = string | React.ComponentType<WordRenderProps<T>>;
+/**
+ * Emphasis marks: a small glyph drawn beside every character of a word, the typographic way East
+ * Asian text stresses a phrase where a Latin one would go italic (傍点 / 圏点 in Japanese, 着重号 in
+ * Chinese). The marks follow the characters as they are typed out, so a word that is half revealed
+ * carries half its marks.
+ */
+export type WordEmphasis = {
+    /**
+     * The glyph drawn beside each character.
+     * @default "dot"
+     */
+    mark?: "dot" | "circle" | "sesame" | "triangle";
+    /**
+     * Whether that glyph is solid or hollow.
+     * @default "filled"
+     */
+    fill?: "filled" | "open";
+    /**
+     * Which side of the text the marks sit on. In horizontal writing `over` is above the line and
+     * `under` is below it; in vertical writing both sit to the right of the column, where the
+     * convention places them.
+     * @default "over"
+     */
+    position?: "over" | "under";
+};
 export type WordConfig = {
     className: string;
     ruby: string;
     color: Color;
     pause: boolean;
     cps?: number;
+    /**
+     * Emphasis marks drawn beside this word's characters. See {@link Word.emphasis}.
+     */
+    emphasis?: WordEmphasis;
+    /**
+     * This word's size as a share of the line's — `1.25` for a quarter larger, `0.8` for a fifth
+     * smaller. Relative rather than absolute, so the word keeps its weight against the rest of the
+     * line whatever size the line is set at, including while text scaling brings the line down to
+     * fit its box.
+     *
+     * Ignored when {@link WordConfig.fontSize} is set, which pins the word to an absolute size.
+     */
+    fontScale?: number;
     /**
      * Renders this word's revealed characters. See {@link Word.custom}.
      */
@@ -82,6 +120,20 @@ export declare class Word<T extends string | DynamicWord | Pausing | TextEvent =
      * @param text - The text or word to italicize.
      */
     static italic(text: string | Word): Word;
+    /**
+     * Return a word with emphasis marks beside its characters — the East Asian counterpart of
+     * italicising a phrase.
+     *
+     * @param text - The text or word to emphasise.
+     * @param emphasis - Which glyph to draw and which side of the text to draw it on. Defaults to a
+     * filled dot above the line, the Japanese convention; Chinese text sets `position: "under"`.
+     * @example
+     * ```ts
+     * character.say(["それは", Word.emphasis("わたし"), "が決めることです。"]);
+     * character.say(["这是", Word.emphasis("我", {position: "under"}), "的决定。"]);
+     * ```
+     */
+    static emphasis(text: string | Word, emphasis?: WordEmphasis): Word;
     /**
      * Render a word with a component of your own — an inline glossary term that opens a definition
      * popup, a name that links into an in-game encyclopedia, anything the dialogue box cannot say

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/player/elements/say/wordStyle.d.ts

@@ -0,0 +1,23 @@
+import type React from "react";
+import type { WordConfig, WordEmphasis } from "../../../nlcore/elements/character/word";
+/**
+ * The size one word of a line is set at.
+ *
+ * A word sized in absolute units goes through the line's scale multiplier like every other length
+ * in the line. A word sized as a share of the line does not: `em` already resolves against the
+ * line's own size, which the multiplier has been applied to, so scaling it a second time would
+ * bring the word down twice for every step the line comes down.
+ */
+export declare function wordFontSize(config: Partial<WordConfig>, sentenceFontSize: React.CSSProperties["fontSize"]): React.CSSProperties["fontSize"];
+/**
+ * The same rule where no scaling is in play — the sample line a settings screen types out has no box
+ * to fit itself into.
+ */
+export declare function previewWordFontSize(config: Partial<WordConfig>, sentenceFontSize: React.CSSProperties["fontSize"]): React.CSSProperties["fontSize"];
+/**
+ * The emphasis marks a word carries, as the two declarations that draw them.
+ *
+ * The position keyword for vertical writing is always `right`: `over` and `under` are read only in
+ * horizontal writing, and both Japanese and Chinese set the marks on the right of a vertical column.
+ */
+export declare function emphasisStyle(emphasis: WordEmphasis | undefined): React.CSSProperties;