extwee 2.2.6 → 2.3.1

package/test/Objects/Story.test.js

@@ -229,6 +229,45 @@ describe('Story', () => {
     });
   });
 
+  describe('storyStylesheet', () => {
+    let s = null;
+
+    beforeEach(() => {
+      s = new Story();
+    });
+
+    it('Set storyStylesheet', () => {
+      s.storyStylesheet = 'Test';
+      expect(s.storyStylesheet).not.toBe('');
+    });
+
+    it('Should throw error if not String', () => {
+      expect(() => {
+        s.storyStylesheet = 1;
+      }).toThrow();
+    }
+    );
+  });
+
+  describe('storyJavaScript', () => {
+    let s = null;
+
+    beforeEach(() => {
+      s = new Story();
+    });
+
+    it('Set storyJavaScript', () => {
+      s.storyJavaScript = 'Test';
+      expect(s.storyJavaScript).not.toBe('');
+    });
+
+    it('Should throw error if not String', () => {
+      expect(() => {
+        s.storyJavaScript = 1;
+      }).toThrow();
+    });
+  });
+
   describe('passages', () => {
     let s = null;
 
@@ -442,6 +481,30 @@ describe('Story', () => {
       // Should have a single passage.
       expect(result.passages.length).toBe(1);
     });
+
+    it('Should have style data', function () {
+      // Create default Story.
+      const s = new Story();
+      // Add a stylesheet.
+      s.storyStylesheet = 'Test';
+      // Convert to JSON and then back to object.
+      const result = JSON.parse(s.toJSON());
+      // Should have a stylesheet.
+      expect(result.style).toBe('Test');
+    }
+    );
+
+    it('Should have script data', function () {
+      // Create default Story.
+      const s = new Story();
+      // Add a script.
+      s.storyJavaScript = 'Test';
+      // Convert to JSON and then back to object.
+      const result = JSON.parse(s.toJSON());
+      // Should have a script.
+      expect(result.script).toBe('Test');
+    }
+    );
   });
 
   describe('toTwee()', function () {
@@ -647,6 +710,48 @@ describe('Story', () => {
       // Test for passage text.
       expect(p[0].text).toBe('Test');
     });
+
+    it('Should encode story stylesheet as passage with "stylesheet" tag', () => {
+      // Add passages.
+      s.storyStylesheet = 'Test';
+
+      // Set IFID.
+      s.IFID = 'DE7DF8AD-E4CD-499E-A4E7-C5B98B73449A';
+
+      // Convert into Twee.
+      const t = s.toTwee();
+
+      // Convert back into Story.
+      const story = parseTwee(t);
+
+      // Search for 'stylesheet'.
+      const p = story.getPassagesByTag('stylesheet');
+
+      // Test for passage text.
+      expect(p[0].text).toBe('Test');
+    }
+    );
+
+    it('Should encode story JavaScript as passage with "script" tag', () => {
+      // Add passages.
+      s.storyJavaScript = 'Test';
+
+      // Set IFID.
+      s.IFID = 'DE7DF8AD-E4CD-499E-A4E7-C5B98B73449A';
+
+      // Convert into Twee.
+      const t = s.toTwee();
+
+      // Convert back into Story.
+      const story = parseTwee(t);
+
+      // Search for 'stylesheet'.
+      const p = story.getPassagesByTag('script');
+
+      // Test for passage text.
+      expect(p[0].text).toBe('Test');
+    }
+    );
   });
 
   describe('toTwine2HTML()', () => {
@@ -695,6 +800,19 @@ describe('Story', () => {
       expect(result.includes('<style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css">Word')).toBe(true);
     });
 
+    it('Should encode stylesheet property', () => {
+      // Add passage.
+      s.addPassage(new Passage('Start', 'Word'));
+      // Set start.
+      s.start = 'Start';
+      // Set stylesheet.
+      s.storyStylesheet = 'Test';
+      // Create HTML.
+      const result = s.toTwine2HTML();
+      // Expect the stylesheet passage text to be encoded.
+      expect(result.includes('<style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css">Test')).toBe(true);
+    });
+
     it('Should encode script passages', () => {
       // Add passage.
       s.addPassage(new Passage('Start', 'Word'));
@@ -708,6 +826,19 @@ describe('Story', () => {
       expect(result.includes('<script role="script" id="twine-user-script" type="text/twine-javascript">Word')).toBe(true);
     });
 
+    it('Should encode script property', () => {
+      // Add passage.
+      s.addPassage(new Passage('Start', 'Word'));
+      // Set start.
+      s.start = 'Start';
+      // Set script.
+      s.storyJavaScript = 'Test';
+      // Create HTML.
+      const result = s.toTwine2HTML();
+      // Expect the script passage text to be encoded.
+      expect(result.includes('<script role="script" id="twine-user-script" type="text/twine-javascript">Test')).toBe(true);
+    });
+
     it('Should encode format', () => {
       // Add passage.
       s.addPassage(new Passage('Start', 'Word'));

package/test/TWS/Parse.test.js

@@ -7,28 +7,6 @@ describe('TWSParser', () => {
       expect(() => { parseTWS(0); }).toThrow();
     });
 
-    describe('Story parsing', function () {
-      let r = null;
-
-      beforeAll(() => {
-        const contents = fs.readFileSync('test/TWS/TWSParser/Example1.tws');
-        //const b = Buffer.from(contents, 'binary');
-        r = parseTWS(contents);
-      });
-
-      it('Should parse StoryTitle', function () {
-        expect(r.name).toBe('Untitled Story');
-      });
-
-      it('Should parse zoom', function () {
-        expect(r.zoom).toBe(1);
-      });
-
-      it('Should parse start passage', function () {
-        expect(r.start).toBe('Start');
-      });
-    });
-
     describe('Passage parsing', function () {
       let r = null;
 

package/test/Web/window.Extwee.test.js

@@ -0,0 +1,85 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import '../../web-index.js';
+
+describe('Extwee', () => {
+    it('should have all the expected properties', () => {
+        expect(window.Extwee).toHaveProperty('parseTwee');
+        expect(window.Extwee).toHaveProperty('parseJSON');
+        expect(window.Extwee).toHaveProperty('parseTWS');
+        expect(window.Extwee).toHaveProperty('parseStoryFormat');
+        expect(window.Extwee).toHaveProperty('parseTwine1HTML');
+        expect(window.Extwee).toHaveProperty('parseTwine2HTML');
+        expect(window.Extwee).toHaveProperty('parseTwine2ArchiveHTML');
+        expect(window.Extwee).toHaveProperty('compileTwine1HTML');
+        expect(window.Extwee).toHaveProperty('compileTwine2HTML');
+        expect(window.Extwee).toHaveProperty('compileTwine2ArchiveHTML');
+        expect(window.Extwee).toHaveProperty('generateIFID');
+        expect(window.Extwee).toHaveProperty('Story');
+        expect(window.Extwee).toHaveProperty('Passage');
+        expect(window.Extwee).toHaveProperty('StoryFormat');
+    });
+
+    it('should have the expected types', () => {
+        expect(typeof window.Extwee.parseTwee).toBe('function');
+        expect(typeof window.Extwee.parseJSON).toBe('function');
+        expect(typeof window.Extwee.parseTWS).toBe('function');
+        expect(typeof window.Extwee.parseStoryFormat).toBe('function');
+        expect(typeof window.Extwee.parseTwine1HTML).toBe('function');
+        expect(typeof window.Extwee.parseTwine2HTML).toBe('function');
+        expect(typeof window.Extwee.parseTwine2ArchiveHTML).toBe('function');
+        expect(typeof window.Extwee.compileTwine1HTML).toBe('function');
+        expect(typeof window.Extwee.compileTwine2HTML).toBe('function');
+        expect(typeof window.Extwee.compileTwine2ArchiveHTML).toBe('function');
+        expect(typeof window.Extwee.generateIFID).toBe('function');
+        expect(typeof window.Extwee.Story).toBe('function');
+        expect(typeof window.Extwee.Passage).toBe('function');
+        expect(typeof window.Extwee.StoryFormat).toBe('function');
+    });
+
+    it('should have the expected properties in StoryFormat', () => {
+        const storyFormat = new window.Extwee.StoryFormat();
+        expect(storyFormat).toHaveProperty('name');
+        expect(storyFormat).toHaveProperty('version');
+        expect(storyFormat).toHaveProperty('description');
+        expect(storyFormat).toHaveProperty('author');
+        expect(storyFormat).toHaveProperty('image');
+        expect(storyFormat).toHaveProperty('url');
+        expect(storyFormat).toHaveProperty('license');
+        expect(storyFormat).toHaveProperty('proofing');
+        expect(storyFormat).toHaveProperty('source');
+    });
+
+    it('should have the expected properties in Story', () => {
+        const story = new window.Extwee.Story();
+        expect(story).toHaveProperty('name');
+        expect(story).toHaveProperty('IFID');
+        expect(story).toHaveProperty('start');
+        expect(story).toHaveProperty('format');
+        expect(story).toHaveProperty('formatVersion');
+        expect(story).toHaveProperty('zoom');
+        expect(story).toHaveProperty('passages');
+        expect(story).toHaveProperty('creator');
+        expect(story).toHaveProperty('creatorVersion');
+        expect(story).toHaveProperty('metadata');
+        expect(story).toHaveProperty('tagColors');
+        expect(story).toHaveProperty('storyJavaScript');
+        expect(story).toHaveProperty('storyStylesheet');
+    });
+   
+    it('should have the expected types in Passage', () => {
+        const passage = new window.Extwee.Passage();
+        expect(passage).toHaveProperty('name');
+        expect(passage).toHaveProperty('text');
+        expect(passage).toHaveProperty('tags');
+        expect(passage).toHaveProperty('metadata');
+    });
+
+    it('should generate a valid IFID', () => {
+        const ifid = window.Extwee.generateIFID();
+        expect(ifid).toMatch(/^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/);
+    });
+
+});

package/types/Story.d.ts

@@ -13,6 +13,8 @@
  * @property {string} creatorVersion - Version used to create Story.
  * @property {object} metadata - Metadata of Story.
  * @property {object} tagColors - Tag Colors
+ * @property {string} storyJavaScript - Story JavaScript
+ * @property {string} storyStylesheet - Story Stylesheet
  * @method {number} addPassage - Add a passage to the story and returns the new length of the passages array.
  * @method {number} removePassageByName - Remove a passage from the story by name and returns the new length of the passages array.
  * @method {Array} getPassagesByTag - Find passages by tag.
@@ -142,6 +144,25 @@ export class Story {
      * @property {Array} passages - Passages
     */
     get passages(): any[];
+    /**
+     * @param {string} s - Replacement story stylesheet
+     */
+    set storyStylesheet(s: string);
+    /**
+     * Story stylesheet data can be set as a passage, property value, or both.
+     * @returns {string} storyStylesheet
+     */
+    get storyStylesheet(): string;
+    /**
+     * Set story JavaScript.
+     * @param {string} s - Replacement story JavaScript
+     */
+    set storyJavaScript(s: string);
+    /**
+     * Get story JavaScript.
+     * @returns {string} storyJavaScript
+     */
+    get storyJavaScript(): string;
     /**
      * Add a passage to the story.
      * Passing `StoryData` will override story metadata and `StoryTitle` will override story name.
@@ -209,6 +230,10 @@ export class Story {
      * - `format`: (string) Optional. The format of the story.
      * - `format-version`: (string) Optional. The version of the format of the story.
      *
+     * Because story stylesheet data can be represented as a passage, property value, or both, all approaches are encoded.
+     *
+     * Because story JavaScript can be represented as a passage, property value, or both, all approaches are encoded.
+     *
      * @method toTwine2HTML
      * @returns {string} Twine 2 HTML string
      */

package/types/index.d.ts

@@ -8,7 +8,9 @@ import { parse as parseTwine2ArchiveHTML } from './src/Twine2ArchiveHTML/parse.j
 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 Story from './src/Story.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';
 import StoryFormat from './src/StoryFormat.js';
-export { parseTwee, parseJSON, parseTWS, parseStoryFormat, parseTwine1HTML, parseTwine2HTML, parseTwine2ArchiveHTML, compileTwine1HTML, compileTwine2HTML, compileTwine2ArchiveHTML, Story, Passage, StoryFormat };
+export { parseTwee, parseJSON, parseTWS, parseStoryFormat, parseTwine1HTML, parseTwine2HTML, parseTwine2ArchiveHTML, compileTwine1HTML, compileTwine2HTML, compileTwine2ArchiveHTML, compileStoryFormat, generateIFID, Story, Passage, StoryFormat };

package/types/src/CLI/CommandLineProcessing.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Process command line arguments.
+ * @function CommandLineProcessing
+ * @description This function processes the command line arguments passed to the Extwee CLI.
+ * @module CLI/commandLineProcessing
+ * @param {Array} argv - The command line arguments passed to the CLI.
+ */
+export function CommandLineProcessing(argv: any[]): void;

package/types/src/CLI/ProcessConfig/loadStoryFormat.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Load the story format from the story-formats directory.
+ * @function loadStoryFormat
+ * @description This function loads the story format from the story-formats directory.
+ * It checks if the story-formats directory exists, if the named story format exists,
+ * if the version directory exists, and if the format.js file exists.
+ * If any of these checks fail, the function will exit the process with an error message.
+ * If all checks pass, the function will return the contents of the format.js file.
+ * @param {string} storyFormatName - The name of the story format.
+ * @param {string} storyFormatVersion - The version of the story format.
+ * @returns {string} - The contents of the format.js file.
+ * @throws {Error} - If the story-formats directory does not exist, if the named story format does not exist,
+ * if the version directory does not exist, or if the format.js file does not exist.
+ * @example
+ * // Load the story format from the story-formats directory.
+ * const storyFormat = loadStoryFormat('Harlowe', '3.2.0');
+ * console.log(storyFormat);
+ * // Output: The contents of the format.js file.
+ */
+export function loadStoryFormat(storyFormatName: string, storyFormatVersion: string): string;

package/types/src/CLI/ProcessConfig/readDirectories.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Read the contents of a directory and returns all directories.
+ * @function readDirectories
+ * @description This function reads the contents of a directory and returns a list of directories.
+ * @param {string} directory - The path to the directory to read.
+ * @returns {Array<string>} - An array of directories in the directory.
+ * @throws {Error} - If the directory does not exist or if there is an error reading the directory.
+ */
+export function readDirectories(directory: string): Array<string>;

package/types/src/CLI/ProcessConfig.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Processes the config file, if present.
+ * @function ConfigFileProcessing
+ * @description This function processes the config file.
+ * It checks if the config file exists and if it does, it reads the config file.
+ * If the config file does not exist, the function will exit the process with an error message.
+ * The config file is used to store configuration options for the Extwee CLI.
+ * @returns {void}
+ * @throws {Error} - If the config file does not exist or if there is an error parsing the config file.
+ */
+export function ConfigFileProcessing(): void;
+export function ConfigFilePresent(): boolean;

package/types/src/CLI/isDirectory.d.ts

@@ -0,0 +1 @@
+export function isDirectory(path: any): boolean;

package/types/src/CLI/isFile.d.ts

@@ -0,0 +1 @@
+export function isFile(path: any): boolean;

package/types/src/Config/parser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parses a JSON object and extracts the StoryFormat, StoryTitle and StoryVersion.
+ * @param {object} obj Incoming JSON object.
+ * @returns {object} An object containing the extracted results.
+ */
+export function parser(obj: object): object;

package/types/src/Config/reader.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Read a JSON file and return its contents.
+ * @param {string} path Path to the JSON file.
+ * @returns {object} Parsed JSON object.
+ * @throws {Error} If the file does not exist.
+ * @throws {Error} If the file is not a valid JSON file.
+ * @example
+ * const contents = reader('test/Config/files/valid.json');
+ * console.log(contents); // {"story-format": 'Harlowe', "story-title": "My Story"}
+ */
+export function reader(path: string): object;

package/types/src/IFID/generate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Generates an Interactive Fiction Identification (IFID) based the Treaty of Babel.
+ *
+ * For Twine works, the IFID is a UUID (v4) in uppercase.
+ * @see Treaty of Babel ({@link https://babel.ifarchive.org/babel_rev11.html#the-ifid-for-an-html-story-file})
+ * @function generate
+ * @description Generates a new IFID.
+ * @returns {string} IFID
+ * @example
+ * const ifid = generate();
+ * console.log(ifid);
+ * // => 'A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6'
+ */
+export function generate(): string;

package/types/src/JSON/parse.d.ts

@@ -1,8 +1,51 @@
 /**
  * Parse JSON representation into Story.
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-jsonoutput-doc.md Twine 2 JSON Specification}
  * @function parse
  * @param {string} jsonString - JSON string to convert to Story.
+ * @throws {Error} - Invalid JSON!
  * @returns {Story} Story object.
+ * @example
+ * const jsonString = `{
+ *  "name": "My Story",
+ *  "start": "First Passage",
+ *  "ifid": "A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6",
+ *  "format": "SugarCube",
+ *  "formatVersion": "2.31.0",
+ *  "creator": "Twine",
+ *  "creatorVersion": "2.3.9",
+ *  "zoom": 1,
+ *  "passages": [
+ *   {
+ *    "name": "First Passage",
+ *    "tags": "",
+ *    "metadata": "",
+ *    "text": "This is the first passage."
+ *   },
+ *  ]
+ * }`;
+ * const story = parse(jsonString);
+ * console.log(story);
+ * // => Story {
+ * //      name: 'My Story',
+ * //      start: 'First Passage',
+ * //      IFID: 'A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6',
+ * //      format: 'SugarCube',
+ * //      formatVersion: '2.31.0',
+ * //      creator: 'Twine',
+ * //      creatorVersion: '2.3.9',
+ * //      zoom: 1,
+ * //      tagColors: {},
+ * //      metadata: {},
+ * //      passages: [
+ * //        Passage {
+ * //          name: 'First Passage',
+ * //          tags: '',
+ * //          metadata: '',
+ * //          text: 'This is the first passage.'
+ * //        }
+ * //      ]
+ * //    }
  */
 export function parse(jsonString: string): Story;
-import Story from '../Story.js';
+import { Story } from '../Story.js';

package/types/src/Passage.d.ts

@@ -1,6 +1,40 @@
 /**
- * A passage is the smallest unit of a Twine story.
- */
+  * Passage class.
+  * @class
+  * @classdesc Represents a passage in a Twine story.
+  * @property {string} name - Name of the passage.
+  * @property {Array} tags - Tags for the passage.
+  * @property {object} metadata - Metadata for the passage.
+  * @property {string} text - Text content of the passage.
+  * @method {string} toTwee - Return a Twee representation.
+  * @method {string} toJSON - Return JSON representation.
+  * @method {string} toTwine2HTML - Return Twine 2 HTML representation.
+  * @method {string} toTwine1HTML - Return Twine 1 HTML representation.
+  * @example
+  * const p = new Passage('Start', 'This is the start of the story.');
+  * console.log(p.toTwee());
+  * // :: Start
+  * // This is the start of the story.
+  * //
+  * console.log(p.toJSON());
+  * // {"name":"Start","tags":[],"metadata":{},"text":"This is the start of the story."}
+  * console.log(p.toTwine2HTML());
+  * // <tw-passagedata pid="1" name="Start" tags="" >This is the start of the story.</tw-passagedata>
+  * console.log(p.toTwine1HTML());
+  * // <div tiddler="Start" tags="" modifier="extwee" twine-position="10,10">This is the start of the story.</div>
+  * @example
+  * const p = new Passage('Start', 'This is the start of the story.', ['start', 'beginning'], {position: '10,10', size: '100,100'});
+  * console.log(p.toTwee());
+  * // :: Start [start beginning] {"position":"10,10","size":"100,100"}
+  * // This is the start of the story.
+  * //
+  * console.log(p.toJSON());
+  * // {"name":"Start","tags":["start","beginning"],"metadata":{"position":"10,10","size":"100,100"},"text":"This is the start of the story."}
+  * console.log(p.toTwine2HTML());
+  * // <tw-passagedata pid="1" name="Start" tags="start beginning" position="10,10" size="100,100">This is the start of the story.</tw-passagedata>
+  * console.log(p.toTwine1HTML());
+  * // <div tiddler="Start" tags="start beginning" modifier="extwee" twine-position="10,10">This is the start of the story.</div>
+  */
 export default class Passage {
     /**
      * Create a passage.
@@ -12,6 +46,7 @@ export default class Passage {
     constructor(name?: string, text?: string, tags?: any[], metadata?: object);
     /**
      * @param {string} s - Name to replace
+     * @throws {Error} Name must be a String!
      */
     set name(s: string);
     /**
@@ -21,6 +56,7 @@ export default class Passage {
     get name(): string;
     /**
      * @param {Array} t - Replacement array
+     * @throws {Error} Tags must be an array!
      */
     set tags(t: any[]);
     /**
@@ -30,15 +66,17 @@ export default class Passage {
     get tags(): any[];
     /**
      * @param {object} m - Replacement object
+     * @throws {Error} Metadata must be an object literal!
      */
-    set metadata(m: any);
+    set metadata(m: object);
     /**
      * Metadata
      * @returns {object} Metadata
      */
-    get metadata(): any;
+    get metadata(): object;
     /**
      * @param {string} t - Replacement text
+     * @throws {Error} Text should be a String!
      */
     set text(t: string);
     /**
@@ -48,23 +86,30 @@ export default class Passage {
     get text(): string;
     /**
      * Return a Twee representation.
+     *
+     * See: https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md
+     *
+     * @method toTwee
      * @returns {string} String form of passage.
      */
     toTwee(): string;
     /**
      * Return JSON representation.
+     * @method toJSON
      * @returns {string} JSON string.
      */
     toJSON(): string;
     /**
      * Return Twine 2 HTML representation.
      * (Default Passage ID is 1.)
+     * @method toTwine2HTML
      * @param {number} pid - Passage ID (PID) to record in HTML.
      * @returns {string} Twine 2 HTML string.
      */
     toTwine2HTML(pid?: number): string;
     /**
      * Return Twine 1 HTML representation.
+     * @method toTwine1HTML
      * @returns {string} Twine 1 HTML string.
      */
     toTwine1HTML(): string;