narraleaf-react 0.25.0 → 0.27.0

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

@@ -0,0 +1,29 @@
+import type { WordRenderProps } from "../../../nlcore/elements/character/word";
+import type React from "react";
+/**
+ * Register a component that words may name by id.
+ *
+ * Registering the same id again replaces the component; lines already on screen pick the new one up
+ * on their next render.
+ *
+ * @param id - The id words refer to, e.g. `"glossary"`.
+ * @param component - The component to render those words with.
+ * @returns A function that unregisters it again.
+ * @example
+ * ```tsx
+ * registerWordRenderer("glossary", GlossaryTerm);
+ * // a word compiled from story data can now ask for it by name
+ * new Word("以太浓度", {render: "glossary", data: {entry: "aether"}});
+ * ```
+ */
+export declare function registerWordRenderer<T = unknown>(id: string, component: React.ComponentType<WordRenderProps<T>>): () => void;
+/**
+ * Drop a registration made by {@link registerWordRenderer}.
+ * @param id - The id to forget.
+ */
+export declare function unregisterWordRenderer(id: string): void;
+/**
+ * The component registered under an id, or `null`.
+ * @param id - The id to look up.
+ */
+export declare function getWordRenderer(id: string): React.ComponentType<WordRenderProps<any>> | null;

package/dist/game/player/elements/scene/stageTransition.d.ts

@@ -0,0 +1,47 @@
+import type { Scene } from "../../../nlcore/elements/scene";
+import type { CSSProps } from "../../../nlcore/elements/transition/type";
+/**
+ * Which scene each half of a stage transition drives.
+ *
+ * A transition task's resolvers are already split by {@link Transition.asPrev} / {@link
+ * Transition.asTarget}; this is what those two roles mean at the stage level.
+ */
+export type StageTransitionRoles = {
+    /** The scene being left. Driven by the `asPrev` resolvers. */
+    from: Scene;
+    /** The scene being entered. Driven by the `asTarget` resolvers. */
+    to: Scene;
+};
+/**
+ * What a scene root paints when no transition owns it.
+ *
+ * This must name **every** property any transition writes to a scene half. A property left out
+ * is not neutral — it keeps whatever the last frame put there. That is survivable for the
+ * outgoing scene (it is unmounted moments later) but not for the incoming one, which lives on:
+ * a `Reveal` leaves a fully-opaque `mask-image` behind, and the scene would then carry that mask
+ * for the rest of its life. Cancellation is worse still — it stops mid-flight with no final
+ * frame, so a half-way value would stick forever on both halves.
+ *
+ * `stageSettledStyle.test.ts` pins this list against what the built-in transitions actually
+ * write, so a transition cannot start writing a property without this naming it.
+ */
+export declare function stageSettledStyle(): CSSProps;
+/**
+ * What the scene a transition moved away from paints once the transition is over: nothing.
+ *
+ * The transition finishing is not what removes the outgoing scene — `scene:exit` is a separate
+ * action, so the scene stays mounted for a moment afterwards, and during that moment it must not be
+ * on screen. Leaving that to the stacking order does not work: settling gives the incoming scene
+ * `z-index: auto` while the outgoing one still carries an explicit `0`, and those are the same
+ * stacking level, so document order decides — and the outgoing scene is the later node. It comes to
+ * the front, at whatever opacity its half of the transition left it at.
+ *
+ * A `Dissolve` hides that, because its outgoing half ends at zero opacity. A `Reveal` does not: its
+ * outgoing half is `{}`, never touched at all, because the effect is entirely the incoming scene
+ * being uncovered on top of it. So the scene the player just left reappears, at full opacity, in
+ * front — for as many frames as `scene:exit` takes to arrive.
+ *
+ * Hiding it is also what the per-element path has always done: `useDisplayable` discards the
+ * element that played the outgoing half the moment the transition completes.
+ */
+export declare function stageRetiredStyle(): CSSProps;

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

