extwee 2.2.5 → 2.2.6

package/README.md

@@ -27,7 +27,7 @@
 
 ## Story Compilation
 
-The process of *story compilation* converts human-readable content, what is generally called a *story*, into a playable format such as HyperText Markup Language (HTML). The result is then presented as links or other visual, interactive elements for another party to interact with to see its content.
+The process of *story compilation* converts human-readable content, what is generally called a *story*, into a playable format such as HyperText Markup Language (HTML). The result is then presented as links or other visual, interactive elements for another party.
 
 The term *compilation* is used because different parts of code are put together in a specific arrangement to enable later play. As part of Twine-compatible HTML, this means combining JavaScript code (generally a "story format") with story HTML data.
 
@@ -59,12 +59,13 @@ Extwee supports multiple historical and current Twine-compatible formats.
 
 | Format                                                                                                                           | Input | Output                                                                                                                                                                                |
 |----------------------------------------------------------------------------------------------------------------------------------|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [ Twine 1 HTML (2006 - 2015) ]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md )          | Yes   | Partial support. Twine 1 HTML can be produced, but the  `StorySettings`  optional passage introduced in Twine 1.4.0 requires external libraries like jQuery not included with Extwee. |
-| [ Twine 1 TWS (2009 - 2015) ]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-twsoutput.md )                | Yes   | Extwee does not support TWS (Python pickle) output because no current version of Twine or other story compilation tool produces this historical format.                                                |
-| [ Twine 2 HTML (2015 - Present) ]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md )      | Yes   | Yes                                                                                                                                                                                   |
-| [ Twine 2 Archive HTML (2015 - Present) ]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-archive-spec.md ) | Yes   | Yes                                                                                                                                                                                   |
-| [ Twee 3 (2021 - Present) ]( https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md )               | Yes   | Yes                                                                                                                                                                                   |
-| [ Twine 2 JSON (2023 - Present) ]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-jsonoutput-doc.md )       | Yes   | Yes                                                                                                                                                                                   |
+| [Twine 1 HTML (2006 - 2015)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md )          | Yes   | Partial support. Twine 1 HTML can be produced, but the  `StorySettings`  optional passage introduced in Twine 1.4.0 requires external libraries like jQuery not included with Extwee. |
+| [Twine 1 TWS (2009 - 2015)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-twsoutput.md )                | Yes   | Extwee does not support TWS (Python pickle) output because no current version of Twine or other story compilation tool produces this historical format.                                                |
+| [Twine 2 HTML (2015 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md )      | Yes   | Yes                                                                                                                                                                                   |
+| [Twine 2 Archive HTML (2015 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-archive-spec.md ) | Yes   | Yes                                                                                                                                                                                   |
+| [Twee 3 (2021 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md )               | Yes   | Yes                                                                                                                                                                                   |
+| [Twine 2 JSON (2023 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-jsonoutput-doc.md )       | Yes   | Yes                                                                                                                                                                                   |
+| [Twine 2 Story Format (2015 - Present)]( https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md )       | Yes   | Yes                                                                                                                                                                                   |
 
 **Note:** Round-trip translations can present problems because of required fields and properties per format. Some metadata may be added or removed based on the specification being followed.
 
@@ -86,6 +87,8 @@ An object must be created using either the `new` keyword in JavaScript or as the
 
 Story and Passage objects can generate multiple output formats: `toTwee()`, `toTwine1HTML()`, `toTwine2HTML()`, and `toJSON()`. Stories cannot be played in a browser without the corresponding compiler combining it with story format data.
 
+The StoryFormat object supports `toString()` method of producing a tab-separated JSON output and `toJSON()` method of generating JSON output matching the Twine 2 Story Format Specification.
+
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 ### Parsers
@@ -110,8 +113,11 @@ Compiles story, story formats, or other data into an archive or playable format.
 - `compileTwine2HTML()`
 - `compileTwine1HTML()`
 - `compileTwine2ArchiveHTML()`
+- `compileStoryFormat()`
+
+To create playable Twine 1 HTML, an `engine.js` file must be supplied. (See [Story Format Archive](https://github.com/videlais/story-formats-archive/tree/main/official/twine1/engine/1.4.2) for available Twine 1 `engine.js` file.)
 
-**Note:** In order to create playable Twine 1 HTML, an `engine.js` file must be supplied.
+Compilation of a story format adds the necessary function wrapper to convert the JSON output, via `toJSON()`, to JSONP.
 
 ### Support Functionality
 
@@ -129,7 +135,9 @@ Extwee has [documentation hosted on GitHub Pages](https://videlais.github.io/ext
 
 ## Command-Line Usage
 
-Extwee supports a command-line interface for four general scenarios:
+Extwee supports a command-line interface for four general scenarios.
+
+**Notes:** As of Extwee 2.2.5, short and long command-line option flags are separated. Short options use one hyphen followed by one character and all long options begin with two hyphens and a name as word.
 
 ### Compiling Twee 3 + Twine 2 Story Format into Twine 2 HTML
 
@@ -145,10 +153,12 @@ De-compile Twine 2 HTML into Twee 3:
 
 ### Compiling Twee 3 into Twine 1 HTML
 
-Enabling Twine 1 mode requires using the `--twine1` flag.
+Enabling Twine 1 mode requires using the `--twine1` long flag.
 
 Because Twine 1 story formats can be split across files, compilation requires the "engine" from Twine 1 named `engine.js`, the name of the story format, and then its `header.html` template code and the optional but often included `code.js` file.
 
+(Refer to the [Story Formats Archive](https://github.com/videlais/story-formats-archive) for access to historic `engine.js` and other files.)
+
 `extwee --twine1 -c -i <tweeFile> -o <Twine1HTML> --engine <engineJS> --name <storyFormatName> --codejs <CodeJS> --header <header>`
 
 ### De-compiling Twine 1 HTML into Twee 3
@@ -159,15 +169,11 @@ Enabling Twine 1 mode requires using the `--twine1` flag.
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
-## Roadmap
-
-Each major version has its own GitHub project:
-
-- [Road to Extwee 2.4.0](https://github.com/users/videlais/projects/4)
-
 ## Tree Shaking Support
 
-For [advanced tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) patterns, most formats are broke into `compile.js` and `parse.js` files exporting associated `compile()` and `parse()` functions. When using the API, it is possible to only import a single function or object to produce smaller and potentially faster code in projects dependent on Extwee functionality.
+For [advanced tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) patterns, most formats are broke into `compile.js` and `parse.js` files exporting associated `compile()` and `parse()` functions.
+
+When using the API, it is possible to only import a single function or object to produce smaller and potentially faster code in projects dependent on Extwee functionality.
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 

package/index.js

@@ -8,6 +8,7 @@ import { parse as parseTWS } from './src/TWS/parse.js';
 import { compile as compileTwine1HTML } from './src/Twine1HTML/compile.js';
 import { compile as compileTwine2HTML } from './src/Twine2HTML/compile.js';
 import { compile as compileTwine2ArchiveHTML } from './src/Twine2ArchiveHTML/compile.js';
+import { compile as compileStoryFormat } from './src/StoryFormat/compile.js';
 import { generate as generateIFID } from './src/IFID/generate.js';
 import { Story } from './src/Story.js';
 import Passage from './src/Passage.js';
@@ -24,6 +25,7 @@ export {
     compileTwine1HTML,
     compileTwine2HTML,
     compileTwine2ArchiveHTML,
+    compileStoryFormat,
     generateIFID,
     Story,
     Passage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extwee",
-  "version": "2.2.5",
+  "version": "2.2.6",
   "description": "A story compiler tool using Twine-compatible formats",
   "author": "Dan Cox",
   "main": "index.js",
@@ -30,28 +30,29 @@
     "node-html-parser": "^7.0.1",
     "pickleparser": "^0.2.1",
     "semver": "^7.7.1",
-    "uuid": "^11.0.5"
+    "uuid": "^11.1.0"
   },
   "devDependencies": {
     "@babel/cli": "^7.26.4",
-    "@babel/core": "^7.26.8",
-    "@babel/preset-env": "^7.26.8",
-    "@eslint/js": "^9.20.0",
+    "@babel/core": "^7.26.10",
+    "@babel/preset-env": "^7.26.9",
+    "@eslint/js": "^9.22.0",
+    "@types/semver": "^7.5.8",
     "@types/uuid": "^10.0.0",
-    "babel-loader": "^9.2.1",
+    "babel-loader": "^10.0.0",
     "clean-jsdoc-theme": "^4.3.0",
-    "core-js": "^3.40.0",
-    "esbuild": "^0.25.0",
-    "eslint": "^9.20.0",
+    "core-js": "^3.41.0",
+    "esbuild": "^0.25.1",
+    "eslint": "^9.22.0",
     "eslint-plugin-jest": "^28.11.0",
-    "eslint-plugin-jsdoc": "^50.6.3",
-    "globals": "^15.14.0",
+    "eslint-plugin-jsdoc": "^50.6.6",
+    "globals": "^16.0.0",
     "jest": "^29.7.0",
     "regenerator-runtime": "^0.14.1",
-    "shelljs": "^0.8.5",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.23.0",
-    "webpack": "^5.97.1",
+    "shelljs": "^0.9.1",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.26.1",
+    "webpack": "^5.98.0",
     "webpack-cli": "^6.0.1"
   },
   "repository": {

package/src/Story.js

@@ -5,7 +5,7 @@ import { encode } from 'html-entities';
 const creatorName = 'extwee';
 
 // Set the creator version.
-const creatorVersion = '2.2.5';
+const creatorVersion = '2.2.6';
 
 /**
  * Story class.
@@ -781,6 +781,15 @@ class Story {
       PIDcounter++;
     });
 
+    // Generate <tw-tag> elements for each tag, if any.
+    const tagList = Object.keys(this.tagColors);
+
+    // For each tag, generate a <tw-tag> element.
+    tagList.forEach((tag) => {
+      // Add the <tw-tag> element.
+      storyData += `\t<tw-tag name="${tag}" color="${this.tagColors[tag]}"></tw-tag>\n`;
+    });
+
     // Close the HTML element.
     storyData += '</tw-storydata>';
 

package/src/StoryFormat/compile.js

@@ -0,0 +1,19 @@
+import StoryFormat from '../StoryFormat.js';
+
+/**
+ * Compiles a {@link StoryFormat} object into a JSONP string for writing to a `format.js` file.
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md Twine 2 Story Formats Specification}
+ * @param {StoryFormat} storyFormat Story format object to compile.
+ * @returns {string} JSONP string.
+ */
+function compile (storyFormat) {
+    // Test if storyFormat is a StoryFormat object.
+    if (!(storyFormat instanceof StoryFormat)) {
+        throw new TypeError('Error: Incoming object is not a storyFormat object');
+    }
+
+    // Create a JSONP string wrapped with the function window.StoryFormat.
+    return `window.storyFormat(${JSON.stringify(storyFormat)})`;
+}
+
+export { compile };

package/src/StoryFormat.js

@@ -1,3 +1,5 @@
+import { valid } from 'semver';
+
 /**
  * StoryFormat representing a Twine 2 story format.
  * 
@@ -85,6 +87,19 @@ export default class StoryFormat {
    */
   #_source = '';
 
+  // Constructor with all parameters.
+  constructor(name = 'Untitled Story Format', version = '', description = '', author = '', image = '', url = '', license = '', proofing = false, source = '') {
+    this.name = name;
+    this.version = version;
+    this.description = description;
+    this.author = author;
+    this.image = image;
+    this.url = url;
+    this.license = license;
+    this.proofing = proofing;
+    this.source = source;
+  }
+
   /**
    * Name
    * @returns {string} Name.
@@ -246,4 +261,40 @@ export default class StoryFormat {
   toString() {
     return JSON.stringify(this, null, "\t");
   }
+
+  /**
+   * Produces a JSON representation of the story format object.
+   * @method toJSON
+   * @returns {object} - A JSON representation of the story format.
+   */
+  toJSON() {
+    // name: (string) Optional. The name of the story format. (Omitting the name will lead to an Untitled Story Format.)
+    // Set a default name.
+    let name = "Untitled Story Format";
+
+    // Check if the story format is not an empty string.
+    if (this.name.length > 0) {
+      // Update the name.
+      name = this.name;
+    }
+
+    // version: (string) Required, and semantic version-style formatting (x.y.z, e.g., 1.2.1) of the version is also required.
+
+    // Check if the version is valid. If not, throw an error.
+    if (!valid(this.version)) {
+      throw new TypeError('ERROR: Version must be a valid semantic version!');
+    }
+
+    return JSON.stringify({
+      name,
+      version: this.version,
+      description: this.description,
+      author: this.author,
+      image: this.image,
+      url: this.url,
+      license: this.license,
+      proofing: this.proofing,
+      source: this.source
+    });
+  }
 }

package/test/Objects/Story.test.js

@@ -819,6 +819,49 @@ describe('Story', () => {
       // Expect the creator to be encoded.
       expect(result.includes(`creator="${creatorName}"`)).not.toBe(true);
     });
+
+    it('Should not encode story tag colors if none are present', () => {
+      // Add passage.
+      s.addPassage(new Passage('Start', 'Word'));
+      // Set start.
+      s.start = 'Start';
+      // Create HTML.
+      const result = s.toTwine2HTML();
+      // Expect the tag colors to not be encoded if none are present.
+      expect(result.includes('<tw-tag')).toBe(false);
+    });
+
+    it('Should encode single story tag color', () => {
+      // Add passage.
+      s.addPassage(new Passage('Start', 'Word'));
+      // Set start.
+      s.start = 'Start';
+      // Add tag colors.
+      s.tagColors = {
+        bar: 'green'
+      };
+      // Create HTML.
+      const result = s.toTwine2HTML();
+      // Expect the tag colors to be encoded.
+      expect(result.includes('<tw-tag name="bar" color="green"></tw-tag>')).toBe(true);
+    });
+
+    it('Should encode multiple story tag colors', () => {
+      // Add passage.
+      s.addPassage(new Passage('Start', 'Word'));
+      // Set start.
+      s.start = 'Start';
+      // Add tag colors.
+      s.tagColors = {
+        bar: 'green',
+        foo: 'red'
+      };
+      // Create HTML.
+      const result = s.toTwine2HTML();
+      // Expect the tag colors to be encoded.
+      expect(result.includes('<tw-tag name="bar" color="green"></tw-tag>')).toBe(true);
+      expect(result.includes('<tw-tag name="foo" color="red"></tw-tag>')).toBe(true);
+    });
   });
 
   describe('toTwine1HTML()', function () {

package/test/Objects/StoryFormat.test.js

@@ -15,6 +15,29 @@ describe('StoryFormat', () => {
     });
   });
 
+  describe('Constructor with default values', () => {
+    it('Should create an instance of StoryFormat', () => {
+      const sf = new StoryFormat();
+      expect(sf).toBeInstanceOf(StoryFormat);
+    });
+  });
+
+  describe('Constructor with parameters', () => {
+    it('Should create an instance of StoryFormat with parameters', () => {
+      const sf = new StoryFormat('name', 'version', 'description', 'author', 'image', 'url', 'license', true, 'source');
+      expect(sf).toBeInstanceOf(StoryFormat);
+      expect(sf.name).toBe('name');
+      expect(sf.version).toBe('version');
+      expect(sf.description).toBe('description');
+      expect(sf.author).toBe('author');
+      expect(sf.image).toBe('image');
+      expect(sf.url).toBe('url');
+      expect(sf.license).toBe('license');
+      expect(sf.proofing).toBe(true);
+      expect(sf.source).toBe('source');
+    });
+  });
+
   describe('name', () => {
     it('Set new String', () => {
       const sf = new StoryFormat();
@@ -153,7 +176,44 @@ describe('StoryFormat', () => {
   describe('toString', () => {
     it('Should return string representation', () => {
       const sf = new StoryFormat();
+      sf.version = '1.0.0';
       expect(sf.toString()).toBe(JSON.stringify(sf, null, '\t'));
     });
+
+    it('Should throw error if version is not valid', () => {
+      const sf = new StoryFormat();
+      expect(() => {
+        sf.toString();
+      }).toThrow();
+    });
+  });
+
+  describe('toJSON', () => {
+    it('Should return JSON representation with default name', () => {
+      const sf = new StoryFormat();
+      sf.version = '1.0.0';
+      expect(sf.toJSON().includes("Untitled Story Format")).toEqual(true);
+    });
+
+    it('Should return JSON representation with custom name', () => {
+      const sf = new StoryFormat();
+      sf.name = 'Custom Name';
+      sf.version = '1.0.0';
+      expect(sf.toJSON().includes("Custom Name")).toEqual(true);
+    });
+
+    it('Should overwrite with default name if name is empty string', () => {
+      const sf = new StoryFormat();
+      sf.name = '';
+      sf.version = '1.0.0';
+      expect(sf.toJSON().includes("Untitled Story Format")).toEqual(true);
+    });
+
+    it('Should throw error if version is not valid', () => {
+      const sf = new StoryFormat();
+      expect(() => {
+        sf.toJSON();
+      }).toThrow();
+    });
   });
 });

package/types/Story.d.ts

@@ -226,5 +226,5 @@ export class Story {
     #private;
 }
 export const creatorName: "extwee";
-export const creatorVersion: "2.2.5";
+export const creatorVersion: "2.2.6";
 import Passage from './Passage.js';

package/types/StoryFormat/compile.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Compiles a {@link StoryFormat} object into a JSONP string for writing to a `format.js` file.
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md Twine 2 Story Formats Specification}
+ * @param {StoryFormat} storyFormat Story format object to compile.
+ * @returns {string} JSONP string.
+ */
+export function compile(storyFormat: StoryFormat): string;
+import StoryFormat from '../StoryFormat.js';

package/types/StoryFormat.d.ts

@@ -30,6 +30,7 @@
  * sf.source = 'New';
  */
 export default class StoryFormat {
+    constructor(name?: string, version?: string, description?: string, author?: string, image?: string, url?: string, license?: string, proofing?: boolean, source?: string);
     /**
      * @param {string} n - Replacement name.
      */
@@ -117,5 +118,11 @@ export default class StoryFormat {
      * @returns {string} - A string representation of the story format.
      */
     toString(): string;
+    /**
+     * Produces a JSON representation of the story format object.
+     * @method toJSON
+     * @returns {object} - A JSON representation of the story format.
+     */
+    toJSON(): object;
     #private;
 }