narraleaf-react 0.4.0-beta.3 → 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?
 
@@ -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/action/actionTypes.d.ts

@@ -6,7 +6,6 @@ import { Transform } from "../elements/transform/transform";
 import type { Scene } from "../elements/scene";
 import type { MenuData } from "../elements/menu";
 import { Awaitable, FlexibleTuple, SelectElementFromEach } from "../../../util/data";
-import { ITransition } from "../elements/transition/type";
 import type { Sound } from "../elements/sound";
 import type { Script } from "../elements/script";
 import { Sentence } from "../elements/character/sentence";
@@ -110,7 +109,7 @@ export declare const TextActionTypes: {
     readonly setFontSize: "text:setFontSize";
 };
 export type TextActionContentType = {
-    [K in typeof TextActionTypes[keyof typeof TextActionTypes]]: K extends "text:setText" ? [string] : K extends "text:show" ? [Transform<TransformDefinitions.TextTransformProps>] : K extends "text:hide" ? [Transform<TransformDefinitions.TextTransformProps>] : K extends "text:applyTransform" ? [Transform<TransformDefinitions.TextTransformProps>] : K extends "text:init" ? [Scene?] : K extends "text:applyTransition" ? [ITransition] : K extends "text:setFontSize" ? [number] : any;
+    [K in typeof TextActionTypes[keyof typeof TextActionTypes]]: K extends "text:setText" ? [string] : K extends "text:show" ? [Transform<TransformDefinitions.TextTransformProps>] : K extends "text:hide" ? [Transform<TransformDefinitions.TextTransformProps>] : K extends "text:applyTransform" ? [Transform<TransformDefinitions.TextTransformProps>] : K extends "text:init" ? [Scene?] : K extends "text:setFontSize" ? [number] : any;
 };
 export declare const PersistentActionTypes: {
     readonly action: "persistent:action";

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

@@ -4,5 +4,6 @@ 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 { GameHistory, IGamePluginRegistry, LiveGameEventToken, Origins, ServiceHandlerCtx, TransformDefinitions };
+export type { GameHistory, IGamePluginRegistry, LiveGameEventToken, Origins, ServiceHandlerCtx, TransformDefinitions, GameConfig, };

package/dist/game/nlcore/elements/transition/type.d.ts

@@ -1,12 +1,21 @@
-import type { EventToken } from "../../../../util/data";
 import { TransformDefinitions } from "../../elements/transform/type";
-/**@deprecated */
-export interface ITransition<T extends ElementProp = Record<string, any>> {
-    start(onComplete?: () => void): void;
-    toElementProps(): T[];
-    copy(): ITransition<T>;
-    complete(): void;
-}
+import type { EventToken } from "../../../../util/data";
+import type { DOMKeyframesDefinition } from "motion/react";
+import React from "react";
+export type ElementProp<T extends Element = Element, U extends React.HTMLAttributes<T> = React.HTMLAttributes<T>> = T extends HTMLImageElement ? React.JSX.IntrinsicAttributes & React.ClassAttributes<T> & React.ImgHTMLAttributes<T> & U : T extends HTMLAnchorElement ? React.JSX.IntrinsicAttributes & React.ClassAttributes<T> & React.AnchorHTMLAttributes<T> & U : T extends HTMLButtonElement ? React.JSX.IntrinsicAttributes & React.ClassAttributes<T> & React.ButtonHTMLAttributes<T> & U : React.JSX.IntrinsicAttributes & React.ClassAttributes<T> & React.HTMLAttributes<T> & U;
+export type ImgElementProp = ElementProp<HTMLImageElement, React.ImgHTMLAttributes<HTMLImageElement>>;
+export type SpanElementProp = ElementProp<HTMLSpanElement, React.HTMLAttributes<HTMLSpanElement>>;
+export type DivElementProp = ElementProp<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>;
+export type CSSElementProp<T extends React.CSSProperties | DOMKeyframesDefinition> = ElementProp & {
+    style: T;
+};
+export type CSSProps = React.CSSProperties;
+export type EmptyObject = {};
+export type EventTypes<T extends any[]> = {
+    "start": [null];
+    "update": T;
+    "end": [null];
+};
 export declare enum TransitionAnimationType {
     Number = 0,
     HexColor = 1

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

@@ -1,4 +1,8 @@
 import { BooleanValueKeyOf, EventDispatcher } from "../../../util/data";
+type PreferenceEventToken = {
+    cancel: () => void;
+};
+type StringKeyof<T> = Extract<keyof T, string>;
 export declare class Preference<T extends Record<string, string | boolean | number | null | undefined>> {
     private readonly settings;
     static EventTypes: {
@@ -25,3 +29,4 @@ export declare class Preference<T extends Record<string, string | boolean | numb
     exportPreferences(): Partial<T>;
     togglePreference<K extends BooleanValueKeyOf<T>>(key: K): void;
 }
+export {};

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

@@ -174,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
@@ -285,6 +292,31 @@ export type GameConfig = {
          */
         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, };