@@ -193,6 +193,7 @@ export declare class GameState {
     readonly gameHistory: GameHistoryManager;
     pageRouter: null;
     private stageClickBuffer;
+    private readonly advanceSuspensions;
     private readonly nvlAdvanceWaiters;
     private advDialogState;
     private _fastForwarding;
@@ -318,6 +319,24 @@ export declare class GameState {
     settleAdvDialog(dialogId: string): this;
     getAdvDialogState(): AdvDialogState | null;
     recordStageClick(): this;
+    /**
+     * Hold the line where it is: while at least one suspension is out, clicking the stage and
+     * pressing the advance or skip key do nothing.
+     *
+     * Anything that opens on top of a line and wants the player's next keystroke needs this — a
+     * definition popup on an inline word, a term the player is reading. Without it a popup opens and
+     * the very next space bar advances the line behind it, which is the one thing the popup exists
+     * to prevent.
+     *
+     * Suspensions nest: the line resumes once every one of them has been released.
+     *
+     * @returns A function that releases this suspension. Safe to call more than once.
+     */
+    suspendAdvance(): () => void;
+    /**
+     * Whether anything is currently holding the line — see {@link GameState.suspendAdvance}.
+     */
+    isAdvanceSuspended(): boolean;
     consumeStageClick(maxAgeMs?: number): boolean;
     createDisplayable(displayable: LogicAction.DisplayableElements, scene?: Scene | null, layer?: Layer | null): this;
     disposeDisplayable(displayable: LogicAction.DisplayableElements, scene?: Scene | null, layer?: Layer | null): this;
@@ -366,6 +385,18 @@ export declare class GameState {
     createElementSnapshot(element: PlayerStateElement): PlayerStateElementSnapshot;
     fromElementSnapshot(snapshot: PlayerStateElementSnapshot): PlayerStateElement;
     private removeElements;
+    /**
+     * Leaving a scene returns everything the scene put on stage to the pose its constructor config
+     * describes — the displayables on each layer, and the layers themselves, which are mutable at
+     * runtime and would otherwise carry a slide or a fade into the next scene.
+     *
+     * The story camera is the one displayable that deliberately outlives a scene (a story owns
+     * exactly one, and it frames the whole stage across scene changes), so it is skipped here.
+     * Nothing in the engine's own pipeline can put it on a layer — only images, texts and puppets
+     * emit `displayable:init`, which is what registers an element into the layer map — but a host
+     * may register any displayable by hand through `DevTools.registerDisplayable`, so the camera is
+     * excluded explicitly rather than by trusting that route to stay closed.
+     */
     private resetLayers;
     private syncNvlDerivedState;
     private emitNvlStateChange;

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * Hold the line while something of yours is open.
+ *
+ * A popup drawn over a line — a definition of an inline word, a term the player is reading — has to
+ * stop the line advancing underneath it, or the space bar that should dismiss the popup skips to
+ * the next line instead. Pass `true` while it is open and the stage click, the advance key and the
+ * skip key all stop reaching the dialog; the hold is released on `false`, and on unmount, so a
+ * popup that disappears can never leave the game stuck.
+ *
+ * Several holds may be out at once; the line resumes when the last one is released.
+ *
+ * @param active - Whether to hold the line right now.
+ * @example
+ * ```tsx
+ * function GlossaryTerm({children, revealed, data}: WordRenderProps<{entry: string}>) {
+ *     const [open, setOpen] = useState(false);
+ *     useSuspendAdvance(open);
+ *     return <span onClick={() => revealed && setOpen(v => !v)}>{children}</span>;
+ * }
+ * ```
+ */
+export declare function useSuspendAdvance(active: boolean): void;

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

@@ -0,0 +1,58 @@
+/**
+ * Vertical typesetting helpers shared by the typewriter and the preview renderer.
+ *
+ * A vertical box is set the way a Japanese novel is: glyphs stand upright in a column that reads
+ * top to bottom, and the next column starts to the left. Two things in that layout are not free,
+ * and both are about text that is not Japanese:
+ *
+ * - A Latin word must stay whole. `word-break: break-all`, which the horizontal renderer wants so
+ *   that CJK wraps anywhere, will otherwise split "Prologue" across two columns, one glyph at a
+ *   time, sideways.
+ * - A short run - a two-digit number, an initialism - reads better set upright across the column
+ *   than laid on its side. That is tate-chu-yoko (縦中横), and CSS spells it
+ *   `text-combine-upright: all` on a wrapper around exactly that run.
+ */
+import React from "react";
+export type TextWritingMode = "horizontal-tb" | "vertical-rl" | "vertical-lr";
+export type TextGlyphOrientation = "mixed" | "upright" | "sideways";
+/**
+ * Tate-chu-yoko setting: `true` uses the typographic default of two characters, a number sets the
+ * longest run to combine, and `false` turns it off.
+ */
+export type TateChuYoko = boolean | number;
+export declare const DEFAULT_TATE_CHU_YOKO_MAX_LENGTH = 2;
+export declare function isVerticalWritingMode(mode: TextWritingMode | undefined): boolean;
+/** The longest run to combine, or 0 when tate-chu-yoko is off. */
+export declare function resolveTateChuYokoMaxLength(setting: TateChuYoko | undefined): number;
+/**
+ * The writing-mode half of the text container's style.
+ *
+ * `text-orientation` is only written while vertical, where it means something; in a horizontal box
+ * it would sit in the inline style doing nothing.
+ */
+export declare function verticalContainerStyle(mode: TextWritingMode | undefined, orientation: TextGlyphOrientation | undefined): React.CSSProperties;
+export type VerticalTextSegment = {
+    text: string;
+    combineUpright: boolean;
+};
+/**
+ * Splits text into the runs tate-chu-yoko combines and the text around them.
+ *
+ * A run longer than `maxLength` is left in the surrounding segment rather than cut down to fit:
+ * a long English word belongs on its side, which is what the writing mode does with it anyway.
+ */
+export declare function segmentVerticalText(text: string, maxLength: number): VerticalTextSegment[];
+/**
+ * How a word's own box breaks.
+ *
+ * Vertical text keeps `word-break: normal`, which still breaks between CJK characters - that rule
+ * has never needed `break-all` - while leaving Latin words whole.
+ */
+export declare function wordBreakStyleFor(vertical: boolean): React.CSSProperties;
+/**
+ * Renders a word's text with its short runs set upright.
+ *
+ * Returns the string itself when nothing would be combined, so horizontal text - and vertical text
+ * with no Latin in it - is one text node, exactly as before.
+ */
+export declare function renderWordText(text: string, vertical: boolean, tateChuYoko: TateChuYoko | undefined): React.ReactNode;

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

@@ -21,9 +21,21 @@ import { NvlContainer } from "./elements/nvl/NvlContainer";
 import { DefaultNvlContainer } from "./elements/nvl/DefaultNvlContainer";
 import { NvlDialogList, DefaultNvlDialogItem } from "./elements/nvl/NvlDialogList";
 import { NvlProvider, useNvl, useNvlDialogs, useIsNvlMode, useIsNvlVisible } from "./elements/nvl/NvlContext";
+import { getWordRenderer, registerWordRenderer, unregisterWordRenderer } from "./elements/say/wordRenderer";
+import { useDialogOverlay } from "./elements/say/dialogOverlay";
+import { useSuspendAdvance } from "./lib/useSuspendAdvance";
 export type { DialogAvatarContext } from "./elements/say/Avatar";
 export type { BaseTextsProps, EntryTextsProps, RawTextsProps, TextAppearanceProps, TextsPreviewInput, TextsPreviewLoop, TextsPreviewProps, TextsProps, } from "./elements/say/Sentence";
+/**
+ * The vocabulary of the vertical-text props on `TextAppearanceProps`.
+ *
+ * Exported because a value has to be named somewhere other than the JSX attribute: an application
+ * that keeps its typography in a settings object, or hands the mode down through its own props,
+ * had no way to type either without restating the unions.
+ */
+export type { TateChuYoko, TextGlyphOrientation, TextWritingMode, } from "./lib/verticalText";
+export type { DialogOverlay, DialogOverlayRect } from "./elements/say/dialogOverlay";
 export type { NametagProps } from "./elements/say/Nametag";
 export type { ItemProps } from "./elements/menu/UIMenu/Item";
 export type { ChoiceEvaluated } from "./elements/menu/type";
-export { Isolated, usePreference, Stage, GameMenu, Item, useUIMenuContext, Notifications, Texts, TextsPreview, Nametag, Dialog, Avatar, useAvatar, useDialog, useVoiceState, Page, Layout, LayoutRouterProvider, PageInjectContext, RootPath, FixedAspectRatioContainer, useKeyBinding, useLiveGame, NvlContainer, DefaultNvlContainer, NvlDialogList, DefaultNvlDialogItem, NvlProvider, useNvl, useNvlDialogs, useIsNvlMode, useIsNvlVisible, };
+export { Isolated, usePreference, Stage, GameMenu, Item, useUIMenuContext, Notifications, Texts, TextsPreview, Nametag, Dialog, Avatar, useAvatar, useDialog, useDialogOverlay, useSuspendAdvance, registerWordRenderer, unregisterWordRenderer, getWordRenderer, useVoiceState, Page, Layout, LayoutRouterProvider, PageInjectContext, RootPath, FixedAspectRatioContainer, useKeyBinding, useLiveGame, NvlContainer, DefaultNvlContainer, NvlDialogList, DefaultNvlDialogItem, NvlProvider, useNvl, useNvlDialogs, useIsNvlMode, useIsNvlVisible, };