@decidables/decidables-elements 0.0.2 → 0.1.0

package/README.md

@@ -1,25 +1,279 @@
 <!--lint ignore first-heading-level-->
 
-# decidables-elements: Basic UI Web Components for [**decidables**](https://github.com/decidables/decidables)
+# **`@decidables/decidables-elements`**<br>Web Components for Basic UI in [**decidables**](https://decidables.github.io)
+
+[![npm version](https://img.shields.io/npm/v/@decidables/decidables-elements?logo=npm)](https://www.npmjs.com/package/@decidables/decidables-elements)
+[![license](https://img.shields.io/npm/l/@decidables/decidables-elements?color=informational)](https://github.com/decidables/decidables/blob/main/LICENSE.md)
+
+This package provides basic user interface web components for use in all of the explorables. This
+facilitates a consistent look and feel. They try to use the native inputs when possible, but build
+on them for new elements like a switch, and composite elements like a slider with a linked spinner.
+
+## Usage
+
+### Install
+
+```shell
+yarn add @decidables/decidables-elements
+```
+
+### Use
+
+```javascript
+import '@decidables/decidables-elements';
+```
+
+A bare import is used to register the elements in the custom registry, so they are then available
+for use in HTML.
 
 ## Contents
 
-- Base class
-  - `DecidablesElement`: Base class for all *decidables* web components
-- Elements
-  - `DecidablesButton`: Button for taking actions
-  - `DecidablesSlider`: Slider w/spinner for selecting a numeric value from a range
-  - `DecidablesSpinner`: Text field w/spinner arrows for selecting a continuous numeric value
-  - `DecidablesSwitch`: Switch for turning an option on or off
-  - `DecidablesToggle`: Toggle for selecting one option from a set
-  - `DecidablesToggleOption`: One option in a toggle set
-- Utilities
-  - `DecidablesConverterArray`: Utility for attributes that can take an array of values
-  - `DecidablesConverterSet`: Utility for attributes that can take a set of values
+### Components
+
+#### `DecidablesButton` / `<decidables-button>`
+
+Button for taking actions
+
+##### Slots
+
+- *unnamed*
+  - Inline content as label
+
+##### Attributes
+
+- `disabled: boolean = false`
+  - In disabled state user can't interact
+
+##### Example
+
+```html
+<decidables-button disabled>
+  Click me
+</decidables-button>
+```
+
+#### `DecidablesSlider` / `<decidables-slider>`
+
+Slider w/spinner for selecting a numeric value from a range
+
+##### Slots
+
+- *unnamed*
+  - Inline content as label
+
+##### Attributes
+
+- `disabled: boolean = false`
+  - In disabled state user can't interact
+- `max: number = undefined`
+  - Maximum value the slider can take
+- `min: number = undefined`
+  - Minimum value the slider can take
+- `step: number = undefined`
+  - Amount that value increments with smallest movement of the slider
+- `value: number = undefined`
+  - Initial value of the slider
+
+##### Example
+
+```html
+<decidables-slider disabled max="0" min="100" step="2" value="50">
+  Move me
+</decidables-slider>
+```
+
+#### `DecidablesSpinner` / `<decidables-spinner>`
+
+Text field w/spinner arrows for selecting a continuous numeric value
+
+##### Slots
+
+- *unnamed*
+  - Inline content as label
+
+##### Attributes
+
+- `disabled: boolean = false`
+  - In disabled state user can't interact
+- `max: number = undefined`
+  - Maximum value the slider can take
+- `min: number = undefined`
+  - Minimum value the slider can take
+- `step: number = undefined`
+  - Amount that value increments with smallest movement of the slider
+- `value: number = undefined`
+  - Initial value of the slider
+
+##### Example
+
+```html
+<decidables-spinner disabled max="0" min="100" step="2" value="50">
+  Change me
+</decidables-spinner>
+```
+
+#### `DecidablesSwitch` / `<decidables-switch>`
+
+Switch for turning an option on or off
+
+##### Slots
+
+- *unnamed*
+  - Inline content as label for **on** state
+- `off-label`
+  - Inline content as label for **off** state
+
+##### Attributes
+
+- `disabled: boolean = false`
+  - In disabled state user can't interact
+- `checked: number = false`
+  - Whether the switch is **on** (`true`) or **off** (`false`)
+
+##### Example
+
+```html
+<decidables-switch disabled checked>
+  <span>On</span>
+  <span slot="off-label">Off</span>
+</decidables-switch>
+```
 
----
+#### `DecidablesToggleOption` / `<decidables-toggle-option>`
 
-## Features/Bugs/Notes
+One option in a toggle set
+
+##### Slots
+
+- *unnamed*
+  - Inline content as label for option
+
+##### Attributes
+
+- `disabled: boolean = false`
+  - In disabled state user can't interact
+- `checked: number = false`
+  - Whether the option is selected (`true`) or not ('false`)
+- `name: string = undefined`
+  - An identifier to be shared by all options in a mutually exclusive group
+- `value: string = undefined`
+  - An identifier specific to this option to uniquely identify it in the group
+
+##### Example
+
+```html
+<decidables-toggle-option disabled name="flavors" value="chocolate" checked>
+  Chocolate
+</decidables-toggle-option>
+```
+
+#### `DecidablesToggle` / `<decidables-toggle>`
+
+Toggle for selecting one option from a set
+
+##### Slots
+
+- *unnamed*
+  - Inline content as label for set
+- `label`
+  - Inline content as legend for options
+
+##### Attributes
+
+- `disabled: boolean = false`
+  - In disabled state user can't interact
+
+##### Example
+
+```html
+<decidables-toggle disabled>
+  <span>Pick one</span>
+  <span slot="label">Flavors</span>
+  <decidables-toggle-option disabled name="flavors" value="chocolate">
+    Chocolate
+  </decidables-toggle-option>
+  <decidables-toggle-option disabled name="flavors" value="strawberry">
+    Strawberry
+  </decidables-toggle-option>
+  <decidables-toggle-option disabled name="flavors" value="vanilla" checked>
+    Vanilla
+  </decidables-toggle-option>
+</decidables-toggle>
+```
+
+### Base class
+
+#### `DecidablesElement`
+
+Base class for all *decidables* web components
+
+To define a new element:
+
+```javascript
+export default class DecidablesSomething extends DecidablesElement {
+  ...
+}
+```
+
+This library is built on `Lit`, so the resulting `DecidableElement` is also a `LitElement` 
+
+### Utilities
+
+#### `DecidablesConverterArray`
+
+Utility for attributes that can take an array of values
+
+If you are defining a `DecidablesElement` with an attribute that can take an array of numbers,
+then you can use this to automatically convert between a space-separated list as the attribute
+and an `Array` of numbers as the property:
+
+```javascript
+static get properties() {
+  return {
+    stuff: {
+      attribute: 'values',
+      converter: DecidablesConverterArray,
+      reflect: true,
+    },
+  };
+};
+```
+
+```html
+<decidables-something values="1.23 3.56 -2.97"></decidables-something>
+```
+
+And `this.values` will be the `Array`: `[1.23 3.56 -2.97]`
+
+#### `DecidablesConverterSet`
+
+Utility for attributes that can take a set of values
+
+If you are defining a `DecidablesElement` with an attribute that can take a set of string
+values, then you can use this to automatically convert between a space-separated list as the
+attribute and a `Set` of strings as the property:
+
+```javascript
+static get properties() {
+  return {
+    stuff: {
+      attribute: 'stuff',
+      converter: DecidablesConverterSet,
+      reflect: true,
+    },
+  };
+};
+```
+
+```html
+<decidables-something stuff="this that other"></decidables-something>
+```
+
+And `this.stuff` will be a `Set` with members: `'this'`, `'that'`, and `'other'`
+
+## Development
+
+### Features/Bugs/Notes
 
 - Custom spinner that looks better than User Agent spinners?
 - Edge/IE11 - slider shadow is clipped
@@ -27,30 +281,34 @@
 - Firefox - spinner arrows look ugly and asymmetrical
 - IE11 - No CSS variables outside custom elements (and not patched by ShadyCSS!)
 
----
-
-## Development Tooling
-
-### Local Scripts
+### Package Scripts
 
 - `yarn lint`
   - Lints markdown, scripts and styles
 - `yarn test`
   - Runs all tests and reports coverage in `test/coverage/`
+- `yarn test:watch`
+  - Runs all tests in watch mode and reports coverage in `test/coverage/`
 - `yarn test:file <filename>`
   - Runs tests for a single file and reports coverage in `test/coverage/`
 - `yarn build`
   - Builds bundles from `src/` to `lib/`
 
----
-
-## File Organization
+### File Organization
 
 - `decidables-elements/`
   - `lib/` (Bundles created from `src/` by `build`) **\[autogenerated\]**
   - `src/` (Source files)
   - `test/` (Testing files)
     - `coverage/` (Code coverage results) **\[autogenerated\]**
-  - `gulpfile.js` (Config for *gulp*)
-  - `package.json` (Config for *yarn* and *npm*)
+  - `CHANGELOG.md` (Based on conventional commits) **\[autogenerated\]**
+  - `gulpfile.js` (Tasks for *gulp*)
+  - `package.json` (Package config for *yarn* and *npm*)
   - `README.md` (This file)
+
+## [License](https://github.com/decidables/decidables/blob/main/LICENSE.md)
+
+The content of this project is licensed under [Creative Commons Attribution-ShareAlike 4.0
+International License (CC-BY-SA-4.0)](https://creativecommons.org/licenses/by-sa/4.0/) and the
+source code of this project is licensed under [GNU General Public License v3.0 or any later version
+(GPL-3.0-or-later)](https://www.gnu.org/licenses/gpl-3.0.html).

package/lib/decidablesElements.esm.js

@@ -655,12 +655,12 @@ var a$1 = /*#__PURE__*/function (_HTMLElement) {
     key: "requestUpdate",
     value: function requestUpdate(t, i, s) {
       var e = !0;
-      void 0 !== t && (((s = s || this.constructor.getPropertyOptions(t)).hasChanged || n$2)(this[t], i) ? (this._$AL.has(t) || this._$AL.set(t, i), !0 === s.reflect && this._$Ei !== t && (void 0 === this._$E_ && (this._$E_ = new Map()), this._$E_.set(t, s))) : e = !1), !this.isUpdatePending && e && (this._$Ep = this._$EC());
+      void 0 !== t && (((s = s || this.constructor.getPropertyOptions(t)).hasChanged || n$2)(this[t], i) ? (this._$AL.has(t) || this._$AL.set(t, i), !0 === s.reflect && this._$Ei !== t && (void 0 === this._$EC && (this._$EC = new Map()), this._$EC.set(t, s))) : e = !1), !this.isUpdatePending && e && (this._$Ep = this._$E_());
     }
   }, {
-    key: "_$EC",
+    key: "_$E_",
     value: function () {
-      var _$EC2 = _asyncToGenerator( /*#__PURE__*/regeneratorRuntime.mark(function _callee() {
+      var _$E_2 = _asyncToGenerator( /*#__PURE__*/regeneratorRuntime.mark(function _callee() {
         var t;
         return regeneratorRuntime.wrap(function _callee$(_context) {
           while (1) {
@@ -703,11 +703,11 @@ var a$1 = /*#__PURE__*/function (_HTMLElement) {
         }, _callee, this, [[1, 6]]);
       }));
 
-      function _$EC() {
-        return _$EC2.apply(this, arguments);
+      function _$E_() {
+        return _$E_2.apply(this, arguments);
       }
 
-      return _$EC;
+      return _$E_;
     }()
   }, {
     key: "scheduleUpdate",
@@ -775,9 +775,9 @@ var a$1 = /*#__PURE__*/function (_HTMLElement) {
     value: function update(t) {
       var _this5 = this;
 
-      void 0 !== this._$E_ && (this._$E_.forEach(function (t, i) {
+      void 0 !== this._$EC && (this._$EC.forEach(function (t, i) {
         return _this5._$ES(i, _this5[i], t);
-      }), this._$E_ = void 0), this._$EU();
+      }), this._$EC = void 0), this._$EU();
     }
   }, {
     key: "updated",
@@ -904,7 +904,7 @@ a$1.finalized = !0, a$1.elementProperties = new Map(), a$1.elementStyles = [], a
   mode: "open"
 }, null == h$1 || h$1({
   ReactiveElement: a$1
-}), (null !== (s$2 = globalThis.reactiveElementVersions) && void 0 !== s$2 ? s$2 : globalThis.reactiveElementVersions = []).push("1.1.2");
+}), (null !== (s$2 = globalThis.reactiveElementVersions) && void 0 !== s$2 ? s$2 : globalThis.reactiveElementVersions = []).push("1.3.1");
 
 /**
  * @license
@@ -941,7 +941,7 @@ var i = globalThis.trustedTypes,
     f = />|[ 	\n\r](?:([^\s"'>=/]+)([ 	\n\r]*=[ 	\n\r]*(?:[^ 	\n\r"'`<>=]|("|')|))|$)/g,
     _ = /'/g,
     m = /"/g,
-    g = /^(?:script|style|textarea)$/i,
+    g = /^(?:script|style|textarea|title)$/i,
     p = function p(t) {
   return function (i) {
     for (var _len = arguments.length, s = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
@@ -1230,23 +1230,23 @@ var N = /*#__PURE__*/function () {
     key: "_$AI",
     value: function _$AI(t) {
       var i = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : this;
-      t = P(this, t, i), r(t) ? t === w || null == t || "" === t ? (this._$AH !== w && this._$AR(), this._$AH = w) : t !== this._$AH && t !== b && this.$(t) : void 0 !== t._$litType$ ? this.T(t) : void 0 !== t.nodeType ? this.S(t) : u(t) ? this.A(t) : this.$(t);
+      t = P(this, t, i), r(t) ? t === w || null == t || "" === t ? (this._$AH !== w && this._$AR(), this._$AH = w) : t !== this._$AH && t !== b && this.$(t) : void 0 !== t._$litType$ ? this.T(t) : void 0 !== t.nodeType ? this.k(t) : u(t) ? this.S(t) : this.$(t);
     }
   }, {
-    key: "M",
-    value: function M(t) {
+    key: "A",
+    value: function A(t) {
       var i = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : this._$AB;
       return this._$AA.parentNode.insertBefore(t, i);
     }
   }, {
-    key: "S",
-    value: function S(t) {
-      this._$AH !== t && (this._$AR(), this._$AH = this.M(t));
+    key: "k",
+    value: function k(t) {
+      this._$AH !== t && (this._$AR(), this._$AH = this.A(t));
     }
   }, {
     key: "$",
     value: function $(t) {
-      this._$AH !== w && r(this._$AH) ? this._$AA.nextSibling.data = t : this.S(l$2.createTextNode(t)), this._$AH = t;
+      this._$AH !== w && r(this._$AH) ? this._$AA.nextSibling.data = t : this.k(l$2.createTextNode(t)), this._$AH = t;
     }
   }, {
     key: "T",
@@ -1259,7 +1259,7 @@ var N = /*#__PURE__*/function () {
         var _t8 = new V(o, this),
             _i9 = _t8.p(this.options);
 
-        _t8.m(s), this.S(_i9), this._$AH = _t8;
+        _t8.m(s), this.k(_i9), this._$AH = _t8;
       }
     }
   }, {
@@ -1269,8 +1269,8 @@ var N = /*#__PURE__*/function () {
       return void 0 === i && T.set(t.strings, i = new E(t)), i;
     }
   }, {
-    key: "A",
-    value: function A(t) {
+    key: "S",
+    value: function S(t) {
       d(this._$AH) || (this._$AH = [], this._$AR());
       var i = this._$AH;
       var s,
@@ -1282,7 +1282,7 @@ var N = /*#__PURE__*/function () {
       try {
         for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
           var _o2 = _step3.value;
-          e === i.length ? i.push(s = new N(this.M(h()), this.M(h()), this, this.options)) : s = i[e], s._$AI(_o2), e++;
+          e === i.length ? i.push(s = new N(this.A(h()), this.A(h()), this, this.options)) : s = i[e], s._$AI(_o2), e++;
         }
       } catch (err) {
         _iterator3.e(err);
@@ -1349,11 +1349,11 @@ var S = /*#__PURE__*/function () {
           _h = P(this, _e[s + _l], i, _l), _h === b && (_h = this._$AH[_l]), n || (n = !r(_h) || _h !== this._$AH[_l]), _h === w ? t = w : t !== w && (t += (null != _h ? _h : "") + o[_l + 1]), this._$AH[_l] = _h;
         }
       }
-      n && !e && this.k(t);
+      n && !e && this.C(t);
     }
   }, {
-    key: "k",
-    value: function k(t) {
+    key: "C",
+    value: function C(t) {
       t === w ? this.element.removeAttribute(this.name) : this.element.setAttribute(this.name, null != t ? t : "");
     }
   }]);
@@ -1376,8 +1376,8 @@ var M = /*#__PURE__*/function (_S) {
   }
 
   _createClass(M, [{
-    key: "k",
-    value: function k(t) {
+    key: "C",
+    value: function C(t) {
       this.element[this.name] = t === w ? void 0 : t;
     }
   }]);
@@ -1385,7 +1385,7 @@ var M = /*#__PURE__*/function (_S) {
   return M;
 }(S);
 
-var _k = i ? i.emptyScript : "";
+var k = i ? i.emptyScript : "";
 
 var H = /*#__PURE__*/function (_S2) {
   _inherits(H, _S2);
@@ -1402,9 +1402,9 @@ var H = /*#__PURE__*/function (_S2) {
   }
 
   _createClass(H, [{
-    key: "k",
-    value: function k(t) {
-      t && t !== w ? this.element.setAttribute(this.name, _k) : this.element.removeAttribute(this.name);
+    key: "C",
+    value: function C(t) {
+      t && t !== w ? this.element.setAttribute(this.name, k) : this.element.removeAttribute(this.name);
     }
   }]);
 
@@ -1470,7 +1470,7 @@ var L = /*#__PURE__*/function () {
 }();
 
 var z = window.litHtmlPolyfillSupport;
-null == z || z(E, N), (null !== (t = globalThis.litHtmlVersions) && void 0 !== t ? t : globalThis.litHtmlVersions = []).push("2.1.1");
+null == z || z(E, N), (null !== (t = globalThis.litHtmlVersions) && void 0 !== t ? t : globalThis.litHtmlVersions = []).push("2.2.1");
 
 /**
  * @license
@@ -1540,7 +1540,7 @@ var n = globalThis.litElementPolyfillSupport;
 null == n || n({
   LitElement: s
 });
-(null !== (o = globalThis.litElementVersions) && void 0 !== o ? o : globalThis.litElementVersions = []).push("3.1.1");
+(null !== (o = globalThis.litElementVersions) && void 0 !== o ? o : globalThis.litElementVersions = []).push("3.2.0");
 
 var noop = {
   value: function value() {}