kemet-ui 1.3.0 → 1.4.0

package/dist/components/kemet-scroll-snap/kemet-scroll-snap-paginator.js

@@ -1,4 +1,28 @@
 import { html, css, LitElement } from 'lit';
+import { emitEvent } from '../../utilities/misc/events.js';
+
+/**
+ * @since 1.0.0
+ * @status stable
+ *
+ * @tagname kemet-scroll-snap-paginator
+ * @summary The scroll snap's pagination.
+ *
+ * @prop {array} slides - Information about each slide.
+ * @prop {string} icon - A string representing which icon to use for pagination. Supports icons used in kemet-icon.
+ * @prop {number} size - The size in pixels of the icons.
+ * @prop {boolean} center - Determines whether to center the pagination items.
+ * @prop {boolean} hideFocusedLinks - Will hide inactive pagination items if set to true.
+ * @prop {boolean} useNumberPages - If set to true, the pages in the pagination iterator will appear as a set of numbers.
+ * @prop {boolean} useLabelPages - If set to true, the pages in the pagination iterator will appear as the label set on the slide.
+ *
+ * @cssproperty --kemet-scroll-snap-paginator-padding - The padding on the container. Default: 1rem 0.
+ * @cssproperty --kemet-scroll-snap-paginator-gap - The space between pagination items. Default: 0.5rem.
+ * @cssproperty --kemet-scroll-snap-paginator-link-color - The color of a linkable pagination item. Default: var(--kemet-color-primary).
+ *
+ * @event kemet-scroll-snap-focus - Fires when a set of slides are focused on.
+ *
+ */
 
 export default class KemetScrollSnapPaginator extends LitElement {
   static get styles() {
@@ -26,50 +50,28 @@ export default class KemetScrollSnapPaginator extends LitElement {
 
   static get properties() {
     return {
-      /**
-       * Information about each slide.
-       */
       slides: {
         type: Array,
       },
-      /**
-       * A string representing which icon to use for pagination. Supports icons used in kemet-icon.
-       */
       icon: {
         type: String,
       },
-      /**
-       * The size in pixels of the icons.
-       */
       size: {
         type: Number,
       },
-      /**
-       * Determines whether to center the pagination items.
-       */
       center: {
         type: Boolean,
         reflect: true,
       },
-      /**
-       * Will hide inactive pagination items if set to true.
-       */
       hideFocusedLinks: {
         type: Boolean,
         attribute: 'hide-focused-links',
       },
-      /**
-       * If set to true, the pages in the pagination iterator will appear as a set of numbers.
-       */
       useNumberPages: {
         type: Boolean,
         reflect: true,
         attribute: 'use-number-pages',
       },
-      /**
-       * If set to true, the pages in the pagination iterator will appear as the label set on
-       * the slide.
-       */
       useLabelPages: {
         type: Boolean,
         reflect: true,
@@ -149,14 +151,7 @@ export default class KemetScrollSnapPaginator extends LitElement {
   }
 
   slideLink(index) {
-    /**
-     * Fires when a set of slides are focused on.
-     */
-    this.dispatchEvent(new CustomEvent('kemet-scroll-snap-focus', {
-      bubbles: true,
-      composed: true,
-      detail: index,
-    }));
+    emitEvent(this, 'kemet-scroll-snap-focus', index);
   }
 
   handleKeyboardInput(event, id) {

package/dist/components/kemet-scroll-snap/kemet-scroll-snap-slide.js

@@ -1,5 +1,21 @@
 import { html, css, LitElement } from 'lit';
 
+/**
+ * @since 1.0.0
+ * @status stable
+ *
+ * @tagname kemet-scroll-snap-slide
+ * @summary A slide in a scroll snap component.
+ *
+ * @prop {boolean} focused - Is true when the slide is fully visible in it's container.
+ * @prop {string} index - Identifies the slide.
+ * @prop {string} label - Labels the slide.
+ *
+ * @cssproperty --kemet-scroll-snap-slide-width - The width of the slide. Default: 100%.
+ * @cssproperty --kemet-scroll-snap-slide-align - The slide alignment. Default: center.
+ *
+ */
+
 export default class KemetScrollSnapSlide extends LitElement {
   static get styles() {
     return css`
@@ -14,23 +30,14 @@ export default class KemetScrollSnapSlide extends LitElement {
 
   static get properties() {
     return {
-      /**
-       * Is true when the slide is fully visible in it's container.
-       */
       focused: {
         type: Boolean,
         reflect: true,
       },
-      /**
-       * Identifies the slide.
-       */
       index: {
         type: String,
         reflect: true,
       },
-      /**
-       * Labels the slide.
-       */
       label: {
         type: String,
         reflect: true,

package/dist/components/kemet-scroll-snap/kemet-scroll-snap.js

@@ -1,4 +1,30 @@
 import { html, css, LitElement } from 'lit';
+import { emitEvent } from '../../utilities/misc/events.js';
+
+/**
+ * @since 1.0.0
+ * @status stable
+ *
+ * @tagname kemet-scroll-snap
+ * @summary A scroll-snap implementation for responsive sliders.
+ *
+ * @prop {string} axis - Determines the direction the component flows. Values include: (horizontal | vertical)
+ * @prop {string} pagination - Determines where to display the paginator. Values include: (top | right | bottom | left)
+ *
+ * @slot slides - Place your slides here.
+ * @slot pagination - Place the paginator component here if you want one.
+ *
+ * @csspart slides - The slides container.
+ * @csspart pagination - The pagination element.
+ *
+ * @cssproperty --kemet-scroll-snap-gap - Space between the slides. Default: 1.5rem.
+ * @cssproperty --kemet-scroll-snap-horizontal-max-width - The horizontal max width of the container. Default: 1024px.
+ * @cssproperty --kemet-scroll-snap-vertical-height - The vertical height of the container. Default: 100vh.
+ * @cssproperty --kemet-scroll-snap-slides-vertical-padding - Padding on the vertical axis. Default: 0 2rem.
+ *
+ * @event kemet-scroll-snap-make-slides - Fires when slide data has been created.
+ *
+ */
 
 export default class KemetScrollSnap extends LitElement {
   static get styles() {
@@ -58,16 +84,10 @@ export default class KemetScrollSnap extends LitElement {
 
   static get properties() {
     return {
-      /**
-       * Determines the direction the component flows. Values include: (horizontal|vertical)
-       */
       axis: {
         type: String,
         reflect: true,
       },
-      /**
-       * Determines where to display the paginator. Values include: (top | right | bottom | left)
-       */
       pagination: {
         type: String,
         reflect: true,
@@ -154,15 +174,7 @@ export default class KemetScrollSnap extends LitElement {
     });
 
     this.slides = slides;
-
-    /**
-     * Fires when slide data has been created.
-     */
-    this.dispatchEvent(new CustomEvent('kemet-scroll-snap-make-slides', {
-      bubbles: true,
-      composed: true,
-      detail: this.slides,
-    }));
+    emitEvent(this, 'kemet-scroll-snap-make-slides', this.slides);
   }
 
   focusSlide(index) {

package/dist/components/kemet-select/kemet-option.js

@@ -1,29 +1,34 @@
 import { html, LitElement } from 'lit';
 
+/**
+ * @since 1.0.0
+ * @status stable
+ *
+ * @tagname kemet-option
+ * @summary An option in a select.
+ *
+ * @prop {string} label - The label of the option
+ * @prop {string} value - The value of the options
+ * @prop {boolean} disabled - Determines whether to disable the option
+ * @prop {boolean} selected - Selects the option if true
+ *
+ * @event kemet-input-focused - Fires when the input receives and loses focus
+ * @event kemet-input-status - Fires when there's a change in status
+ *
+ */
+
 export default class KemetOption extends LitElement {
   static get properties() {
     return {
-      /**
-       * The label of the option
-       */
       label: {
         type: String,
       },
-      /**
-       * The value of the options
-       */
       value: {
         type: String,
       },
-      /**
-       * Determines whether to disable the option
-       */
       disabled: {
         type: Boolean,
       },
-      /**
-       * Selects the option if true
-       */
       selected: {
         type: Boolean,
       },

package/dist/components/kemet-select/kemet-select.js

@@ -1,5 +1,47 @@
 import { html, css, LitElement } from 'lit';
 import { FormSubmitController } from '../../utilities/controllers/forms.js';
+import { emitEvent } from '../../utilities/misc/events.js';
+
+/**
+ * @since 1.0.0
+ * @status stable
+ *
+ * @tagname kemet-select
+ * @summary An enhanced select element.
+ *
+ * @prop {string} slug - A string the uniquely identifies the select
+ * @prop {string} name - The name of the select
+ * @prop {string} value - The value of the select
+ * @prop {array} options - The options the select contains
+ * @prop {string} status - The status of the select
+ * @prop {boolean} required - Determines whether or not the field is required
+ * @prop {boolean} disabled - Determines whether or not the field is disabled
+ * @prop {boolean} multiple - Support of multiple choice selections
+ * @prop {string} icon - The dropdown icon
+ * @prop {number} iconSize - The dropdown icon size
+ * @prop {boolean} filled - Displays a filled select
+ * @prop {boolean} rounded - Displays rounded corners
+ *
+ * @csspart select
+ *
+ * @cssproperty --kemet-select-padding - The padding on the textarea. Default: 1rem.
+ * @cssproperty --kemet-select-border - The border of the textarea. Default: 1px solid var(--kemet-color-primary).
+ * @cssproperty --kemet-select-border-color-error - The border of the error state. Default: 1px solid var(--kemet-color-error).
+ * @cssproperty --kemet-select-border-color-success - The border of the success state. Default: 1px solid var(--kemet-color-success).
+ * @cssproperty --kemet-select-border-color-warning - The border of the warning state. Default: 1px solid var(--kemet-color-warning).
+ * @cssproperty --kemet-select-border-radius-rounded - The border radius on rounded. Default: var(--kemet-border-radius).
+ * @cssproperty --kemet-select-border-filled - The border on filled. Default: none.
+ * @cssproperty --kemet-select-color-filled - The color on filled. Default: var(--kemet-color-white).
+ * @cssproperty --kemet-select-background-color-filled - The background-color on filled. Default: var(--kemet-color-primary).
+ * @cssproperty --kemet-select-background-color-error - The error state background color. Default: var(--kemet-color-error).
+ * @cssproperty --kemet-select-background-color-success - The success state background color. Default: var(--kemet-color-success).
+ * @cssproperty --kemet-select-background-color-warning - The warning state background color. Default: var(--kemet-color-warning).
+ * @cssproperty --kemet-select-icon-right - The space on the right of the icon. Default: 1rem.
+ *
+ * @event kemet-input-focused - Fires when the input receives and loses focus
+ * @event kemet-input-status - Fires when there's a change in status
+ *
+ */
 
 export default class KemetSelect extends LitElement {
   static get styles() {
@@ -75,80 +117,44 @@ export default class KemetSelect extends LitElement {
 
   static get properties() {
     return {
-      /**
-       * A string the uniquely identifies the select
-       */
       slug: {
         type: String,
       },
-      /**
-       * The name of the select
-       */
       name: {
         type: String,
       },
-      /**
-       * The value of the select
-       */
       value: {
         type: String,
       },
-      /**
-       * The options the select contains
-       */
       options: {
         type: Array,
       },
-      /**
-       * The status of the select
-       */
       status: {
         type: String,
         reflect: true,
       },
-      /**
-       * Determines whether or not the field is required
-       */
       required: {
         type: Boolean,
         reflect: true,
       },
-      /**
-       * Determines whether or not the field is disabled
-       */
       disabled: {
         type: Boolean,
         reflect: true,
       },
-      /**
-       * Support of multiple choice selections
-       */
       multiple: {
         type: Boolean,
       },
-      /**
-       * The dropdown icon
-       */
       icon: {
         type: String,
       },
-      /**
-       * The dropdown icon size
-       */
       iconSize: {
         type: Number,
         attribute: 'icon-size',
       },
-      /**
-       * Displays a filled select
-       */
       filled: {
         type: Boolean,
         reflect: true,
       },
-      /**
-       * Displays rounded corners
-       */
       rounded: {
         type: Boolean,
         reflect: true,
@@ -164,12 +170,10 @@ export default class KemetSelect extends LitElement {
     this.icon = 'chevron-down';
     this.iconSize = 16;
 
-    /**
-     * Used only for form reactive controller
-     */
+    /** @internal */
     this.formSubmitController = new FormSubmitController(this);
 
-    // elements
+    /** @internal */
     this.control = this.closest('kemet-field');
   }
 
@@ -178,7 +182,7 @@ export default class KemetSelect extends LitElement {
     this.select = this.shadowRoot.querySelector('select');
     this.selectedOption = this.querySelector('[selected]');
 
-    this.value = this.selecltedOption ? this.selectedOption.value : '';
+    this.value = this.selectedOption ? this.selectedOption.value : '';
   }
 
   render() {
@@ -247,17 +251,7 @@ export default class KemetSelect extends LitElement {
    */
   handleFocus() {
     this.hasFocus = true;
-
-    /**
-     * Fires when the input receives and loses focus
-     */
-    this.dispatchEvent(
-      new CustomEvent('kemet-input-focused', {
-        bubbles: true,
-        composed: true,
-        detail: true,
-      }),
-    );
+    emitEvent(this, 'kemet-input-focused', true);
   }
 
   /**
@@ -266,17 +260,7 @@ export default class KemetSelect extends LitElement {
    */
   handleBlur() {
     this.hasFocus = false;
-
-    /**
-     * Fires when the input receives and loses focus
-     */
-    this.dispatchEvent(
-      new CustomEvent('kemet-input-focused', {
-        bubbles: true,
-        composed: true,
-        detail: false,
-      }),
-    );
+    emitEvent(this, 'kemet-input-focused', false);
 
     this.select.checkValidity();
 
@@ -285,17 +269,11 @@ export default class KemetSelect extends LitElement {
       this.status = 'error';
       this.control.status = 'error';
 
-      this.dispatchEvent(
-        new CustomEvent('kemet-input-status', {
-          bubbles: true,
-          composed: true,
-          detail: {
-            status: 'error',
-            validity: this.select.validity,
-            element: this,
-          },
-        }),
-      );
+      emitEvent(this, 'kemet-input-status', {
+        status: 'error',
+        validity: this.select.validity,
+        element: this,
+      });
     }
   }
 
@@ -310,20 +288,11 @@ export default class KemetSelect extends LitElement {
       this.invalid = false;
       this.status = 'standard';
 
-      /**
-       * Fires when there's a change in status
-       */
-      this.dispatchEvent(
-        new CustomEvent('kemet-input-status', {
-          bubbles: true,
-          composed: true,
-          detail: {
-            status: 'standard',
-            validity: this.select.validity,
-            element: this,
-          },
-        }),
-      );
+      emitEvent(this, 'kemet-input-status', {
+        status: 'standard',
+        validity: this.select.validity,
+        element: this,
+      });
     }
   }
 
@@ -335,20 +304,11 @@ export default class KemetSelect extends LitElement {
     this.invalid = true;
     this.status = 'error';
 
-    /**
-     * Fires when there's a change in status
-     */
-    this.dispatchEvent(
-      new CustomEvent('kemet-input-status', {
-        bubbles: true,
-        composed: true,
-        detail: {
-          status: 'error',
-          validity: this.select.validity,
-          element: this,
-        },
-      }),
-    );
+    emitEvent(this, 'kemet-input-status', {
+      status: 'error',
+      validity: this.select.validity,
+      element: this,
+    });
   }
 
   /**

package/dist/components/kemet-sortable/kemet-sortable-item.js

@@ -1,5 +1,15 @@
 import { html, css, LitElement } from 'lit';
 
+/**
+ * @since 1.3.0
+ * @status stable
+ *
+ * @tagname kemet-sortable-item
+ * @summary An item in a sortable list.
+ *
+ * @prop {boolean} ghost - Automatically set to true when an item is dragged to a new spot.
+ */
+
 export default class KemetSortableItem extends LitElement {
   static get styles() {
     return [
@@ -21,11 +31,7 @@ export default class KemetSortableItem extends LitElement {
 
   static get properties() {
     return {
-      /* Automatically set to true when an item is dragged to a new spot */
-      ghost: {
-        type: Boolean,
-        reflect: true,
-      },
+      ghost: { type: Boolean, reflect: true },
     };
   }
 

package/dist/components/kemet-sortable/kemet-sortable.js

@@ -1,5 +1,6 @@
 import { html, css, LitElement } from 'lit';
 import { polyfill } from 'mobile-drag-drop';
+import { emitEvent } from '../../utilities/misc/events.js';
 
 const getMouseOffset = (event) => {
   const targetRect = event.target.getBoundingClientRect();
@@ -16,6 +17,16 @@ const getElementVerticalCenter = (element) => {
   return (rect.bottom - rect.top) / 2;
 };
 
+/**
+ * @since 1.3.0
+ * @status stable
+ *
+ * @tagname kemet-sortable
+ * @summary A list that can be sorted by drag and drop.
+ *
+ * @event kemet-sortable-drag-end - Fires when an item has been moved to a new spot.
+ */
+
 export default class KemetSortable extends LitElement {
   static get styles() {
     return [
@@ -72,20 +83,11 @@ export default class KemetSortable extends LitElement {
     event.preventDefault();
     this.sortableItem.ghost = false;
 
-    /**
-     * Fires when an item has been moved to a new spot
-     */
-    this.dispatchEvent(
-      new CustomEvent('kemet-sortable-drag-end', {
-        bubbles: true,
-        composed: true,
-        detail: {
-          event,
-          current: this.sortableItem,
-          all: this.querySelectorAll('kemet-sortable-item'),
-        },
-      }),
-    );
+    emitEvent(this, 'kemet-sortable-drag-end', {
+      event,
+      current: this.sortableItem,
+      all: this.querySelectorAll('kemet-sortable-item'),
+    });
   }
 }
 

package/dist/components/kemet-svgs/kemet-svg.js

@@ -1,5 +1,22 @@
 import { html, css, LitElement } from 'lit';
 
+/**
+ * @since 1.0.0
+ * @status stable
+ *
+ * @tagname kemet-svg
+ * @summary A svg from a set of custom SVGs.
+ *
+ * @prop {string} set - Defines which set of svgs is referenced.
+ * @prop {string} svg - The name (id) of the svg to be displayed.
+ * @prop {number} size - Sets the width and height of a the svg to the given value in pixels.
+ * @prop {string} ratio - The value for the preserveAspectRatio attribute of the svg.
+ * @prop {string} viewBox - The value for the viewBox attribute of the svg.
+ *
+ * @csspart svg - The svg element.
+ *
+ */
+
 export default class KemetSVG extends LitElement {
   static get styles() {
     return css`
@@ -16,33 +33,18 @@ export default class KemetSVG extends LitElement {
 
   static get properties() {
     return {
-      /**
-       * Defines which set of svgs is referenced.
-       */
       set: {
         type: String,
       },
-      /**
-       * The name (id) of the svg to be displayed.
-       */
       svg: {
         type: String,
       },
-      /**
-       * Sets the width and height of a the svg to the given value in pixels.
-       */
       size: {
         type: Number,
       },
-      /**
-       * The value for the preserveAspectRatio attribute of the svg.
-       */
       ratio: {
         type: String,
       },
-      /**
-       * The value for the viewBox attribute of the svg.
-       */
       viewBox: {
         type: String,
       },

package/dist/components/kemet-svgs/kemet-svgs.js

@@ -1,5 +1,16 @@
 import { LitElement, html, css } from 'lit';
 
+/**
+ * @since 1.0.0
+ * @status stable
+ *
+ * @tagname kemet-svgs
+ * @summary A set of SVG graphics that can be referenced any where in a page or app.
+ *
+ * @prop {string} set - Defines the name for the set of svgs.
+ *
+ */
+
 export default class KemetSVGs extends LitElement {
   static get styles() {
     return css`
@@ -11,9 +22,6 @@ export default class KemetSVGs extends LitElement {
 
   static get properties() {
     return {
-      /**
-       * Defines the name for the set of svgs.
-       */
       set: {
         type: String,
       },