narraleaf-react 0.4.0 → 0.4.1

package/README.md

@@ -1,10 +1,15 @@
-![](docs/nlr-logo-banner.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-transparent.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
+  <img alt="Fallback image description" src="https://raw.githubusercontent.com/NarraLeaf/.github/refs/heads/master/doc/banner-md-light.png">
+</picture>
 
-# NarraLeaf-React
+<h1 align="center">NarraLeaf-React</h1>
 
-English | [简体中文](docs/README.zh-CN.md)
+<h4 align="center">A React visual novel player framework</h3>
+
+<p align="center">English | <a href="docs/README.zh-CN.md">简体中文</a></p>
 
-A React visual novel player framework
 
 ## What is NarraLeaf-React?
 
@@ -46,7 +51,7 @@ scene1.action([
   johnSmith
     .say("Hello, world!")
     .say`This is my first ${b("NarraLeaf")} story.`
-    .say`Start editing ${c("src/story.js", "#0000ff")} and enjoy the journey!`,
+    .say`Start editing ${c("src/story.js", "#00f")} and enjoy the journey!`,
 
   /**
    * John Doe: Also, don't forget to check out the documentation!
@@ -85,7 +90,7 @@ npm install narraleaf-react
 
 ### Documentation
 
-- [Introduction](https://react.narraleaf.com/documentation/introduction)
+- [Introduction](https://react.narraleaf.com/documentation/introduction)****
 - [Quick Start](https://react.narraleaf.com/documentation/quick-start)
 - [Installation](https://react.narraleaf.com/documentation/installation)
 - [Basic](https://react.narraleaf.com/documentation/basic)
@@ -100,6 +105,9 @@ npm install narraleaf-react
   - [Conditional](https://react.narraleaf.com/documentation/basic/conditional)
   - [Voice](https://react.narraleaf.com/documentation/basic/voice)
   - [Manage Preferences](https://react.narraleaf.com/documentation/basic/manage-preferences)
+- [Solutions](https://react.narraleaf.com/documentation/solutions)
+  - [Customizing the font](https://react.narraleaf.com/documentation/solutions/font)
+  - [Migration from Ren'Py](https://react.narraleaf.com/documentation/solutions/from-renpy)
 - [Core](https://react.narraleaf.com/documentation/core)
   - [Elements](https://react.narraleaf.com/documentation/core/elements)
     - [Scene](https://react.narraleaf.com/documentation/core/elements/scene)
@@ -116,13 +124,16 @@ npm install narraleaf-react
     - [Text](https://react.narraleaf.com/documentation/core/elements/text)
     - [Persistent](https://react.narraleaf.com/documentation/core/elements/persistent)
     - [Story](https://react.narraleaf.com/documentation/core/elements/story)
+    - [Displayable](https://react.narraleaf.com/documentation/core/elements/displayable)
+    - [Layer](https://react.narraleaf.com/documentation/core/elements/layer)
+    - [Service](https://react.narraleaf.com/documentation/core/elements/service)
+    - [Video](https://react.narraleaf.com/documentation/core/elements/video)
   - [Animation](https://react.narraleaf.com/documentation/core/animation)
   - [Game](https://react.narraleaf.com/documentation/core/game)
+  - [Plugin](https://react.narraleaf.com/documentation/core/plugin)
+  - [Utils](https://react.narraleaf.com/documentation/core/utils)
 - [Player](https://react.narraleaf.com/documentation/player)
-- [Customization](https://react.narraleaf.com/documentation/custom)
-- [Migration](https://react.narraleaf.com/documentation/migration)
-  - [From Ren'Py](https://react.narraleaf.com/documentation/migration/from-renpy)
-- Info
+- About
   - [License](https://react.narraleaf.com/documentation/info/license)
   - [Incompatible Changes](https://react.narraleaf.com/documentation/info/incompatible-changes)
 

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

@@ -1,7 +1,9 @@
-import { TransformDefinitions } from "../elements/transform/type";
-import { Origins } from "../elements/story";
 import { ServiceHandlerCtx } from "../elements/service";
+import { Origins } from "../elements/story";
+import { TransformDefinitions } from "../elements/transform/type";
 import { IGamePluginRegistry } from "../game/plugin/plugin";
 import { LiveGameEventToken } from "../types";
+import { GameHistory } from "../action/gameHistory";
+import { GameConfig } from "../gameTypes";
 export * from "../elements/type";
-export type { TransformDefinitions, Origins, ServiceHandlerCtx, IGamePluginRegistry, LiveGameEventToken, };
+export type { GameHistory, IGamePluginRegistry, LiveGameEventToken, Origins, ServiceHandlerCtx, TransformDefinitions, GameConfig, };

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

@@ -8,9 +8,29 @@ declare enum GameSettingsNamespace {
     game = "game"
 }
 export type GamePreference = {
+    /**
+     * If true, the game will automatically forward to the next sentence when the player has finished the current sentence
+     * @default false
+     */
     autoForward: boolean;
+    /**
+     * If true, the game will allow the player to skip the dialog
+     * @default true
+     */
     skip: boolean;
+    /**
+     * If true, the game will show the dialog
+     * @default true
+     */
     showDialog: boolean;
+    /**
+     * The multiplier of the dialog speed
+     *
+     * Dialog speed will apply to:
+     * - The text speed
+     * - The auto-forward delay
+     */
+    gameSpeed: number;
 };
 export type GameHooks = {
     /**

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

@@ -28,36 +28,6 @@ export interface SavedGame {
     };
 }
 export type GameConfig = {
-    app: {
-        debug: boolean;
-        /**
-         * Log level for the logger
-         * Set to true to enable all logs
-         */
-        logger: {
-            log: boolean;
-            info: boolean;
-            warn: boolean;
-            error: boolean;
-            debug: boolean;
-            trace: boolean;
-            verbose: boolean;
-        } | boolean;
-        /**
-         * If true, the game will show the inspector when you hover over the element
-         */
-        inspector: boolean;
-        /**
-         * The config of {@link GameStateGuard}
-         */
-        guard: GuardConfig;
-        /**
-         * Quality of the screenshot, between 0 and 1
-         * @default 1
-         * @deprecated Moved to `$root.screenshotQuality`
-         */
-        screenshotQuality: number;
-    };
     /**
      * The id of the container element for the game
      * @default "__narraleaf_content"
@@ -176,7 +146,6 @@ export type GameConfig = {
     /**
      * Quality of the screenshot, between 0 and 1
      * @default 1
-     * @deprecated Moved to `$root.screenshotQuality`
      */
     screenshotQuality: number;
     /**
@@ -205,6 +174,13 @@ export type GameConfig = {
      * @default 3000
      */
     autoForwardDelay: number;
+    /**
+     * The default pause duration in milliseconds when auto-forward is enabled
+     *
+     * When auto-forward is enabled, any Pause without a custom duration will use this value
+     * @default 1000
+     */
+    autoForwardDefaultPause: number;
     /**
      * If true, when you press [GameConfig.player.skipKey], the game will skip the image transform
      * @default true
@@ -292,6 +268,55 @@ export type GameConfig = {
      * @default () => {}
      */
     onError: (error: Error) => void;
+    app: {
+        debug: boolean;
+        /**
+         * Log level for the logger
+         * Set to true to enable all logs
+         */
+        logger: {
+            log: boolean;
+            info: boolean;
+            warn: boolean;
+            error: boolean;
+            debug: boolean;
+            trace: boolean;
+            verbose: boolean;
+        } | boolean;
+        /**
+         * If true, the game will show the inspector when you hover over the element
+         */
+        inspector: boolean;
+        /**
+         * The config of {@link GameStateGuard}
+         */
+        guard: GuardConfig;
+    };
+    /**
+     * Default font size for the game
+     * @default "16px"
+     */
+    fontSize: React.CSSProperties["fontSize"];
+    /**
+     * Default font weight for the game
+     * @default 400
+     */
+    fontWeight: number;
+    /**
+     * Default font weight for the game
+     * @default 700
+     */
+    fontWeightBold: number;
+    /**
+     * Default font family for the game
+     * @default "sans-serif"
+     */
+    fontFamily: React.CSSProperties["fontFamily"];
+    /**
+     * Override the default stage
+     * @default null
+     */
+    stage: React.ReactNode | null;
 };
 export type GameSettings = {
     volume: number;

package/dist/game/player/elements/menu/UIMenu/Item.d.ts

@@ -2,5 +2,11 @@ import React from "react";
 export interface ItemProps {
     className?: string;
     style?: React.CSSProperties;
+    /**
+     * The keyboard binding for this item, see [Key_Values](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) for more information
+     *
+     * When this key is pressed, the item will be selected and the action will be executed
+     */
+    bindKey?: string;
 }
-export default function Item({ className, style }: ItemProps): React.JSX.Element;
+export default function Item({ className, style, bindKey }: ItemProps): React.JSX.Element;

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

@@ -0,0 +1,21 @@
+/**
+ * Represents the context of a dialog, containing information about its completion status
+ * and the text content.
+ */
+export type DialogContext = {
+    /** Whether the dialog has finished displaying */
+    done: boolean;
+    /** The text content of the dialog */
+    text: string;
+};
+/**
+ * A custom hook that provides access to the current dialog's state and content.
+ * It retrieves the dialog information from the sentence context and processes
+ * the words to generate the final text.
+ *
+ * @returns {DialogContext} An object containing the dialog's completion status and text content
+ */
+export declare function useDialog(): {
+    done: boolean;
+    text: string;
+};

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

@@ -5,7 +5,7 @@ type PageRouterProps = Readonly<{
 /**
  * Page Router for NarraLeaf-React
  *
- * **Note**: only `Page` components are allowed as children, other components will be ignored.
+ * **Note**: only `Page` and `Stage` components are allowed as children, other components will be ignored.
  *
  * @example
  * ```tsx

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

@@ -7,5 +7,6 @@ import Item from "./elements/menu/UIMenu/Item";
 import Notifications from "./elements/notification/Notifications";
 import Texts from "./elements/say/Sentence";
 import Nametag from "./elements/say/Nametag";
-import Dialog from "../../game/player/elements/say/Dialog";
-export { Isolated, usePreference, Stage, Page, GameMenu, Item, Notifications, Texts, Nametag, Dialog, };
+import Dialog from "./elements/say/Dialog";
+import { useDialog } from "./elements/say/useDialog";
+export { Isolated, usePreference, Stage, Page, GameMenu, Item, Notifications, Texts, Nametag, Dialog, useDialog, };