@decidables/decidables-elements 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+### [0.0.3](https://github.com/decidables/decidables/compare/@decidables/decidables-elements@0.0.2...@decidables/decidables-elements@0.0.3) (2022-03-07)
+
+**Note:** Version bump only for package @decidables/decidables-elements
+
+
+
+
+
 ### [0.0.2](https://github.com/decidables/decidables/compare/@decidables/decidables-elements@0.0.1...@decidables/decidables-elements@0.0.2) (2022-03-03)
 
 **Note:** Version bump only for package @decidables/decidables-elements

package/README.md

@@ -2,20 +2,199 @@
 
 # decidables-elements: Basic UI Web Components for [**decidables**](https://github.com/decidables/decidables)
 
+## 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
+- Components
   - `DecidablesButton`: Button for taking actions
+    - `<decidables-button></decidables-button>`
+    - Slot: *unnamed*
+      - Inline content as label
+    - Attribute: `disabled`
+      - Boolean (default: `false`)
+      - In disabled state user can't interact
+    - Example: 
+      ```html
+      <decidables-button disabled>
+        Click me
+      </decidables-button>
+      ```
   - `DecidablesSlider`: Slider w/spinner for selecting a numeric value from a range
+    - `<decidables-slider></decidables-slider>`
+    - Slot: *unnamed*
+      - Inline content as label
+    - Attribute: `disabled`
+      - Boolean (default: `false`)
+      - In disabled state user can't interact
+    - Attribute: `max`
+      - Number (default: `undefined`)
+      - Maximum value the slider can take
+    - Attribute: `min`
+      - Number (default: `undefined`)
+      - Minimum value the slider can take
+    - Attribute: `step`
+      - Number (default: `undefined`)
+      - Amount that value increments with smallest movement of the slider
+    - Attribute: `value`
+      - Number (default: `undefined`)
+      - Initial value of the slider
+    - Example:
+      ```html
+      <decidables-slider disabled max="0" min="100" step="2" value="50">
+        Move me
+      </decidables-slider>
+      ```
   - `DecidablesSpinner`: Text field w/spinner arrows for selecting a continuous numeric value
+    - `<decidables-spinner></decidables-spinner>`
+    - Slot: *unnamed*
+      - Inline content as label
+    - Attribute: `disabled`
+      - Boolean (default: `false`)
+      - In disabled state user can't interact
+    - Attribute: `max`
+      - Number (default: `undefined`)
+      - Maximum value the slider can take
+    - Attribute: `min`
+      - Number (default: `undefined`)
+      - Minimum value the slider can take
+    - Attribute: `step`
+      - Number (default: `undefined`)
+      - Amount that value increments with smallest movement of the slider
+    - Attribute: `value`
+      - Number (default: `undefined`)
+      - Initial value of the slider
+    - Example:
+      ```html
+      <decidables-spinner disabled max="0" min="100" step="2" value="50">
+        Change me
+      </decidables-spinner>
+      ```
   - `DecidablesSwitch`: Switch for turning an option on or off
