Improve docs and fix bug with specifying window size when not using M…

…ilkdrop
captbaritone · May 8, 2024 · 025f9e7 · 025f9e7
1 parent 946b57a
commit 025f9e7
Show file tree

Hide file tree

Showing 10 changed files with 219 additions and 80 deletions.
diff --git a/examples/minimalMilkdrop/index.html b/examples/minimalMilkdrop/index.html
@@ -13,7 +13,7 @@
     <script src="https://unpkg.com/[email protected]/lib/butterchurnPresets.min.js"></script>
     <script>
       const Webamp = window.Webamp;
-      new Webamp({
+      const webamp = new Webamp({
         initialTracks: [
           {
             metaData: {
@@ -46,7 +46,8 @@
           playlist: { position: { x: 0, y: 232 }, size: [0, 4] },
           milkdrop: { position: { x: 275, y: 0 }, size: [7, 12] },
         },
-      }).renderWhenReady(document.getElementById("app"));
+      });
+      webamp.renderWhenReady(document.getElementById("app"));
     </script>
   </body>
 </html>
diff --git a/examples/minimalWindowLayout/README.md b/examples/minimalWindowLayout/README.md
@@ -0,0 +1,11 @@
+# Minimal Example Window Layout
+
+This example demonstrates configuring the initial layout of windows in Webamp.
+
+You should be able to open this local html file in your browser and see Webamp working.
+
+```
+$ git clone [email protected]:captbaritone/webamp.git
+$ cd webamp
+$ open examples/minimalWindowLayout/index.html
+```
diff --git a/examples/minimalWindowLayout/index.html b/examples/minimalWindowLayout/index.html
@@ -0,0 +1,40 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+  </head>
+
+  <body>
+    <div id="app" style="height: 100vh">
+      <!-- Webamp will attempt to center itself within this div -->
+    </div>
+    <script src="https://unpkg.com/[email protected]/built/webamp.bundle.min.js"></script>
+    <script>
+      const Webamp = window.Webamp;
+      const webamp = new Webamp({
+        windowLayout: {
+          main: {
+            position: { top: 0, left: 0 },
+            shadeMode: true,
+            closed: false,
+          },
+          equalizer: {
+            position: { top: 230, left: 0 },
+            shadeMode: true,
+            closed: false,
+          },
+          playlist: {
+            position: { top: 28, left: 0 },
+            shadeMode: false,
+            size: { extraHeight: 3, extraWidth: 11 },
+            closed: false,
+          },
+        },
+        enableDoubleSizeMode: true,
+      });
+
+      // Returns a promise indicating when it's done loading.
+      webamp.renderWhenReady(document.getElementById("app"));
+    </script>
+  </body>
+</html>
diff --git a/examples/readme.md b/examples/readme.md
@@ -5,6 +5,7 @@ This directory contains a number of examples of how to add Webamp to a project.
 - [Minimal](./minimal) Stick Webamp in a `<script>` tag, and add a few lines of JavaScript to get Webamp on your page.
 - [Multiple Tracks](./multipleTracks) An example of setting up Webamp with multiple audio tracks.
 - [Multiple Skins](./multipleSkins) An example of setting up Webamp with multiple skins.
+- [Minimal Window Layout](./minimalWindowLayout) An example of configuring the initial layout of windows in Webamp.
 - [Webpack](./webpack) Install Webamp via NPM and bundle it in a Webpack bundle.
 - [Webpack Lazyload](./webpackLazyLoad) **In progress**
 - [Minimal Milkdrop](./minimalMilkdrop) **In progress**

diff --git a/examples/webpackLazyLoad/index.js b/examples/webpackLazyLoad/index.js
@@ -1,6 +1,6 @@
 import Webamp from "webamp";
 
-new Webamp({
+const webamp = new Webamp({
   initialTracks: [
     {
       metaData: {
@@ -40,4 +40,6 @@ new Webamp({
     playlist: { position: { x: 0, y: 232 }, size: [0, 4] },
     milkdrop: { position: { x: 275, y: 0 }, size: [7, 12] },
   },
-}).renderWhenReady(document.getElementById("app"));
+});
+
+webamp.renderWhenReady(document.getElementById("app"));
diff --git a/packages/webamp/CHANGELOG.md b/packages/webamp/CHANGELOG.md
@@ -3,9 +3,14 @@
 ### Features
 
 - Allow a single mouse drag across the EQ to set all values [#1180](https://github.com/captbaritone/webamp/pull/1180)
-- Configure the initial layout of windows -- size, position, openness, shade mode -- when constructing a Webamp instance.
-- Configure if "double size mode" should be enabled when constructing a Webamp instance.
+- Configure the initial layout of windows -- size, position, openness, shade mode -- when constructing a Webamp instance. See `windowLayout` in the [Usage](./docs/usage.md) docs for more information.
+- Configure if "double size mode" should be enabled when constructing a Webamp instance. See `enableDoubleSizeMode` in the [Usage](./docs/usage.md) docs for more information.
 - Optically allow users to lazily load heavy dependencies like JSZip and music-metadata-browser with the `webamp/lazy` entry point.
+- Include source maps for non-minified bundles.
+
+### Bug Fixes
+
+- Fix bug where track position slider could get stuck on mobile. [PR](https://github.com/captbaritone/webamp/pull/1253)
 
 ### Internal Improvements:
 

diff --git a/packages/webamp/demo/js/webampConfig.ts b/packages/webamp/demo/js/webampConfig.ts
@@ -67,7 +67,7 @@ export async function getWebampConfig(
   if (isButterchurnSupported()) {
     const startWithMilkdropHidden = skinUrl != null || screenshot;
 
-    __butterchurnOptions = getButterchurnOptions(startWithMilkdropHidden);
+    __butterchurnOptions = undefined; // getButterchurnOptions(startWithMilkdropHidden);
 
     if (
       startWithMilkdropHidden ||
@@ -112,7 +112,25 @@ export async function getWebampConfig(
       ? SoundCloud.tracksFromPlaylist(soundCloudPlaylist)
       : initialTracks,
     availableSkins,
-    windowLayout,
+    windowLayout: {
+      main: {
+        position: { top: 0, left: 0 },
+        shadeMode: true,
+        closed: false,
+      },
+      equalizer: {
+        position: { top: 230, left: 0 },
+        shadeMode: true,
+        closed: false,
+      },
+      playlist: {
+        position: { top: 28, left: 0 },
+        shadeMode: false,
+        size: { extraHeight: 3, extraWidth: 11 },
+        closed: false,
+      },
+    },
+    enableDoubleSizeMode: true,
     filePickers: [dropboxFilePicker],
     enableHotkeys: true,
     handleTrackDropEvent: (e) => {

diff --git a/packages/webamp/docs/usage.md b/packages/webamp/docs/usage.md
@@ -4,10 +4,15 @@ Here's how to use Webamp in your own project. If you get stuck, or need help, pl
 
 ## Examples
 
-If you would like to look at some examples check out the [examples directory](../examples/) where you will find:
+If you would like to look at some examples check out the [examples directory](../../../examples/) where you will find:
 
-- [Minimal](../examples/minimal/) - An example that just uses a `<script>` tag that points to a CDN. No install required.
-- [Webpack](../examples/webpack/) - An example that installs Webamp via NPM, and bundles it into an application using Webpack.
+- [Minimal](../../../examples/minimal) Stick Webamp in a `<script>` tag, and add a few lines of JavaScript to get Webamp on your page.
+- [Multiple Tracks](../../../examples/multipleTracks) An example of setting up Webamp with multiple audio tracks.
+- [Multiple Skins](../../../examples/multipleSkins) An example of setting up Webamp with multiple skins.
+- [Minimal Window Layout](../../../examples/minimalWindowLayout) An example of configuring the initial layout of windows in Webamp.
+- [Webpack](../../../examples/webpack) Install Webamp via NPM and bundle it in a Webpack bundle.
+- [Webpack Lazyload](../../../examples/webpackLazyLoad) **In progress**
+- [Minimal Milkdrop](../../../examples/minimalMilkdrop) **In progress**
 
 Each example has a README which explains it in more detail.
 
@@ -128,75 +133,118 @@ if(Winamp.browserIsSupported()) {
 
 The `Winamp` class is constructed with an options object. All are optional.
 
-```JavaScript
+```ts
 const options = {
-    // Optional. An object representing the initial skin to use.
-    // If omitted, the default skin, included in the bundle, will be used.
-    // Note: This URL must be served the with correct CORs headers.
-    initialSkin: {
-        url: './path/to/skin.wsz'
-    },
+  // Optional. An object representing the initial skin to use.
+  // If omitted, the default skin, included in the bundle, will be used.
+  // Note: This URL must be served the with correct CORs headers.
+  initialSkin: {
+    url: "./path/to/skin.wsz",
+  },
 
-    // Optional. An array of `track`s (see above) to prepopulate the playlist with.
-    initialTracks: [/* ... */],
-
-    // Optional. An array of objects representing skins.
-    // These will appear in the "Options" menu under "Skins".
-    // Note: These URLs must be served with the correct CORs headers.
-    availableSkins: [
-      { url: "./green.wsz", name: "Green Dimension V2" },
-      { url: "./osx.wsz", name: "Mac OSX v1.5 (Aqua)" }
-    ],
-
-    // Optional. (Default: `false`) Should double size mode be enabled?
-    enableDoubleSizeMode: true,
-
-    // Optional. (Default: `false`) Should global hotkeys be enabled?
-    enableHotkeys: true,
-
-    // Optional. (Default: `0`) The zIndex that Webamp should use.
-    zIndex: 99999,
-
-    // Optional. An array of additional file pickers.
-    // These will appear in the "Options" menu under "Play".
-    // In the demo site, This option is used to provide a "Dropbox" file
-    // picker.
-    filePickers: [{
-        // The name that will appear in the context menu.
-        contextMenuName: "My File Picker...",
-        // A function which returns a Promise that resolves to
-        // an array of `track`s (see above)
-        filePicker: () => Promise.resolve([{
-            url: './rick_roll.mp3'
-        }]),
-        // A boolean indicating if this options should be made
-        // available when the user is offline.
-        requiresNetwork: true
-    }],
-
-    // Optional. Provide a custom way to derive `Track` objects from a drop event.
-    // Useful if your website has some DOM representation of a track that you can map to a URL/blob.
-    handleTrackDropEvent: async (e) => {
-        // Return an array of `Track` objects, see documentation below, or `null` to get the default drop behavior.
-        // You may optionally wrap the return value in a promise.
-    },
+  // Optional. An array of `track`s (see above) to prepopulate the playlist with.
+  initialTracks: [
+    /* ... */
+  ],
+
+  // Optional. An array of objects representing skins.
+  // These will appear in the "Options" menu under "Skins".
+  // Note: These URLs must be served with the correct CORs headers.
+  availableSkins: [
+    { url: "./green.wsz", name: "Green Dimension V2" },
+    { url: "./osx.wsz", name: "Mac OSX v1.5 (Aqua)" },
+  ],
 
-    // Optional. Provide a way to extend the behavior of the button ADD URL.
-    // **Since** 1.4.1
-    handleAddUrlEvent: async () => {
-        // Return an optional array of `Track` objects or null.
+  // Optional. An object representing the initial layout of the windows.
+  // Valid keys are `main`, `equalizer`, `playlist` and `milkdrop`. All windows
+  // are optional.
+  //
+  // - Each provided window must specify a `position` object with `top` and
+  //   `left` which specify pixel offsets.
+  // - Each provided window, except for
+  // `milkdrop` may specify a `shadeMode` boolean.
+  // - Each provided window may specify a `closed` boolean.
+  // - The playlist and milkdrop windows may specify a `size` object with
+  //   `extraHeight` and `extraWidth`.
+  //
+  // **Note:** After windows are positioned, they are then centered _as a group_ within the
+  // DOM element that Webamp is rendered into.
+  windowLayout: {
+    main: {
+      position: { top: 0, left: 0 },
+      shadeMode: true,
+      closed: false,
+    },
+    equalizer: {
+      position: { top: 0, left: 0 },
+      shadeMode: true,
+      closed: false,
+    },
+    playlist: {
+      position: { top: 0, left: 0 },
+      shadeMode: true,
+      // Number of additional sprites by which to expand the window.
+      size: { extraHeight: 1, extraHeight: 10 },
+      closed: false,
     },
+  },
+
+  // Optional. (Default: `false`) Should double size mode be enabled?
+  // **Note:** In keeping with the original Winamp, double size mode
+  // does not apply to resizable windows like the equalizer or Milkdrop.
+  enableDoubleSizeMode: true,
+
+  // Optional. (Default: `false`) Should global hotkeys be enabled?
+  enableHotkeys: true,
 
-    // Optional. Provide a way to extend the behavior of the playlist button LOAD LIST.
-    // **Since** 1.4.1
-    handleLoadListEvent: async () => {
-        // Return an optional array of `Track` objects or null.
+  // Optional. (Default: `0`) The zIndex that Webamp should use.
+  zIndex: 99999,
+
+  // Optional. An array of additional file pickers.
+  // These will appear in the "Options" menu under "Play".
+  // In the demo site, This option is used to provide a "Dropbox" file
+  // picker.
+  filePickers: [
+    {
+      // The name that will appear in the context menu.
+      contextMenuName: "My File Picker...",
+      // A function which returns a Promise that resolves to
+      // an array of `track`s (see above)
+      filePicker: () =>
+        Promise.resolve([
+          {
+            url: "./rick_roll.mp3",
+          },
+        ]),
+      // A boolean indicating if this options should be made
+      // available when the user is offline.
+      requiresNetwork: true,
     },
+  ],
+
+  // Optional. Provide a custom way to derive `Track` objects from a drop event.
+  // Useful if your website has some DOM representation of a track that you can map to a URL/blob.
+  handleTrackDropEvent: async (e) => {
+    // Return an array of `Track` objects, see documentation below, or `null` to get the default drop behavior.
+    // You may optionally wrap the return value in a promise.
+  },
+
+  // Optional. Provide a way to extend the behavior of the button ADD URL.
+  // **Since** 1.4.1
+  handleAddUrlEvent: async () => {
+    // Return an optional array of `Track` objects or null.
+  },
+
+  // Optional. Provide a way to extend the behavior of the playlist button LOAD LIST.
+  // **Since** 1.4.1
+  handleLoadListEvent: async () => {
+    // Return an optional array of `Track` objects or null.
+  },
 
-    // Optional. Provide a way to extend the behavior of the playlist button SAVE LIST.
-    // Where tracks: Track[]
-    // **Since** 1.4.1
-    handleSaveListEvent: (tracks) => {}
+  // Optional. Provide a way to extend the behavior of the playlist button SAVE LIST.
+  // Where tracks: Track[]
+  // **Since** 1.4.1
+  handleSaveListEvent: (tracks) => {},
 };
 const webamp = new Webamp(options);
 ```

diff --git a/packages/webamp/js/reducers/windows.ts b/packages/webamp/js/reducers/windows.ts
@@ -80,6 +80,16 @@ const defaultWindowsState: WindowsState = {
       hotkey: "Alt+E",
       position: { x: 0, y: 0 },
     },
+    [WINDOWS.MILKDROP]: {
+      title: "Milkdrop",
+      size: [0, 0],
+      open: false,
+      shade: false,
+      canResize: true,
+      canShade: false,
+      canDouble: false,
+      position: { x: 0, y: 0 },
+    },
   },
   browserWindowSize: { width: 0, height: 0 },
   windowOrder: [
@@ -101,14 +111,8 @@ const windows = (
         genWindows: {
           ...state.genWindows,
           [WINDOWS.MILKDROP]: {
-            title: "Milkdrop",
-            size: [0, 0],
+            ...state.genWindows[WINDOWS.MILKDROP],
             open: action.open,
-            shade: false,
-            canResize: true,
-            canShade: false,
-            canDouble: false,
-            position: { x: 0, y: 0 },
           },
         },
       };