pominis-react-flow

pominis-react-flow is an internal package for Pominis that facilitates JSON-to-Flow data translation.
It helps structure and format data for use in pominis-frontend and adv.js, ensuring seamless integration with Flow-based components.

📋 Table of Contents

Installation
Usage
Schema Documentation
- AIStorySchema
- SceneNodeSchema
Development

📦 Installation

To install the package, run:

npm install pominis-react-flow

🚀 Usage

Import the package in your project:

import {
  schema,
  flow,
  functions,
  AIStoryType,
  SceneNodeType,
  StoryFlow,
} from "pominis-react-flow";

Components

StoryFlow

The main component for displaying story flow charts:

<StoryFlow
  storyId="your_story_id" // Required: ID of the story to display
  chapterId="chapter_number" // Optional: Specific chapter to display
/>

Data Types

AIStoryType

Represents the complete story structure:

type AIStoryType = {
  id: string;
  title: string;
  characters?: {
    name: string;
    image: string;
    background: string;
    appearance: string;
  }[];
  nodes: Record<string, Record<string, SceneNodeType>>;
};

SceneNodeType

Represents a single scene node in the story:

type SceneNodeType = {
  id: string; // Node identifier (e.g., "node_01")
  imagePrompt: string; // Detailed scene description for image generation
  sceneDescription: string; // Scene setting description
  bg?: string; // Optional background image URL
  bgm?: string; // Optional background music id
  dialogues?: {
    image: string; // Speaker's image
    speaker: string; // Speaker's name
    text: string; // Dialogue content
  }[];
  choices?: {
    text: string; // Choice description
    targetId: string | null; // Target node ID
  }[];
  next: string | null; // Next node ID (if no choices)
};

🎯 Features

Zod Schemas (schema): Type-safe validation for story structures using Zod schemas.
React Flow Types (flow): Full compatibility with @xyflow/react for flow chart visualization.
Utility Functions (functions):
- convertJSONToNodes: Converts story JSON to React Flow nodes
- convertJSONToEdges: Converts story JSON to React Flow edges
- isEndingNode: Checks if a node is an ending node
Type Definitions: Comprehensive TypeScript definitions for story structures and nodes.

📝 Schema Documentation

AIStorySchema

The root schema that represents a complete story structure.

Field	Type	Description
`id`	`string` (optional)	Unique identifier of the story
`title`	`string`	Title of the story
`characters`	`Character[]` (optional)	List of characters appearing in the story
`nodes`	`Record<ChapterId, Record<NodeId, SceneNode>>`	Collection of chapters and their scenes

Chapter IDs

Valid chapter IDs are: chapter1 through chapter10

Character Object

Field	Type	Description
`name`	`string`	Name of the character
`image`	`string`	Photo/avatar of the character
`background`	`string`	Character's background story
`appearance`	`string`	Character's physical appearance description

SceneNodeSchema

Represents a single scene in the story. Each scene can contain dialogues, choices, and various media elements.

Field	Type	Description
`id`	`string`	Unique identifier (format: `node_XX` where XX is incremental)
`imagePrompt`	`string`	Detailed scene description for AI image generation
`imageUrl`	`string`	URL of the generated scene image
`sceneDescription`	`string`	Brief description of the scene setting
`bg`	`string` (optional)	Background image URL
`bgm`	`string` (optional)	Background music identifier
`dialogues`	`Dialogue[]` (optional)	List of character dialogues
`choices`	`Choice[]` (optional)	Available player choices (max 2)
`next`	`string` (optional, nullable)	Next scene ID for linear progression
`source`	`string` (optional, nullable)	Source reference for the scene

Dialogue Object

Field	Type	Description
`image`	`string` (optional)	Speaker's portrait
`speaker`	`string`	Name of the speaking character
`text`	`string`	Dialogue content

Choice Object

Field	Type	Description
`text`	`string`	Choice description
`targetId`	`string` (nullable)	Target scene ID

Note: Choices are decision points that affect the story progression. Good choices help achieve the hero's goal, while poor choices create additional challenges. Different choices typically lead to different story branches.

🔧 Development

To rebuild the package during development:

npm run npmbuild