Merge pull request #15 from ChapelR/dev

v1.3.0

.gitignore

@@ -63,4 +63,5 @@ typings/
 **.sublime-*
 *.bat
 **.zip
-test/
+test/
+src/wrap/min.js

docs/API.md

@@ -1227,4 +1227,130 @@ Dismisses the loading screen.
 
 Completely removes the loading screen from the DOM.
 
----
+---
+
+## The Menu API
+
+---
+
+- **the `A.menu.hide()` method**
+
+- Arguments: none.
+
+- Returns: the `#story-menu` element (jQuery).
+
+Hides the story menu portion of the side bar.
+
+---
+
+- **the `A.menu.show()` method**
+
+- Arguments: none.
+
+- Returns: the `#story-menu` element (jQuery).
+
+Shows the story menu portion of the side bar.
+
+---
+
+- **the `A.menu.isShown()` method**
+
+- Arguments: none.
+
+- Returns: boolean.
+
+Returns whether the story menu portion of the side bar is currently visible.
+
+---
+
+- **the `A.menu.links.add(linkText, [passageName], [callback])` method**
+
+- Arguments: 
+    - `linkText`: (string) the text of the link.
+    - `passageName`: (optional) (string) a passage name to navigate to when the link is clicked.
+    - `callback`: (optional) (string) a function to run when the link is clicked.
+
+- Returns: the generated link (jQuery).
+
+This method creates a story menu link. You must pass it text to display or it will raise an error. You can then pass it a passage name to navigate to, a callback function to run on click, both, or neither. If you include both, they must be included in the indicated order.
+
+---
+
+- **the `A.menu.links.clear()` method**
+
+- Arguments: none.
+
+- Returns: the `#story-menu` element (jQuery).
+
+This method removes all of the links from the story menu.
+
+---
+
+- **the `A.menu.links.hide(text)` method**
+
+- Arguments: 
+    - `text`: the text of the link you want to alter.
+
+- Returns: nothing.
+
+This method hides a story menu link. If there are multiple links with the same link text, all of them will be hidden.
+
+---
+
+- **the `A.menu.links.show(text)` method**
+
+- Arguments: 
+    - `text`: the text of the link you want to alter.
+
+- Returns: nothing.
+
+This method shows a hidden story menu link. If there are multiple links with the same link text, all of them will be shown.
+
+---
+
+- **the `A.menu.links.toggle(text)` method**
+
+- Arguments: 
+    - `text`: the text of the link you want to alter.
+
+- Returns: nothing.
+
+This method toggles the visibility a story menu link (hiding it if it's visible, showing it if it is hidden). If there are multiple links with the same link text, all of them will be toggled.
+
+---
+
+- **the `A.menu.links.remove(text)` method**
+
+- Arguments: 
+    - `text`: the text of the link you want to alter.
+
+- Returns: nothing.
+
+This method removes a story menu link. If there are multiple links with the same link text, all of them will be removed. Hidden links can be re-shown later, removed links are gone for good and will need to be recreated via `A.menu.links.add()`.
+
+---
+
+# Events
+
+## List of Track Events
+
+| Event        | Description                                |
+| ---          | ---                                        |
+| `:available` | a track's metadata is loaded               |
+| `:loaded`    | a track can be played from start to finish |
+| `:play`      | a track starts playing                     |
+| `:pause`     | a track is paused                          |
+| `:stop`      | a track reaches the end or is stopped      |
+| `:mute`      | a track is muted or unmuted                |
+| `:volume`    | a track's volume is changed                |
+
+## List of Master Audio Events
+
+| Event            | Description                                 |
+| ---              | ---                                         |
+| `:master-mute`   | the master mute control is muted or unmuted |
+| `:master-volume` | the master volume is changed                |
+
+## Event Objects
+
+Track event objects are given a `track` property, which contains the track instance that triggered the event.

docs/README.md

@@ -5,7 +5,7 @@
 [Complete API Reference](./API.md)
 
 > [!WARNING]
-> If you're using **Harlowe v3.x (or later)**, some updates to the way the engine preserves state via reloads may cause parts of this library to stop functioning correctly when used outside of the Story JavaScript or equivalent; particularly things that need initialized. There is not much I can do to fix this on my end--for now, it's recommended that you define all your tracks and menu links in Story JavaScript, not in `startup`-tagged passages. All other commands, like playing or stopping audio, should continue to work as expected.
+> If you're using **Harlowe v3.x (or later)**, it is strongly recommended that you define tracks, groups, playlists, and menu links in your Story JavaScript area (or equivalent for your compiler) rather than in `startup`-tagged passages.
 
 If you just need some audio and don't need anything too complex, start at [Installation](#installation) and then read some of the [examples](#detailed-examples) to see if what you want to do is covered. If you want anything more complex than that, or if you have grand, complex ideas, you'll need to read the whole thing.
 
@@ -38,7 +38,7 @@ The best place to ask for help if the issue is on your end is [the Twine Q&A](ht
 
 ## Installation
 
-All you need to install this library is the code. There are two ways to get it: [copy and pasting from GitHub](https://github.com/ChapelR/harlowe-audio/tree/master/dist), or [via a Google Drive download](https://drive.google.com/file/d/1ThjHsBDzAwYNLc0p8g_V1fC-dLhBc8EH/view?usp=sharing). If you download the code, be sure to open it and mess with it in a text editor, *not* a word processor. Once you've got the code, you'll need to put in in your project.
+All you need to install this library is the code. Download the most recent version of HAL here, on the [releases page](https://github.com/ChapelR/harlowe-audio/releases). If you download the code, be sure to open it and mess with it in a text editor, *not* a word processor. Once you've got the code, you'll need to put in in your project.
 
 **In Twine 2 (online or standalone)**, copy and paste the code in `harlowe-audio.min.js` into your [Story JavaScript area](https://twinery.org/wiki/twine2:adding_custom_javascript_and_css), and the code in `harlowe-audio.min.css` into your Story Stylesheet area.
 
@@ -192,7 +192,7 @@ To setup a track, use the `A.newTrack()` method, and provide your track a name a
 A.newTrack('piano', 'http://www.kozco.com/tech/piano2.wav');
 ```
 
-~~You can also use a script element in a `startup`-tagged passage:~~ (See warning below.)
+You can also use a script element in a `startup`-tagged passage (though doing so in your Story JavaScript is still strongly recommended):
 ```
 :: audio-init [startup]
 <script>
@@ -201,9 +201,6 @@ A.newTrack('beep', 'audio/beep.mp3');
 </script>
 ```
 
-> [!DANGER]
-> In Harlowe v3.x, you should **always** define your tracks in your Story JavaScript, or your compiler's equivalent script section.
-
 The *sources* of your audio files are urls or paths to the audio resources. These can be relative paths or absolute paths, depending on your needs.
 
 You should try to provide multiple sources to each sound: they'll be the same sound, just in different file formats, to help improve browser support. For example, most browsers can play `.mp3` files just fine, but Chromium users can't without a special plug-in they may not have. But they can play `.ogg` files, but Safari doesn't support `.ogg`...
@@ -233,9 +230,6 @@ A.preload(); // shows a load screen and dismisses it when the audio has loaded
 </script>
 ```
 
-> [!DANGER]
-> In Harlowe v3.x, you should **always** define your tracks in your Story JavaScript, or your compiler's equivalent script section.
-
 Once you have some tracks set up and named, you're ready to do things with them!
 
 ## Track Methods
@@ -821,10 +815,8 @@ This library adds a loading screen to Harlowe that is superficially similar to S
 > [!TIP]
 > These APIs are completely unavailable if `options.controls.show` is `false`.
 
-?> **TODO:** Add this to the API section. Improve this aspect of the demo. Write code examples.
-
 > [!DANGER]
-> In Harlowe v3.x, you should **always** define your menu links Story JavaScript, or your compiler's equivalent script section.
+> You should **always** define your menu links Story JavaScript, or your compiler's equivalent script section, never in passages.
 
 This API allows you to add links to the sidebar as a 'story menu', similar to what can be done in SugarCube. THese links can be used to navigate to a passage, run a JavaScript function, or both. They can be hidden, shown, toggled, and removed at any time.
 
@@ -1121,16 +1113,13 @@ Then:
 
 ## Looping Background Music
 
-The `<track>.loop()` method can be used to make music loop. If all you're after is a a backing track, this is all you need. Just place it in your JavaScript (after the library) ~~or in a `<script>` in a `startup`-tagged passage element~~:
+The `<track>.loop()` method can be used to make music loop. If all you're after is a a backing track, this is all you need. Just place it in your JavaScript (after the library):
 
 ```javascript
 A.newTrack('theme', 'url/to-you-track.mp3');
 A.track('theme').loop(true).playWhenPossible();
 ```
 
-> [!DANGER]
-> In Harlowe v3.x, you should **always** define your tracks in your Story JavaScript, or your compiler's equivalent script section.
-
 
 That's it; you're done.
 
@@ -1259,9 +1248,6 @@ You can abuse the set macro, however to run code in order:
 <script>A.track('piano').loop(true).playWhenPossible();</script>
 ```
 
-> [!DANGER]
-> In Harlowe v3.x, you should **always** define your tracks in your Story JavaScript, or your compiler's equivalent script section.
-
 The `(set:)` will force the function to be evaluated in order, and the `(print:)` will print `false` as expected. However, this is a hack, and may not be possible in future versions of Harlowe.
 
 I generally recommend using `<script>` elements where ever possible, and only resorting to this trick when there's no other easy way to achieve the desired results.

docs/changelog.md

@@ -1,3 +1,12 @@
+## v1.3.0
+
+This version of HAL should address most issues related to Harlowe v3's refresh/reload persistence for tracks, playlists, and groups. The Menu API calls still need to be set up in Story JavaScript; there's simply too much that can go wrong there.
+
+- Added session persistence for `track`, `playlist`, and `group` instances.
+- Fixed a bug with `track#one()`.
+- Updated documentation.
+- Other internal improvements and updates.
+
 ## v1.2.0
 
 This version adds event handler methods to the `track` prototype and to the root `A` object.

docs/demo/twee/start.twee

@@ -8,23 +8,22 @@
     A.createGroup('tests', 'beep', 'nope');
     A.createGroup('bgm', 'cibelle', 'que-pena');
     A.createPlaylist('bgm', 'cibelle', 'que-pena');
+    A.createPlaylist('test', 'beep', 'nope');
 
     A.preload();
 </script>
 
-:: story-menu [startup]
-<script>
-    A.menu.links.add('Navigate', 'other passage');
-    A.menu.links.add('Alert', function () {
-        alert('This is an alert.');
-    });
-    A.menu.links.add('Both', 'other passage', function () {
-        alert('This is an alert.');
-    });
-    A.menu.links.add('Removes self.', function () {
-        A.menu.links.remove('Removes self.');
-    });
-</script>
+:: story-menu [script]
+A.menu.links.add('Navigate', 'other passage');
+A.menu.links.add('Alert', function () {
+    alert('This is an alert.');
+});
+A.menu.links.add('Both', 'other passage', function () {
+    alert('This is an alert.');
+});
+A.menu.links.add('Removes self.', function () {
+    A.menu.links.remove('Removes self.');
+});
 
 :: Start
 <script>A.playlist('bgm').random().loop(true).playWhenPossible();</script>\
@@ -93,8 +92,31 @@ Tests:
     </script>
 ]
 }
+<!--
+[[stop test]]
+[[playlist test]]
+-->
 
 :: other passage
 This is another passage!
 
-[[Go back.|Start]]
+[[Go back.|Start]]
+
+:: stop test
+<span id='counter-test'>0</span>
+(link-repeat: 'test')[
+    <script>
+        A.track('beep').play();
+        A.track('beep').one(':stop', function () {
+            var x = Number($('#counter-test').text())
+            $('#counter-test').empty().append(++x);
+        });
+    </script>
+]
+
+:: playlist test
+(link-repeat: 'test')[
+    <script>
+        A.playlist('test').loop(true).play();
+    </script>
+]

gulpfile.js

@@ -43,11 +43,30 @@ function rimraf () {
 
 // build functions
 function buildScripts () {
-    return processScripts('./src/*.js', './src/wrap', 'min.js');
+    var jsFiles = [
+        'get.js',
+        'audio.js',
+        'controlpanel.js',
+        'detect.js',
+        'preload.js',
+        'state.js',
+        'setup.js',
+        'userland.js',
+        'fixes.js'
+    ].map( function (file) {
+        return './src/js/' + file;
+    });
+    return processScripts(jsFiles, './src/wrap', 'min.js');
 }
 
 function buildStyles () {
-    return processStyles('./src/*.css', './dist', 'harlowe-audio.min.css');
+    var cssFiles = [
+        'overlay.css',
+        'panel.css'
+    ].map( function (file) {
+        return './src/css/' + file;
+    });
+    return processStyles(cssFiles, './dist', 'harlowe-audio.min.css');
 }
 
 // add js wrapper