-  - `DecidablesToggle`: Toggle for selecting one option from a set
+    - `<decidables-switch></decidables-switch>`
+    - Slot: *unnamed*
+      - Inline content as label for **on** state
+    - Slot: `off-label`
+      - Inline content as label for **off** state
+    - Attribute: `disabled`
+      - Boolean (default: `false`)
+      - In disabled state user can't interact
+    - Attribute: `checked`
+      - Number (default: `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`: One option in a toggle set
+    - `<decidables-toggle-option></decidables-toggle-option>`
+    - Slot: *unnamed*
+      - Inline content as label for option
+    - Attribute: `disabled`
+      - Boolean (default: `false`)
+      - In disabled state user can't interact
+    - Attribute: `checked`
+      - Number (default: `false`)
+      - Whether the option is selected (`true`) or not ('false`)
+    - Attribute: `name`
+      - String (default: `undefined`)
+      - An identifier to be shared by all options in a mutually exclusive group
+    - Attribute: `value`
+      - String (default: `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`: Toggle for selecting one option from a set
+    - `<decidables-toggle></decidables-toggle>`
+    - Slot: *unnamed*
+      - Inline content as label for set
+    - Slot: `label`
+      - Inline content as legend for options
+    - Attribute: `disabled`
+      - Boolean (default: `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'`
 
 ---
 
@@ -37,6 +216,8 @@
   - 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`
@@ -51,6 +232,7 @@
   - `src/` (Source files)
   - `test/` (Testing files)
     - `coverage/` (Code coverage results) **\[autogenerated\]**
+  - `CHANGELOG.md` (Based on conventional commits) **\[autogenerated\]**
   - `gulpfile.js` (Config for *gulp*)
   - `package.json` (Config for *yarn* and *npm*)
   - `README.md` (This file)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidables/decidables-elements",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "decidables-elements: Basic UI Web Components for the decidables project",
   "type": "module",
   "main": "./lib/decidablesElements.umd.min.js",
@@ -23,9 +23,16 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "package.json",
+    "*.md",
+    "src",
+    "lib"
+  ],
   "scripts": {
     "lint": "gulp lint",
     "test": "web-test-runner test/**/*.test.js --config ../../.webtestrunnerrc.js",
+    "test:watch": "web-test-runner test/**/*.test.js --config ../../.webtestrunnerrc.js --watch",
     "test:file": "web-test-runner $@ --config ../../.webtestrunnerrc.js",
     "build": "gulp build"
   },
@@ -34,7 +41,6 @@
     "not dead"
   ],
   "devDependencies": {
-    "@open-wc/testing": "^3.1.1",
     "@web/test-runner": "^0.13.27",
     "gulp": "^4.0.2"
   },
@@ -42,5 +48,5 @@
     "d3": "^7.3.0",
     "lit": "^2.1.2"
   },
-  "gitHead": "e6bd81a6113c3d4e6a89d9b16f835ec00021034e"
+  "gitHead": "316addbec77ac7c9b445b313ac4694e65164f104"
 }

package/gulpfile.js

@@ -1,25 +0,0 @@
-
-// devDependencies
-import gulp from 'gulp';
-
-// Local dependencies
-import * as cleans from '../../scripts/clean.js';
-import * as lints from '../../scripts/lint.js';
-import * as builds from '../../scripts/build.js';
-
-// Re-export
-export * from '../../scripts/clean.js';
-export * from '../../scripts/lint.js';
-export * from '../../scripts/build.js';
-
-// Tasks
-export const lint = gulp.parallel(
-  lints.lintMarkdown,
-  lints.lintScripts,
-  lints.lintStyles,
-);
-
-export const build = gulp.series(
-  cleans.cleanLib,
-  builds.buildLibrary,
-);

package/test/button.test.js

@@ -1,29 +0,0 @@
-import {expect, fixture, html} from '@open-wc/testing';
-
-import '../src/button';
-
-describe('decidables-button', () => {
-  it('has a shadowDom', async () => {
-    const el = await fixture(html` <decidables-button>Push</decidables-button> `);
-
-    expect(el).shadowDom.to.equal(`
-      <button>
-        <slot></slot>
-      </button>
-    `);
-  });
-
-  it('has a lightDom', async () => {
-    const el = await fixture(html` <decidables-button>Push</decidables-button> `);
-
-    expect(el).lightDom.to.equal(`
-      Push
-    `);
-  });
-
-  it('can be disabled', async () => {
-    const el = await fixture(html` <decidables-button disabled>Push</decidables-button> `);
-
-    expect(el.shadowRoot).to.have.descendant('button').that.has.attribute('disabled');
-  });
-});

package/test/converter-array.test.js

@@ -1,14 +0,0 @@
-import {expect} from '@open-wc/testing';
-
-import DecidablesConvertArray from '../src/converter-array';
-
-describe('decidables-converter-array', () => {
-  it('converts from attribute to property', () => {
-    expect(DecidablesConvertArray.fromAttribute('1 2 3 4 5')).to.deep.equal([1, 2, 3, 4, 5]);
-  });
-
-  it('converts from property to attribute', () => {
-    expect(DecidablesConvertArray.toAttribute([1, 2, 3, 4, 5]))
-      .to.equal('1.000 2.000 3.000 4.000 5.000');
-  });
-});

package/test/converter-set.test.js

@@ -1,15 +0,0 @@
-import {expect} from '@open-wc/testing';
-
-import DecidablesConvertSet from '../src/converter-set';
-
-describe('decidables-converter-set', () => {
-  it('converts from attribute to property', () => {
-    expect(DecidablesConvertSet.fromAttribute('alpha beta gamma'))
-      .to.deep.equal(new Set(['alpha', 'beta', 'gamma']));
-  });
-
-  it('converts from property to attribute', () => {
-    expect(DecidablesConvertSet.toAttribute(new Set(['alpha', 'beta', 'gamma'])))
-      .to.equal('alpha beta gamma');
-  });
-});

package/test/coverage/lcov-report/base.css

@@ -1,224 +0,0 @@
-body, html {
-  margin:0; padding: 0;
-  height: 100%;
-}
-body {
-    font-family: Helvetica Neue, Helvetica, Arial;
-    font-size: 14px;
-    color:#333;
-}
-.small { font-size: 12px; }
-*, *:after, *:before {
-  -webkit-box-sizing:border-box;
-     -moz-box-sizing:border-box;
-          box-sizing:border-box;
-  }
-h1 { font-size: 20px; margin: 0;}
-h2 { font-size: 14px; }
-pre {
-    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
-    margin: 0;
-    padding: 0;
-    -moz-tab-size: 2;
-    -o-tab-size:  2;
-    tab-size: 2;
-}
-a { color:#0074D9; text-decoration:none; }
-a:hover { text-decoration:underline; }
-.strong { font-weight: bold; }
-.space-top1 { padding: 10px 0 0 0; }
-.pad2y { padding: 20px 0; }
-.pad1y { padding: 10px 0; }
-.pad2x { padding: 0 20px; }
-.pad2 { padding: 20px; }
-.pad1 { padding: 10px; }
-.space-left2 { padding-left:55px; }
-.space-right2 { padding-right:20px; }
-.center { text-align:center; }
-.clearfix { display:block; }
-.clearfix:after {
-  content:'';
-  display:block;
-  height:0;
-  clear:both;
-  visibility:hidden;
-  }
-.fl { float: left; }
-@media only screen and (max-width:640px) {
-  .col3 { width:100%; max-width:100%; }
-  .hide-mobile { display:none!important; }
-}
-
-.quiet {
-  color: #7f7f7f;
-  color: rgba(0,0,0,0.5);
-}
-.quiet a { opacity: 0.7; }
-
-.fraction {
-  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
-  font-size: 10px;
-  color: #555;
-  background: #E8E8E8;
-  padding: 4px 5px;
-  border-radius: 3px;
-  vertical-align: middle;
-}
-
-div.path a:link, div.path a:visited { color: #333; }
-table.coverage {
-  border-collapse: collapse;
-  margin: 10px 0 0 0;
-  padding: 0;
-}
-
-table.coverage td {
-  margin: 0;
-  padding: 0;
-  vertical-align: top;
-}
-table.coverage td.line-count {
-    text-align: right;
-    padding: 0 5px 0 20px;
-}
-table.coverage td.line-coverage {
-    text-align: right;
-    padding-right: 10px;
-    min-width:20px;
-}
-
-table.coverage td span.cline-any {
-    display: inline-block;
-    padding: 0 5px;
-    width: 100%;
-}
-.missing-if-branch {
-    display: inline-block;
-    margin-right: 5px;
-    border-radius: 3px;
-    position: relative;
-    padding: 0 4px;
-    background: #333;
-    color: yellow;
-}
-
-.skip-if-branch {
-    display: none;
-    margin-right: 10px;
-    position: relative;
-    padding: 0 4px;
-    background: #ccc;
-    color: white;
-}
-.missing-if-branch .typ, .skip-if-branch .typ {
-    color: inherit !important;
-}
-.coverage-summary {
-  border-collapse: collapse;
-  width: 100%;
-}
-.coverage-summary tr { border-bottom: 1px solid #bbb; }
-.keyline-all { border: 1px solid #ddd; }
-.coverage-summary td, .coverage-summary th { padding: 10px; }
-.coverage-summary tbody { border: 1px solid #bbb; }
-.coverage-summary td { border-right: 1px solid #bbb; }
-.coverage-summary td:last-child { border-right: none; }
-.coverage-summary th {
-  text-align: left;
-  font-weight: normal;
-  white-space: nowrap;
-}
-.coverage-summary th.file { border-right: none !important; }
-.coverage-summary th.pct { }
-.coverage-summary th.pic,
-.coverage-summary th.abs,
-.coverage-summary td.pct,
-.coverage-summary td.abs { text-align: right; }
-.coverage-summary td.file { white-space: nowrap;  }
-.coverage-summary td.pic { min-width: 120px !important;  }
-.coverage-summary tfoot td { }
-
-.coverage-summary .sorter {
-    height: 10px;
-    width: 7px;
-    display: inline-block;
-    margin-left: 0.5em;
-    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
-}
-.coverage-summary .sorted .sorter {
-    background-position: 0 -20px;
-}
-.coverage-summary .sorted-desc .sorter {
-    background-position: 0 -10px;
-}
-.status-line {  height: 10px; }
-/* yellow */
-.cbranch-no { background: yellow !important; color: #111; }
-/* dark red */
-.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
-.low .chart { border:1px solid #C21F39 }
-.highlighted,
-.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
-  background: #C21F39 !important;
-}
-/* medium red */
-.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
-/* light red */
-.low, .cline-no { background:#FCE1E5 }
-/* light green */
-.high, .cline-yes { background:rgb(230,245,208) }
-/* medium green */
-.cstat-yes { background:rgb(161,215,106) }
-/* dark green */
-.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
-.high .chart { border:1px solid rgb(77,146,33) }
-/* dark yellow (gold) */
-.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
-.medium .chart { border:1px solid #f9cd0b; }
-/* light yellow */
-.medium { background: #fff4c2; }
-
-.cstat-skip { background: #ddd; color: #111; }
-.fstat-skip { background: #ddd; color: #111 !important; }
-.cbranch-skip { background: #ddd !important; color: #111; }
-
-span.cline-neutral { background: #eaeaea; }
-
-.coverage-summary td.empty {
-    opacity: .5;
-    padding-top: 4px;
-    padding-bottom: 4px;
-    line-height: 1;
-    color: #888;
-}
-
-.cover-fill, .cover-empty {
-  display:inline-block;
-  height: 12px;
-}
-.chart {
-  line-height: 0;
-}
-.cover-empty {
-    background: white;
-}
-.cover-full {
-    border-right: none !important;
-}
-pre.prettyprint {
-    border: none !important;
-    padding: 0 !important;
-    margin: 0 !important;
-}
-.com { color: #999 !important; }
-.ignore-none { color: #999; font-weight: normal; }
-
-.wrapper {
-  min-height: 100%;
-  height: auto !important;
-  height: 100%;
-  margin: 0 auto -48px;
-}
-.footer, .push {
-  height: 48px;
-}

package/test/coverage/lcov-report/block-navigation.js

@@ -1,87 +0,0 @@
-/* eslint-disable */
-var jumpToCode = (function init() {
-    // Classes of code we would like to highlight in the file view
-    var missingCoverageClasses = ['.cbranch-no', '.cstat-no', '.fstat-no'];
-
-    // Elements to highlight in the file listing view
-    var fileListingElements = ['td.pct.low'];
-
-    // We don't want to select elements that are direct descendants of another match
-    var notSelector = ':not(' + missingCoverageClasses.join('):not(') + ') > '; // becomes `:not(a):not(b) > `
-
-    // Selecter that finds elements on the page to which we can jump
-    var selector =
-        fileListingElements.join(', ') +
-        ', ' +
-        notSelector +
-        missingCoverageClasses.join(', ' + notSelector); // becomes `:not(a):not(b) > a, :not(a):not(b) > b`
-
-    // The NodeList of matching elements
-    var missingCoverageElements = document.querySelectorAll(selector);
-
-    var currentIndex;
-
-    function toggleClass(index) {
-        missingCoverageElements
-            .item(currentIndex)
-            .classList.remove('highlighted');
-        missingCoverageElements.item(index).classList.add('highlighted');
-    }
-
-    function makeCurrent(index) {
-        toggleClass(index);
-        currentIndex = index;
-        missingCoverageElements.item(index).scrollIntoView({
-            behavior: 'smooth',
-            block: 'center',
-            inline: 'center'
-        });
-    }
-
-    function goToPrevious() {
-        var nextIndex = 0;
-        if (typeof currentIndex !== 'number' || currentIndex === 0) {
-            nextIndex = missingCoverageElements.length - 1;
-        } else if (missingCoverageElements.length > 1) {
-            nextIndex = currentIndex - 1;
-        }
-
-        makeCurrent(nextIndex);
-    }
-
-    function goToNext() {
-        var nextIndex = 0;
-
-        if (
-            typeof currentIndex === 'number' &&
-            currentIndex < missingCoverageElements.length - 1
-        ) {
-            nextIndex = currentIndex + 1;
-        }
-
-        makeCurrent(nextIndex);
-    }
-
-    return function jump(event) {
-        if (
-            document.getElementById('fileSearch') === document.activeElement &&
-            document.activeElement != null
-        ) {
-            // if we're currently focused on the search input, we don't want to navigate
-            return;
-        }
-
-        switch (event.which) {
-            case 78: // n
-            case 74: // j
-                goToNext();
-                break;
-            case 66: // b
-            case 75: // k
-            case 80: // p
-                goToPrevious();
-                break;
-        }
-    };
-})();
-window.addEventListener('keydown', jumpToCode);