Merge pull request #38 from ChapelR/v2.6.0

v2.6.0

Author: ChapelR

.gitignore

@@ -46,9 +46,10 @@ Network Trash Folder
 Temporary Items
 .apdisk
 
-/old
-/node_modules
-build.bat
+old/
+node_modules/
+**.bat
 **.sublime-*
-
-test/
+**.log
+test/
+proto/

.jshintignore

@@ -0,0 +1 @@
+scripts/minified/

build.js

@@ -1,21 +1,34 @@
-// build me
+// jshint esversion: 6, node: true
 
-var jetpack = require('fs-jetpack'),
+const jetpack = require('fs-jetpack'),
     Terser  = require('terser');
 
+
+
+const buildDate = new Date().toISOString().split('T')[0],
+    buildID = require('git-commit-id')();
+
 function build () {
-    var jsFiles = jetpack.find('./scripts', {
+    const jsFiles = jetpack.find('./scripts', {
         matching : '*.js',
         recursive : false
     });
 
-    jsFiles.forEach( function (file) {
-        var source = jetpack.read(file),
-            path   = file.split(/[\\\/]/g),
-            name   = path.pop().split('.').join('.min.'),
-            result, ret;
+    jsFiles.forEach( file => {
+        const source = jetpack.read(file);
+        let path = file.split(/[\\\/]/g);
+
+        const name = path.pop().split('.').join('.min.');
+
+        let version = source.match(/(v|version\s+)(\d+\.\d+.\d+)/);
+        if (version == null) {
+            version = '0.0.0';
+            console.log(`missing version info: ${file}`);
+        } else {
+            version = version[2];
+        }
 
-        result = Terser.minify(source);
+        const result = Terser.minify(source);
 
         console.log(result.error);
 
@@ -24,7 +37,7 @@ function build () {
         path.push(name);
         path = path.join('/');
 
-        ret = '// ' + name + ', for SugarCube 2, by Chapel\n;' + result.code + '\n// end ' + name; 
+        const ret = `// ${name}, for SugarCube 2, by Chapel\n// v${version}, ${buildDate}, ${buildID}\n;${result.code}\n// end ${name}`;
 
         jetpack.write(path, ret, {atomic : true});
     });

docs/README.md

@@ -1,38 +1,40 @@
-## Chapel's Custom Macro Collection (v2.5.5)
+## Chapel's Custom Macro Collection (v2.6.0)
 
-- [Try the demo!](https://macros.twinelab.net/demo)
+- [Try the demo!](https://macros.twinelab.net/demo) ([Sausage](https://github.com/ChapelR/custom-macros-demo))
 - [Downloads](./download ':ignore')
-- [Changelog](./changelog.md)
+- [Changelog](changelog.md)
 - [Release Notes](https://twinelab.net/blog/tags/macros/)
 
 ### Documentation
 - **Gameplay Systems and Mechanics**
-  - [The Simple Inventory System](./simple-inventory.md)
-  - [The Cycles System](./cycles-system.md)
-  - [The Playtime System](./playtime-system.md)
+  - [The Simple Inventory System](simple-inventory.md)
+  - Updated [The Cycles System](cycles-system.md) 
+  - [The Playtime System](playtime-system.md)
 - **Interface and Style**
-  - [The Dialog API Macro Set](./dialog-api-macro-set.md)
-  - [The UI Macro](./ui-macro.md)
-  - [The Fading Macro Set](./fading-macros.md)
-  - [The CSS Macro](./css-macro.md)
-  - [The Notify Macro](./notify-macro.md)
-  - [The Meter Macro Set](./meter-macros.md)
-  - [The Speech Box System](./speech-box-system.md)
+  - [The Dialog API Macro Set](dialog-api-macro-set.md)
+  - New [The Popover Macro](popover.md)
+  - [The UI Macro](ui-macro.md)
+  - [The Fading Macro Set](fading-macros.md)
+  - [The CSS Macro](css-macro.md)
+  - [The Notify Macro](notify-macro.md)
+  - [The Meter Macro Set](meter-macros.md)
+  - [The Speech Box System](speech-box-system.md)
 - **User Interaction and Events**
-  - [The Event Macros](./event-macros.md)
-  - [The Continue Macro Set](./continue-macro.md)
-  - [The Swap Macro Set](./swap-macro-set.md)
-  - [The Mouseover Macro](./mouseover-macro.md)
-  - [The Message Macro](./message-macro.md)
-  - [The Typing Simulation Macro](./type-sim.md)
+  - [The Event Macros](event-macros.md)
+  - [The Continue Macro Set](continue-macro.md)
+  - [The Swap Macro Set](swap-macro-set.md)
+  - [The Mouseover Macro](mouseover-macro.md)
+  - [The Message Macro](message-macro.md)
+  - [The Typing Simulation Macro](type-sim.md)
 - **Grammar and Language**
-  - [The Pronoun Templates](./pronoun-templates.md)
-  - [The Articles (A/An) Macros](./articles.md)
+  - [The Pronoun Templates](pronoun-templates.md)
+  - [The Articles (A/An) Macros](articles.md)
 - **Utilities and Other**
-  - [The Done Macro](./done-macro.md)
-  - [The File System Macro Set](./file-system-macros.md)
-  - [The First Macro](./first-macro.md)
-  - [Dice Roller and Fairmath Functions](./operations-api.md)
+  - New [The Preload Macro](preload.md)
+  - [The Done Macro](done-macro.md)
+  - [The File System Macro Set](file-system-macros.md)
+  - [The First Macro](first-macro.md)
+  - [Dice Roller and Fairmath Functions](operations-api.md)
 
 ### Installation Guide
 

docs/changelog.md

@@ -2,6 +2,15 @@
 
 [Back to the main page](./README.md).
 
+### July 24, 2020 (v2.6.0)
+
+- **[New]** New macros.
+  - Added the preload macro for preloading images.
+  - Added the popover macro for creating special transparent dialogs and splash screens.
+- **[Meta]** Repository changes.
+  - Overhauled build and code quality check processes.
+  - Spun out demo project into its own repo.
+
 ### June 28, 2020 (v2.5.5)
 
 - **[Update]** Updated `Cycle.check()` and `cycle#check()` to accept multiple phases to check.

docs/demo/index.html

@@ -18,7 +18,7 @@ The `<<dialog>>` macro creates a new dialog box, with an optional title and an o
 
  * **title**: (optional) A title to appear at the top of the dialog box.  If you want to omit a title but include classes, this argument can be an empty string (`''`).
  * **classList**: (optional) A list of CSS classes to add to the dialog, for styling.  The classes should be a space-separated list of quoted class names (i.e. `'class-a' 'class-b' 'class-c'`), a quoted list of space-separated class names (i.e. `'class-a class-b class-c'`), or one or more string arrays (i.e. `['class-a', 'class-b', 'class-c']`), or any combination of thereof.
- 
+
 **Usage**:
 ```
 /% creates a link that opens a dialog box called 'Character Sheet' with the classes .char-sheet and .stats %/
@@ -90,8 +90,9 @@ The `<<popup>>` macro provides a similar result to what you might get by pairing
  * **passageName**: The name of one of your passages.  The indicated passage's content will be rendered into the dialog box's body.
  * **title**: (optional) A title to appear at the top of the dialog box.  If you want to omit a title but include classes, this argument can be an empty string (`''`).
  * **classList**: (optional) A list of CSS classes to add to the dialog, for styling.  The classes should be a space-separated list of quoted class names (i.e. `'class-a' 'class-b' 'class-c'`), a quoted list of space-separated class names (i.e. `'class-a class-b class-c'`), or one or more string arrays (i.e. `['class-a', 'class-b', 'class-c']`), or any combination of thereof.
- 
+
 **Usage**:
+
 ```
 /% 
 	creates a link that opens a dialog box called 'Character Sheet' 
@@ -106,4 +107,26 @@ The `<<popup>>` macro provides a similar result to what you might get by pairing
 <<button 'About'>>
 	<<popup 'credits-passage' 'Credits'>>
 <</button>>
-```
+```
+
+### Macro: `<<dialogclose>>`
+
+**Syntax**: `<<dialogclose>>`
+
+Closes the dialog.
+
+**Usage**:
+
+```
+<<link 'View Character Sheet'>>
+	<<dialog 'Character Sheet' 'char-sheet stats'>>\
+		|Strength|$str|
+		|Dexterity|$dex|
+		|Wisdom|$wis|\
+	@@float:right;
+		<<button "Close">><<dialogclose>><</button>>
+    @@
+	<</dialog>>
+<</link>>
+```
+

docs/dialog-api-macro-set.md

@@ -16,10 +16,10 @@
         'The Fading Macro Set' : 'fading-macro-set',
         'The First Macro' : 'first-macro',
         'File System Macros' : 'fs',
-        // 'Fullscreen Macros' : 'fullscreen',
         'The Message Macro' : 'message-macro',
         'The Meters Macro Set' : 'meters',
         'The Mouseover Macro' : 'mouseover',
+        'The Popover Macro' : 'popover+css',
         'The Notify Macro' : 'notify+css',
         'Dice Roller and Fairmath Functions' : 'operations',
         'Playtime System' : 'playtime',
@@ -28,7 +28,8 @@
         'The Speech Box System' : 'speech+css',
         'Swap Macro Set' : 'swap-macro-set',
         'The Typesim Macro' : 'type-sim',
-        'The UI Macro' : 'ui-macro'
+        'The UI Macro' : 'ui-macro',
+        'The Preload Macro' : 'preload'
     };
 
     var macros = Object.keys(fileNameMap);

docs/download/fetch.js

@@ -0,0 +1,72 @@
+## The Popover Macro
+
+[Back to the main readme](./README.md).
+
+Creates a special transparent dialog modal for images and text.
+
+![The Popover Macro](https://i.imgur.com/vW7soRX.png)
+
+**THE CODE:** [Minified](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/minified/popover.min.js). [Pretty](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/popover.js).  
+**DEMO:** [Available](http://macros.twinelab.net/demo?macro=popover).  
+**GUIDE:** Not available.
+
+### Macro: `<<popover>>`
+
+**Syntax**: `<<popover [flags] [classList]>><</popover>>`
+
+The `<<popover>>` macro creates a special transparent dialog modal for images and text, rendering the content between its tags into this special dialog element. Like a normal dialog, clicking on the overlay closes the popover, but this behavior may be suppressed. There are also a few additional options and you may add custom classes as well.
+
+**Arguments**:
+
+ * **flags**: (optional) A list of options for the popover. Valid options are:
+    * `opaque`: makes the overlay opaque (alpha: 1). By default it's alpha is 0.8.
+    * `transparent`: makes the overlay totally transparent (alpha: 0). By default it's alpha is 0.8. The overlay will still block user interaction from occurring on whatever is behind it, and will still, by default, dismiss the popover when clicked.
+    * `noclick`: by default, clicks on the overlay close the popover. This option suppresses this behavior, meaning users will only be able to close the popover with the `X` button at the top right of the screen.
+    * `invert`: inverts the colors of the overlay and it's default text color. By default the overlay is dark and the text is light. This does not effect the opacity of the overlay.
+ * **classList**: (optional) A list of CSS classes to add to the popover, for styling. These classes are added to `#ui-overlay`, `#ui-dialog`, and `#ui-dialog-body`.  The classes should be a space-separated list of quoted class names (i.e. `'class-a' 'class-b' 'class-c'`), a quoted list of space-separated class names (i.e. `'class-a class-b class-c'`), or one or more string arrays (i.e. `['class-a', 'class-b', 'class-c']`), or any combination of thereof.
+
+**Usage**:
+
+```
+<<popover 'invert' 'opaque'>>Hi there!<</popover>>
+
+<<popover 'transparent' 'my-class'>>[img[assets/my-img.png]]<</popover>>
+
+<<popover 'my-class'>>[img[assets/my-img.png]]<</popover>>
+
+<<popover 'noclick'>>[[Move on]]<</popover>>
+
+<<popover>>Welcome!<</popover>>
+```
+
+### Macro: `<<dismisspopover>>`
+
+**Syntax**: `<<dismisspopover>>`
+
+Closes the popover dialog. Can't be used to close other dialogs, but functions, methods, or macros that close other dialogs should generally also be able to close popovers, so `Dialog.close()` should work fine if you prefer.
+
+**Usage**:
+
+```
+<<popover>>\
+	Hi there! Welcome to my game!
+	
+	<<button "Continue">><<dismisspopover>><</button>>
+<</popover>>
+```
+
+### Function: `setup.popover()`
+
+**Syntax**: `setup.popover(content [, flagsAndClasses])`
+
+A JavaScript function that is essentially the same as the `<<popover>>` macro
+
+**Arguments**:
+
+ * **content**: the content to render in the popover.
+ * **flags**: (optional) A list of options for the popover. Valid options are:
+    * `opaque`: makes the overlay opaque (alpha: 1). By default it's alpha is 0.8.
+    * `transparent`: makes the overlay totally transparent (alpha: 0). By default it's alpha is 0.8.
+    * `noclick`: by default, clicks on the overlay close the popover. This option suppresses this behavior, meaning users will only be able to close the popover with the `X` button at the top right of the screen.
+    * `invert`: inverts the colors of the overlay and it's default text color. By default the overlay is dark and the text is light. This does not effect the opacity of the overlay.
+ * **classList**: (optional) A list of CSS classes to add to the popover, for styling. These classes are added to `#ui-overlay`, `#ui-dialog`, and `#ui-dialog-body`.  The classes should be a space-separated list of quoted class names (i.e. `'class-a' 'class-b' 'class-c'`), a quoted list of space-separated class names (i.e. `'class-a class-b class-c'`), or one or more string arrays (i.e. `['class-a', 'class-b', 'class-c']`), or any combination of thereof.

docs/popover.md

@@ -0,0 +1,50 @@
+## The Preload Macro
+
+[Back to the main readme](./README.md).
+
+This macro allows you to preload image resources.
+
+**THE CODE:** [Minified](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/minified/preload.min.js). [Pretty](https://github.com/ChapelR/custom-macros-for-sugarcube-2/blob/master/scripts/preload.js).  
+**DEMO:** [Available](http://macros.twinelab.net/demo?macro=preload).  
+**GUIDE:** Not available.
+
+### Macro: `<<preload>>`
+
+**Syntax:** `<<preload urls>>`
+
+This macro will preload a list of image resources so that they will be available and not have to take time to download as they are encountered during play. In general, only important or necessary images should be preloaded, and because the process of preloading merely moves the downloads to startup rather than eliminating them, preloading too many images or extremely large images can cause startup times to become excessive.  Still, judicious use of this macro can help a game feel snappier and more performant.
+
+> [!DANGER]
+> The `<<preload>>` macro will throw an error if used outside of the `StoryInit` special passage (or equivalent). If you absolutely need to preload at some other time, set `setup.preload.force` to `true`. This is not recommended, and only included as an option for bizarre use-cases.
+
+**Arguments:**
+
+- `urls` ( *`string`* | *`string array`* ) A list of URL paths to image resources to preload. You may pass individual URLs as separate arguments, or as an array, or as any combination of the two.
+
+**Usage:**
+
+```
+<<preload 'assets/lisa/jpg' 'assets/bob.jgp'>>
+
+/* you can also provide the arguments as an array if you prefer */
+<<preload `['assets/lisa/jpg', 'assets/bob.jgp']`>>
+```
+
+### Function: `setup.preload()`
+
+**Syntax:** `setup.preload(urls)`
+
+This function does exactly the same thing as `<<preload>>` and is subject to the exact same restrictions.
+
+**Arguments:**
+
+- `urls` ( *`string`* | *`string array`* ) A list of URL paths to image resources to preload. You may pass individual URLs as separate arguments, or as an array, or as any combination of the two.
+
+**Usage:**
+
+```
+setup.preload('assets/lisa/jpg', 'assets/bob.jgp');
+
+// you can also provide the arguments as an array if you prefer
+setup.preload(['assets/lisa/jpg', 'assets/bob.jgp'])
+```