Merge branch 'release/5.0.0'

README.md

@@ -2,6 +2,10 @@
 
 # Spin Wheel
 
+[![GitHub tag](https://img.shields.io/github/tag/CrazyTim/spin-wheel)](https://img.shields.io/github/v/tag/CrazyTim/spin-wheel.svg?sort=semver "View latest release")
+![maturity stable badge](https://img.shields.io/badge/maturity-stable-blue)
+[![License](https://img.shields.io/badge/license-MIT-blue)](#license "View license")
+
 An easy to use, themeable component for randomising choices and prizes.
 
 ## Features
@@ -28,20 +32,20 @@ An easy to use, themeable component for randomising choices and prizes.
 - [Spin to a specific item](https://crazytim.github.io/spin-wheel/examples/spin-to-item)
 - [Multiple Wheels](https://crazytim.github.io/spin-wheel/examples/multiple)
 - [Themes](https://crazytim.github.io/spin-wheel/examples/themes)
-- [Developer playground (for testing and troubleshooting)](https://crazytim.github.io/spin-wheel/examples/playground)
+- [Playground (for testing and troubleshooting)](https://crazytim.github.io/spin-wheel/examples/playground)
 
 ## Installation
 
 ### ESM
 
 ```javascript
-import {Wheel} from 'https://cdn.jsdelivr.net/npm/spin-wheel@4.4.0/dist/spin-wheel-esm.js';
+import {Wheel} from 'https://cdn.jsdelivr.net/npm/spin-wheel@5.0.0/dist/spin-wheel-esm.js';
 ```
 
 ### IIFE
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/spin-wheel@4.4.0/dist/spin-wheel-iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/spin-wheel@5.0.0/dist/spin-wheel-iife.js"></script>
 ```
 
 ### Local
@@ -97,7 +101,9 @@ Your options for drawing the pointer are:
 - Overlay an image using `Wheel.overlayImage`
 - Overlay something using the DOM
 
-Feel free to use an image from one of the examples above.
+## Images and fonts
+
+Images are passed as instances of `HTMLImageElement` and should be pre-loaded, otherwise there will be an initial delay (or flicker) while the browser downloads them. Fonts should also be pre-loaded for the same reason. See the [code behind the themes example](https://github.com/CrazyTim/spin-wheel/blob/release/images/examples/themes/js/index.js) for an example of how to pre-load images and fonts.
 
 ## Configuration
 
@@ -133,37 +139,37 @@ Note: setting a property to `undefined` will reset it to the default value.
 
 Name                            | Default Value     | Description
 ------------------------------- | ------------------| ---------------------------
-`borderColor`                   | `'#000'`          | The [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) of the line around the circumference of the wheel.
+`borderColor`                   | `'#000'`          | The [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) for the line around the circumference of the wheel.
 `borderWidth`                   | `0`               | The width (in pixels) of the line around the circumference of the wheel.
-`debug`                         | `false`           | Show debugging info.</p><p>This is particularly helpful when fine-tuning labels.
-`image`                         | `''`              | The url of an image that will be drawn over the center of the wheel which will rotate with the wheel.</p><p>It will be automatically scaled to fit `radius`.
-`isInteractive`                 | `true`            | Allow the user to spin the wheel using click-drag/touch-flick. </p><p>User interaction will only be detected within the bounds of `Wheel.radius`.
+`debug`                         | `false`           | If debugging info will be shown.</p><p>This is helpful when positioning labels.
+`image`                         | `null`            | The image (HTMLImageElement) to draw on the wheel and rotate with the wheel.</p><p>It will be centered and scaled to fit `Wheel.radius`.
+`isInteractive`                 | `true`            | If the user will be allowed to spin the wheel using click-drag/touch-flick.</p><p>User interaction will only be detected within the bounds of `Wheel.radius`.
 `itemBackgroundColors`          | `['#fff']`        | The [CSS colors](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) to use as a repeating pattern for the background colors of all items.</p><p>Overridden by `Item.backgroundColor`.</p><p>Example: `['#fff','#000']`.
-`itemLabelAlign`                | `'right'`         | The alignment of all item labels.</p><p>Accepted values: `'left'`,`'center'`,`'right'`.
+`itemLabelAlign`                | `'right'`         | The alignment of all item labels.</p><p>Possible values: `'left'`,`'center'`,`'right'`.
 `itemLabelBaselineOffset`       | `0`               | The offset of the baseline (or line height) of all item labels (as a percent of the label's height).
 `itemLabelColors`               | `['#000']`        | The [CSS colors](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) to use as a repeating pattern for the colors of all item labels.</p><p>Overridden by `Item.labelColor`.</p><p>Example: `['#fff','#000']`.
-`itemLabelFont`                 | `'sans-serif'`    | The font family for all item labels.</p><p>Example: `'sans-serif'`.
+`itemLabelFont`                 | `'sans-serif'`    | The [font familiy](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family) to use for all item labels.</p><p>Example: `'Helvetica, sans-serif'`.
 `itemLabelFontSizeMax`          | `100`             | The maximum font size (in pixels) for all item labels.
-`itemLabelRadius`               | `0.85`            | The point along the radius (as a percent, starting from the center of the wheel) to start drawing all item labels.
-`itemLabelRadiusMax`            | `0.2`             | The point along the radius (as a percent, starting from the center of the wheel) to calculate the maximum font size for all item labels.
+`itemLabelRadius`               | `0.85`            | The point along the wheel's radius (as a percent, starting from the center) to start drawing all item labels.
+`itemLabelRadiusMax`            | `0.2`             | The point along the wheel's radius (as a percent, starting from the center) to limit the maximum width of all item labels.
 `itemLabelRotation`             | `0`               | The rotation of all item labels.<p></p>Use this in combination with `itemLabelAlign` to flip the labels `180°`.
 `itemLabelStrokeColor`          | `'#fff'`          | The [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) of the stroke applied to the outside of the label text.
 `itemLabelStrokeWidth`          | `0`               | The width of the stroke applied to the outside of the label text.
-`items`                         | `[]`              | The items to show on the wheel.
+`items`                         | `[]`              | The items (or slices, wedges, segments) shown on the wheel.</p><p>Setting this property will re-create all of the items on the wheel based on the objects provided.</p><p>Accessing this property lets you change individual items. For example you could change the background color of an item.
 `lineColor`                     | `'#000'`          | The [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) of the lines between the items.
 `lineWidth`                     | `1`               | The width (in pixels) of the lines between the items.
-`pixelRatio`                    | `0`               | The pixel ratio used to draw the wheel.</p><p>Values above 0 will produce a sharper image at the cost of performance.</p><p>A value of `0` will cause the pixel ratio to be automatically determined using `window.devicePixelRatio`.
-`radius`                        | `0.95`            | The radius of the wheel (as a percent of the container's smallest dimension).
-`rotation`                      | `0`               | The rotation (angle in degrees) of the wheel.</p><p>The first item will be drawn clockwise from this point.
-`rotationResistance`            | `-35`             | The amount that `rotationSpeed` will be reduced by every second. Only in effect when `rotationSpeed !== 0`.</p><p>Set to `0` to spin the wheel infinitely.
-`rotationSpeed`                 | `0`               | (Readonly) How far (angle in degrees) the wheel will spin every 1 second.</p><p>A positive number means the wheel is spinning clockwise, a negative number means anti-clockwise, and `0` means the wheel is not spinning.
-`rotationSpeedMax`              | `250`             | The maximum value for `rotationSpeed` (ignoring the wheel's spin direction).</p><p>The wheel will not spin faster than this value in any direction.
-`offset`                        | `{w: 0, h: 0}`    | The offset of the wheel relative to it's center (as a percent of the wheel's diameter).
+`offset`                        | `{x: 0, y: 0}`    | The offset of the wheel from the center of it's container (as a percent of the wheel's diameter).
 `onCurrentIndexChange`          | `null`            | The callback for the `onCurrentIndexChange` event.
 `onRest`                        | `null`            | The callback for the `onRest` event.
 `onSpin`                        | `null`            | The callback for the `onSpin` event.
-`overlayImage`                  | `''`              | The url of an image that will be drawn over the center of the wheel which will not rotate with the wheel.</p><p>It will be automatically scaled to fit the container's smallest dimension.</p><p>Use this to draw decorations around the wheel, such as a stand or pointer.
-`pointerAngle`                  | `0`               | The angle of the Pointer which is used to determine the `currentIndex` (or the "winning" item).
+`overlayImage`                  | `null`            | The image (HTMLImageElement) to draw over the top of the wheel.</p><p>It will be centered and scaled to fit the container's smallest dimension.</p><p>Use this to draw decorations around the wheel, such as a stand or pointer.
+`pixelRatio`                    | `0`               | The pixel ratio (as a percent) used to draw the wheel.</p><p>Higher values will produce a sharper image at the cost of performance, but the sharpness depends on the current display device.</p><p>A value of `0` will use the pixel ratio of the current display device (see [devicePixelRatio](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio)).
+`pointerAngle`                  | `0`               | The angle of the Pointer which will be used to determine the `currentIndex` (or the "winning" item).
+`radius`                        | `0.95`            | The radius of the wheel (as a percent of the container's smallest dimension).
+`rotation`                      | `0`               | The rotation (angle in degrees) of the wheel.</p><p>The first item will be drawn clockwise from this point.
+`rotationResistance`            | `-35`             | The amount that `rotationSpeed` will be reduced by every second until the wheel stops spinning.</p><p>Set to `0` to spin the wheel infinitely.
+`rotationSpeed`                 | `0`               | [Readonly] How fast (angle in degrees) the wheel is spinning every 1 second.</p><p>A positive number means the wheel is spinning clockwise, a negative number means anti-clockwise, and `0` means the wheel is not spinning.
+`rotationSpeedMax`              | `250`             | The maximum absolute value for `rotationSpeed`.</p><p>The wheel will not spin faster than this value in either direction.
 
 ## Events for `Wheel`
 
@@ -193,12 +199,12 @@ Raised when the wheel has been spun.
 Key                         | Value
 --------------------------- | ---------------------------
 `type`                      | `'spin'`
-`duration`                  | the duration of the spin animation. Only set when `method = spinto` or `method = spintoitem`.
+`duration`                  | The duration of the spin animation. Only provided when `method = spinto` or `method = spintoitem`.
 `method`                    | The method that was used to spin the wheel (`interact`, `spin`, `spinto`, `spintoitem`).
-`rotationResistance`        | The value of `Wheel.rotationResistance` at the time the event was raised.</p><p>Only set when `method = interact` or `method = spin`.
-`rotationSpeed`             | The value of `Wheel.rotationSpeed` at the time the event was raised.</p><p>Only set when `method = interact` or `method = spin`.
-`targetItemIndex`           | The item that the Pointer will be pointing at once the spin animation has finished.</p><p>Only set when `method = spintoitem`.
-`targetRotation`            | The value that `Wheel.rotation` will have once the spin animation has finished.</p><p>Only set when `method = spinto` or `method = spintoitem`.
+`rotationResistance`        | The value of `Wheel.rotationResistance` at the time the event was raised.</p><p>Only provided when `method = interact` or `method = spin`.
+`rotationSpeed`             | The value of `Wheel.rotationSpeed` at the time the event was raised.</p><p>Only provided when `method = interact` or `method = spin`.
+`targetItemIndex`           | The item that the Pointer will be pointing at once the spin animation has finished.</p><p>Only provided when `method = spintoitem`.
+`targetRotation`            | The value that `Wheel.rotation` will have once the spin animation has finished.</p><p>Only provided when `method = spinto` or `method = spintoitem`.
 
 ## Methods for `Item`
 
@@ -218,11 +224,11 @@ Note: setting a property to `undefined` will reset it to the default value.
 Name                            | Default Value     | Description
 ------------------------------- | ----------------- | ---------------------------
 `backgroundColor`               | `null`            | The [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) of the item's background.</p><p>When `null`, the color will fall back to `Wheel.itemBackgroundColors`.</p><p>Example: `'#fff'`.
-`image`                         | `null`            | The url of an image that will be drawn on the item. Any part of the image that extends outside the item will be clipped. The image will be drawn over the top of `Item.backgroundColor`.
-`imageOpacity`                  | `1`               | The opacity (as a percent) of `Item.image`. Useful if you want to fade the image to make the item's label stand out.
-`imageRadius`                   | `0.5`             | The point along the radius (as a percent, starting from the center of the wheel) to draw the center of `Item.image`.
+`image`                         | `null`            | The image (HTMLImageElement) to draw on the item.</p><p>Any part of the image that extends outside the item will be clipped. The image will be drawn over the top of `Item.backgroundColor`.
+`imageOpacity`                  | `1`               | The opacity (as a percent) of `Item.image`.</p><p>Useful if you want to fade the image to make the item's label stand out.
+`imageRadius`                   | `0.5`             | The point along the wheel's radius (as a percent, starting from the center) to draw the center of `Item.image`.
 `imageRotation`                 | `0`               | The rotation (angle in degrees) of `Item.image`.
-`imageScale`                    | `1`               | The scale (as a percent) to resize `Item.image`.
+`imageScale`                    | `1`               | The scale (size as a percent) of `Item.image`.
 `label`                         | `''`              | The text that will be drawn on the item.
 `labelColor`                    | `null`            | The [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) of the item's label.</p><p>When `null`, the color will fall back to `Wheel.itemLabelColors`.</p><p>Example: `'#000'`.
 `value`                         | `null`            | Some value that has meaning to your application. For example, a reference to the object representing the item on the wheel, or a database id.

examples/playground/css/index.css

@@ -2,7 +2,7 @@
   margin: 0;
   padding: 0;
   font-family: 'Lucida Grande', sans-serif;
-  font-size: 15px;
+
   -webkit-tap-highlight-color: transparent;
   user-select: none; /* Prevent selecting ui text when dragging */
 }
@@ -22,10 +22,13 @@ body {
   /* Prevent browser from handling touch events */
   touch-action: none;
 
-  display: flex;
-  flex-direction: row;
+  display: grid;
+  grid-template-columns: 1fr min-content;
   justify-items: stretch;
   align-items: stretch;
+
+  font-size: 0.95em;
+  --padding: 12px;
 }
 
 .frame-center {
@@ -36,6 +39,9 @@ body {
 }
 
 .wheel-wrapper {
+  /* Hide UI during page load */
+  visibility: hidden;
+
   overflow: hidden;
   height: 100%;
   width: 100%;
@@ -45,9 +51,8 @@ body {
   background-color: #f0f0ee;
   display: flex;
   flex-direction: column;
-  gap: 10px;
+  gap: var(--padding);
   overflow-y: scroll;
-  width: 460px;
   border-left: solid 1px #5c5c5c;
   padding-bottom: 15px;
 }
@@ -56,6 +61,7 @@ button.btn, label.btn {
   padding: 4px 8px;
   margin: 0px;
   font-family: inherit;
+  font-size: inherit;
   display: inline-block;
   cursor: pointer;
   background-color: white;
@@ -67,26 +73,30 @@ button.btn, label.btn {
 .input-group {
   display: flex;
   flex-direction: column;
-  gap: 10px;
-  padding: 0 10px;
+  gap: calc(var(--padding) * 0.7);
+  padding: 0 var(--padding);
   border-top: solid 1px #5c5c5c;
 }
 
 .input-group h2 {
-  display: block;
+  font-size: 1.1em;
+  display: flex;
   font-family: monospace;
   /* background-color: #dfdfdb; */
-  padding: 10px 0px 0px;
+  padding: var(--padding) 0px 0px;
   font-weight: normal;
   white-space: nowrap;
 }
 .input-group h2 span:first-of-type {
   display: inline-block;
   font-family: inherit;
+  user-select: text;
 }
 .input-group h2 span:last-of-type {
   margin-left:7px;
   font-family: inherit;
+  width: 40px; /* fixed width so the panel can be auto sized */
+  user-select: text;
 }
 
 .input-group input[type="range"] {
@@ -112,7 +122,7 @@ button.btn, label.btn {
 }
 
 .input-group button {
-  margin-top: 10px;
+  margin-top: var(--padding);
 }
 
 select {
@@ -125,10 +135,24 @@ label {
 
 .toolbar {
   position: absolute;
-  top: 10px;
-  right: 15px;
+  top: 0;
+  right: 0;
+  left: 0;
+  padding: var(--padding);
+  text-align: right;
 }
 
 .btn.clear {
   display: none;
+}
+
+/*************************************************/
+/*************************************************/
+@media only screen and (max-width: 450px) {
+
+  body {
+    font-size: .85em;
+    --padding: 10px;
+  }
+
 }

examples/playground/index.html

@@ -26,11 +26,11 @@
       <div class="input-group" data-name="image" data-type="image"></div>
       <div class="input-group" data-name="isInteractive" data-type="checkbox"></div>
       <div class="input-group" data-name="itemBackgroundColors" data-type="textboxArray"></div>
-      <div class="input-group" data-name="itemLabelAlign" data-type="textbox"></div>
+      <div class="input-group" data-name="itemLabelAlign" data-type="select" data-options="left|right|center"></div>
       <div class="input-group" data-name="itemLabelBaselineOffset" data-type="range" data-min="-50" data-max="50" data-multiplier="0.01"></div>
       <div class="input-group" data-name="itemLabelColors" data-type="textboxArray"></div>
       <div class="input-group" data-name="itemLabelFont" data-type="textbox"></div>
-      <div class="input-group" data-name="itemLabelFontSizeMax" data-type="range" data-min="10" data-max="100"></div>
+      <div class="input-group" data-name="itemLabelFontSizeMax" data-type="range" data-min="10" data-max="150"></div>
       <div class="input-group" data-name="itemLabelRadius" data-type="range" data-min="0" data-max="100" data-multiplier="0.01"></div>
       <div class="input-group" data-name="itemLabelRadiusMax" data-type="range" data-min="0" data-max="100" data-multiplier="0.01"></div>
       <div class="input-group" data-name="itemLabelRotation" data-type="range" data-min="0" data-max="359"></div>

examples/playground/js/index.js

@@ -1,2 +1,5 @@
 import './initWheel.js';
-import './initEventListeners.js';
+import './initEventListeners.js';
+
+// Show the wheel once everything has loaded
+document.querySelector('.wheel-wrapper').style.visibility = 'visible';