@elvishscout/mdstory 0.1.2 → 0.1.3

package/README.md

@@ -1,5 +1,295 @@
 # MdStory
 
-An interactive story format based on Markdown and Handlebars with JavaScript support.
+An interactive fiction scripting format based on Markdown and Handlebars.
 
-Online demo available on <https://mdstory.elvish.cc>.
+Online demo: <https://mdstory.elvish.cc>
+
+## Features
+
+- Seamless intergration of Markdown, Handlebars and JavaScript.
+- Ease-to-use API, for both Web and command line applications.
+
+## File Format
+
+### Metadata
+
+The story file header may include YAML-formatted [Metadata](#type-metadata). Metadata defines the basic information and global configuration of the story.
+
+### Chapters
+
+Story files are divided into chapters by level-one headings. The `id` attribute of the heading serves as the unique identifier (`id`) for the chapter. If omitted, the heading content is used as the chapter `id` instead.
+
+Handlebars template language is supported in the chapter content. During rendering, properties in `globals` and `assets` are added to the context for direct access by the template.
+
+### Helpers
+
+MdStory includes built-in Handlebars helpers for creating interactive components or various functionalities:
+
+#### `{{input type name=default}}`
+
+Creates an input of type `type` and assigns the input value (by default `default`) to a global variable named `name`. Supported input types include: `string`, `number`, `boolean`, and `object` (represented in a JSON string).
+
+In HTML rendering mode, it generates a corresponding `<input>` element.
+
+#### `{{set name=value}}`
+
+Assigns the value `value` to a global variable named `name`.
+
+#### `{{#nav target}}`
+
+Creates an entry to navigate to another chapter identified by `target`.
+
+In HTML rendering mode, it generates a corresponding `<button type="submit">` element.
+
+#### `{{linebreak [n]}}`
+
+Inserts `n` blank lines, where `n` defaults to `1`.
+
+#### `{{asset name}}`
+
+Retrieves the URL of a resource file named `name`. Basically it acts the same way as `{{name}}` except that it supports resource names with special characters.
+
+#### `{{mime name}}`
+
+Retrieves the MIME type of a resource file named `name`.
+
+### JavaScript Scripts
+
+JavaScript may be included into the story file using the `<script>` tag. Scripts before any level-one headings are considered global scripts, while those within chapters are considered chapter scripts. Only one `<script>` tag is allowed at the beginning of the story and in each chapter.
+
+Scripts are evaluated during runtime using the `Function()` constructor, therefore you may use top-level `return` statements to return objects of type [StoryHooks](#type-storyhooks) or [ChapterHooks](#type-chapterhooks).
+
+### Stylesheets
+
+CSS stylesheets may be included using the `<style>` tag, they will be extracted and gathered into the `stylesheet` property of [StoryBody](#type-storybody) during parsing.
+
+## Examples
+
+Here are some [examples](./examples/) of story files.
+
+## API
+
+### `type Value`
+
+The type of variables in MdStory, basically all types allowed in JSON, including primitive values (`string`, `number`, `boolean`, `null`) and nested `array`s and `object`s. Functions and `undefined` are not supported.
+
+### `type Scope`
+
+An object of variable values by their names, used to store global variables or input fields.
+
+### `type Asset`
+
+A referenceable resource file.
+
+#### Properties
+
+- `url`: The URL of the resource.
+- `mime (optional)`: The MIME type of the resource.
+
+### `type Metadata`
+
+The Metadata of the story.
+
+#### Properties
+
+- `title (optional)`: The story title.
+- `author (optional)`: The author's name.
+- `email (optional)`: The author's email address.
+- `globals (optional)`: An object of type [Scope](#type-scope) containing initial values of global variables.
+- `assets (optional)`: An object of resource names and [Asset](#type-asset) objects, containing all assets used in the story.
+
+### `type ChapterBody`
+
+The structured representation of chapter content.
+
+#### Properties
+
+- `title`: The chapter title.
+- `template`: The Handlebars template for rendering.
+- `script`: The JavaScript script for the chapter.
+
+### `type StoryBody`
+
+The structured representation of story content.
+
+#### Properties
+
+- `metadata`: The story [Metadata](#type-metadata).
+- `chapters`: An object of [ChapterBody](#type-chapterbody) objects by their `id`s.
+- `entry`: The `id` of the entry chapter of the story, which may be `null`.
+- `script`: The global JavaScript script of the story.
+- `stylesheet`: The global stylesheet of the story.
+
+### `type StoryHooks`
+
+Defines the global lifecycle hooks of the story.
+
+#### Properties
+
+- `onStart (optional)`: Called when the story starts.
+  - Parameters:
+    - `globals`: The initial values of global variables.
+  - Return value: Updated `globals` or `void`.
+
+### `type ChapterHooks`
+
+Defines the lifecycle hooks of a chapter.
+
+#### Properties
+
+- `onEnter (optional)`: Called when entering a chapter.
+  - Parameters:
+    - `globals`: Current global variables.
+  - Return value: Updated `globals` or `void`, effective only during the lifecycle of current chapter.
+- `onLeave (optional)`: Called when leaving a chapter.
+  - Parameters:
+    - `globals`: Current global variables.
+    - `fields`: Input fields from current chapter.
+  - Return value: Updated `globals` or `void`.
+- `onNavigate (optional)`: Called during chapter navigation.
+  - Parameters:
+    - `target` : `id` of target chapter.
+    - `globals`: Current global variables.
+    - `fields`: Input fields from current chapter.
+  - Return value: Updated `target` or `void`.
+
+### `type Renderer`
+
+Defines the renderer interface for generating outputs in different formats.
+
+#### Methods
+
+- `input({ name, type, value }) (optional)`: Generates the rendering result of an input field.
+
+  - Parameters:
+    - `name`: The name of the variable.
+    - `type`: The type of the variable.
+    - `value`: The default value of the variable.
+  - Return value: The rendered input field.
+
+- `nav({ target, children }) (optional)`: Generates the rendering result of chapter navigation.
+  - Parameters:
+    - `target`: The `id` of the target chapter.
+    - `children`: The text content of the navigation button.
+  - Return value: The rendered navigation button.
+
+### `type RenderOptions`
+
+Defines rendering options.
+
+#### Properties
+
+- `format`: The rendering format, which may be `"markdown"`, `"html"`, or a custom [Renderer](#type-renderer).
+- `html (optional)`: Whether to parse Markdown into HTML, defaults to `false`.
+
+### `type RenderResult`
+
+The rendering result, containing the rendered text and extracted fields.
+
+#### Properties
+
+- `text`: The rendered text content.
+- `inputs`: An array of input fields, each containing:
+  - `name`: The name of the variable.
+  - `type`: The type of the variable.
+  - `value`: The default value of the variable.
+- `sets`: An array of set fields, each containing:
+  - `name`: The name of the variable.
+  - `type`: The type of the variable.
+  - `value`: The value of the variable.
+- `navs`: An array of navigation fields, each containing:
+  - `text`: The text content of the navigation button.
+  - `target`: The `id` of the target chapter.
+
+### `type ChapterOptions`
+
+Defines the initialization options of a chapter.
+
+#### Properties
+
+- `id`: The unique identifier of the chapter.
+- `title`: The title of the chapter.
+- `template`: The Handlebars template for rendering.
+- `hooks`: An object of type [ChapterHooks](#type-chapterhooks).
+
+### `class Chapter`
+
+Defines a chapter.
+
+#### Properties
+
+- `id`: The unique identifier of the chapter.
+- `title`: The title of the chapter.
+- `template`: The Handlebars template for rendering.
+- `hooks`: Chapter hooks of type [ChapterHooks](#type-chapterhooks).
+
+#### Methods
+
+- `constructor(options)`: Initializes the chapter instance.
+  - Parameters:
+    - `options`: The chapter options of type [ChapterOptions](#type-chapteroptions).
+- `render(scope, assets, options)`: Renders the story content.
+  - Parameters:
+    - `scope`: The rendering context.
+    - `assets`: The story assets.
+    - `options`: The rendering options of type [RenderOptions](#type-renderoptions).
+  - Return value: The rendering result of type [RenderResult](#type-renderresult).
+
+### `type StoryPrompt`
+
+Defines the prompt function of the story, used to handle user input.
+
+#### Parameters
+
+- `props`: An object containing the current chapter and rendering result.
+  - `chapter`: Current chapter.
+  - `text`: The rendered chapter content.
+  - `inputs`, `sets`, `navs`: Fields from the rendering result.
+
+#### Return value
+
+- A `Promise` resolving to one of the following forms:
+  - `{ target, updates }`: The `id` of the target chapter and updated global variables.
+  - `FormData`: Contains the form data of user input.
+
+### `class StoryBase`
+
+Defines the base class of the story, containing the core logic of the story.
+
+#### Properties
+
+- `metadata`: Story [Metadata](#type-metadata).
+- `globals`: Global variables.
+- `chapters`: An object of chapters by their `id`s.
+- `entry`: The entry chapter of the story.
+- `hooks`: An object of type [StoryHooks](#type-storyhooks).
+- `stylesheet`: The global stylesheet of the story.
+- `assets`: An object of asset files by their alias names.
+
+#### Methods
+
+- `constructor({ metadata, chapters, entry, script, stylesheet })`: Initializes the story instance.
+- `play(prompt, options)`: Starts playing the story.
+  - Parameters:
+    - `prompt`: A function of type [StoryPrompt](#type-storyprompt).
+    - `options`: An object of type [RenderOptions](#type-renderoptions).
+
+### `function parseStoryContent`
+
+Parses the story content in Markdown format.
+
+#### Parameters
+
+- `content`: The story content in Markdown format.
+
+#### Return value
+
+- An object of type [StoryBody](#type-storybody).
+
+### `class Story`
+
+Inherits from [StoryBase](#class-storybase), creating a story instance from the story content in Markdown format.
+
+#### Methods
+
+- `constructor(content: string)`: Initializes the story instance.

package/dist/base/chapter.js

@@ -1,6 +1,7 @@
 import Handlebars from "handlebars";
 import MarkdownIt from "markdown-it";
 import pluginAttrs from "markdown-it-attrs";
+const escapeHtml = (text) => text.replace(/[<>&'"]/g, (ch) => `&#${ch.charCodeAt(0)};`);
 const valueType = (value) => {
     if (typeof value === "string") {
         return "string";
@@ -13,7 +14,6 @@ const valueType = (value) => {
     }
     return "object";
 };
-const escapeHtml = (text) => text.replace(/[<>&'"]/g, (ch) => `&#${ch.charCodeAt(0)};`);
 const createElementHtml = (tag, attrs, children) => {
     // prettier-ignore
     const voidTags = [
@@ -21,61 +21,75 @@ const createElementHtml = (tag, attrs, children) => {
         "link", "meta", "param", "source", "track", "wbr",
     ];
     const attrText = Object.entries(attrs)
-        .filter(([, value]) => value !== undefined)
         .map(([name, value]) => {
         if (typeof value === "boolean") {
             value = value ? "" : undefined;
         }
-        const escapedValue = escapeHtml(value ?? "");
-        return `${name}="${escapedValue}"`;
+        if (value === undefined) {
+            return null;
+        }
+        if (value) {
+            const escapedValue = escapeHtml(value ?? "");
+            return `${name}="${escapedValue}"`;
+        }
+        else {
+            return name;
+        }
     })
+        .filter((attr) => attr !== null)
         .join(" ");
     if (voidTags.includes(tag)) {
         return `<${tag} ${attrText}>`;
     }
     return `<${tag} ${attrText}>${children ?? ""}</${tag}>`;
 };
-const createInputHtml = ({ tagMap = {}, name, type, value, required, readonly, }) => {
-    const tag = tagMap["input"] ?? "input";
+const createInputHtml = ({ name, type, value }) => {
     const inputType = type === "boolean" ? "checkbox" : "text";
     const inputAttrs = {
         name,
         type: inputType,
         value: inputType !== "checkbox" ? (type === "object" ? JSON.stringify(value) : String(value)) : undefined,
         checked: inputType === "checkbox" && value ? "" : undefined,
-        required,
-        readonly,
         "aria-label": name,
     };
-    return createElementHtml(tag, inputAttrs);
+    return createElementHtml("input", inputAttrs);
 };
-const createSubmitButtonHtml = ({ tagMap = {}, target, children, }) => {
-    const tag = tagMap["button"] ?? "button";
+const createSubmitButtonHtml = ({ target, children }) => {
     const buttonAttrs = {
         name: "@target",
         type: "submit",
         value: target,
     };
-    return createElementHtml(tag, buttonAttrs, children);
+    return createElementHtml("button", buttonAttrs, children);
 };
-const useHelper = ({ inputs, sets, navs }, assets, options) => {
+const markdownRenderer = {
+    input({ name, type }) {
+        if (type === "boolean") {
+            return `[? _${name}_]`;
+        }
+        else {
+            return `[> _${name}_]`;
+        }
+    },
+    nav({ children }) {
+        return `[@ __${children}__]`;
+    },
+};
+const htmlRenderer = {
+    input({ type, name, value }) {
+        return createInputHtml({ name, type, value });
+    },
+    nav({ target, children }) {
+        return createSubmitButtonHtml({ target: target ?? "", children });
+    },
+};
+const useHelper = ({ inputs, sets, navs }, assets, renderer) => {
     return {
         input(type, opt) {
             for (const name in opt.hash) {
-                let result;
                 const value = opt.hash[name];
                 inputs.push({ name, type, value });
-                if (options.format === "html") {
-                    result = createInputHtml({ name, type, value, ...options });
-                }
-                else {
-                    if (type === "boolean") {
-                        result = `[? _${name}_]`;
-                    }
-                    else {
-                        result = `[> _${name}_]`;
-                    }
-                }
+                const result = renderer.input ? renderer.input({ name, type, value }) : "";
                 return new Handlebars.SafeString(result);
             }
             return "";
@@ -89,15 +103,9 @@ const useHelper = ({ inputs, sets, navs }, assets, options) => {
             return "";
         },
         nav(target, opt) {
-            let result;
             const text = opt.fn(this).trim();
             navs.push({ text, target });
-            if (options.format === "html") {
-                result = createSubmitButtonHtml({ target: target ?? "", children: text, ...options });
-            }
-            else {
-                result = `[@ __${text}__]`;
-            }
+            const result = renderer.nav ? renderer.nav({ target, children: text }) : "";
             return new Handlebars.SafeString(result);
         },
         asset(name) {
@@ -107,7 +115,7 @@ const useHelper = ({ inputs, sets, navs }, assets, options) => {
             return new Handlebars.SafeString(assets[name]?.mime ?? "");
         },
         linebreak(n) {
-            return new Handlebars.SafeString("\n".repeat(n ?? 1));
+            return new Handlebars.SafeString("<br>".repeat(n ?? 1));
         },
     };
 };
@@ -118,19 +126,28 @@ export class Chapter {
         this.template = template;
         this.hooks = hooks;
     }
-    render(scope, assets = {}, options) {
-        const md = new MarkdownIt({ html: true }).use(pluginAttrs);
+    render(scope, assets = {}, { format, html }) {
+        let renderer;
+        if (format === "markdown") {
+            renderer = markdownRenderer;
+        }
+        else if (format === "html") {
+            renderer = htmlRenderer;
+        }
+        else {
+            renderer = format;
+        }
         const fields = {
             inputs: [],
             sets: [],
             navs: [],
         };
-        const helpers = useHelper(fields, assets, options);
+        const helpers = useHelper(fields, assets, renderer);
         let text;
-        if (options.format === "html") {
+        if (html) {
+            const md = new MarkdownIt({ html: true }).use(pluginAttrs);
             text = Handlebars.compile(this.template)(scope, { helpers });
             text = md.render(text);
-            text = createElementHtml("input", { type: "submit", disabled: true, hidden: true }) + text;
         }
         else {
             text = Handlebars.compile(this.template, { noEscape: true })(scope, { helpers });

package/dist/base/definitions.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
 export const ValueSchema = z.any().transform((v) => v);
 export const ScopeSchema = z.record(ValueSchema);
+const AssetObjectSchema = z.object({ url: z.string(), mime: z.string().optional() });
 export const AssetSchema = z.union([
-    z.string().transform((url) => ({ url, mime: undefined })),
-    z.object({ url: z.string(), mime: z.string().optional() }),
+    z.string().transform((url) => AssetObjectSchema.parse({ url, mime: undefined })),
+    AssetObjectSchema,
 ]);
 export const AssetsSchema = z.record(AssetSchema);
 export const MetadataSchema = z.object({

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@elvishscout/mdstory",
-  "version": "0.1.2",
-  "description": "An interactive story format based on Markdown and Handlebars with JavaScript support.",
+  "repository": "https://github.com/ElvishScout/mdstory.git",
+  "version": "0.1.3",
+  "description": "An interactive fiction scripting format based on Markdown and Handlebars.",
   "main": "./dist/index.js",
   "type": "module",
   "files": [
@@ -37,4 +38,4 @@
   ],
   "author": "Jiakai Jiang",
   "license": "ISC"
-}
+}

package/types/base/chapter.d.ts

@@ -1,13 +1,22 @@
 import { ValueType, Value, ChapterHooks, Scope, Asset } from "./definitions.js";
-type MarkdownOptions = {};
-type HtmlOptions = {
-    tagMap?: Record<string, string>;
+export type Renderer = {
+    input?: ({ name, type, value }: {
+        name: string;
+        type: ValueType;
+        value: string;
+    }) => string;
+    nav?: ({ target, children }: {
+        target: string | null;
+        children: string;
+    }) => string;
 };
-export type RenderOptions = ({
-    format: "markdown";
-} & MarkdownOptions) | ({
-    format: "html";
-} & HtmlOptions);
+export type RenderOptions = {
+    format: "markdown" | "html" | Renderer;
+    html?: boolean;
+};
+export type RenderResult = {
+    text: string;
+} & Fields;
 type Fields = {
     inputs: {
         name: string;
@@ -24,9 +33,6 @@ type Fields = {
         target: string | null;
     }[];
 };
-export type RenderResult = {
-    text: string;
-} & Fields;
 export type ChapterOptions = {
     id: string;
     title: string;
@@ -39,6 +45,6 @@ export declare class Chapter {
     template: string;
     hooks: ChapterHooks;
     constructor({ id, title, template, hooks }: ChapterOptions);
-    render(scope: Scope, assets: Record<string, Asset> | undefined, options: RenderOptions): RenderResult;
+    render(scope: Scope, assets: Record<string, Asset> | undefined, { format, html }: RenderOptions): RenderResult;
 }
 export {};

package/types/base/definitions.d.ts

@@ -9,7 +9,7 @@ export declare const ValueSchema: z.ZodEffects<z.ZodAny, string | number | boole
 export declare const ScopeSchema: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>;
 export declare const AssetSchema: z.ZodUnion<[z.ZodEffects<z.ZodString, {
     url: string;
-    mime: undefined;
+    mime?: string | undefined;
 }, string>, z.ZodObject<{
     url: z.ZodString;
     mime: z.ZodOptional<z.ZodString>;
@@ -22,7 +22,7 @@ export declare const AssetSchema: z.ZodUnion<[z.ZodEffects<z.ZodString, {
 }>]>;
 export declare const AssetsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodEffects<z.ZodString, {
     url: string;
-    mime: undefined;
+    mime?: string | undefined;
 }, string>, z.ZodObject<{
     url: z.ZodString;
     mime: z.ZodOptional<z.ZodString>;
@@ -40,7 +40,7 @@ export declare const MetadataSchema: z.ZodObject<{
     globals: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>>;
     assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodEffects<z.ZodString, {
         url: string;
-        mime: undefined;
+        mime?: string | undefined;
     }, string>, z.ZodObject<{
         url: z.ZodString;
         mime: z.ZodOptional<z.ZodString>;
@@ -57,9 +57,6 @@ export declare const MetadataSchema: z.ZodObject<{
     email?: string | undefined;
     globals?: Record<string, string | number | boolean | JsonArray | JsonObject | null> | undefined;
     assets?: Record<string, {
-        url: string;
-        mime: undefined;
-    } | {
         url: string;
         mime?: string | undefined;
     }> | undefined;