@decidables/decidables-elements 0.0.1 → 0.0.4

package/README.md

@@ -2,22 +2,270 @@
 
 # decidables-elements: Basic UI Web Components for [**decidables**](https://github.com/decidables/decidables)
 
+[![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)](https://github.com/decidables/decidables/blob/main/LICENSE.md)
+
+## 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>`
+
+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'`
 
 ## Features/Bugs/Notes
 
@@ -27,8 +275,6 @@
 - Firefox - spinner arrows look ugly and asymmetrical
 - IE11 - No CSS variables outside custom elements (and not patched by ShadyCSS!)
 
----
-
 ## Development Tooling
 
 ### Local Scripts
@@ -36,12 +282,14 @@
 - `yarn lint`
   - Lints markdown, scripts and styles
 - `yarn test`
-  - Runs tests and reports coverage in `test/coverage/`
+  - 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
 
 - `decidables-elements/`
@@ -49,6 +297,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.1",
+  "version": "0.0.4",
   "description": "decidables-elements: Basic UI Web Components for the decidables project",
   "type": "module",
   "main": "./lib/decidablesElements.umd.min.js",
@@ -19,14 +19,21 @@
   "bugs": "https://github.com/decidables/decidables/issues",
   "homepage": "https://github.com/decidables/decidables/tree/main/libraries/decidables-elements",
   "author": "Adam Krawitz (https://web.uvic.ca/psyc/krawitz/)",
-  "license": "GPL-3.0",
+  "license": "CC-BY-SA-4.0 AND GPL-3.0-or-later",
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "package.json",
+    "*.md",
+    "src",
+    "lib"
+  ],
   "scripts": {
     "lint": "gulp lint",
     "test": "web-test-runner test/**/*.test.js --config ../../.webtestrunnerrc.js",
-    "test-file": "web-test-runner $@ --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"
   },
   "browserslist": [
@@ -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": "560272dc4d2c353ff4cffa76a27d1dc5343674b2"
+  "gitHead": "f3e3115ad33a8e1ad5db8ae455b67f571f4561c6"
 }

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;
-}