awesome-webcomponents

awesome native js web components

Usage no npm install needed!

<script type="module">
  import awesomeWebcomponents from 'https://cdn.skypack.dev/awesome-webcomponents';
</script>

README

awesome : object

Awesome-Webcomponents

Awesome ES6 compliant web componants for use in your app or website.

Tested and working on :

  • Chrome
  • Chromium
  • Android Chrome
  • FireFox >=45
  • IE Edge
  • Electron
  • NW.js

Firefox >=45 supports evrything needed with the included ./bower_components/document-register-element/build/document-register-element.js. IE Edge Array.prototype.includes polyfill is build into awesome.js

install awesome-webcomponents via bower for your project by running bower install awesome-webcomponents don't forget to run bower update on occasion to get the latest version!

Working Component Examples and Demos

awesome-webcomponents on github.io

Licensed under DBAD license

See the DBAD license in your language or our licence.md file.

Contributing

  1. Fork the repo
  2. Do awesome stuff!
  3. Submit a Pull Request
  4. Feel Awesome!

Awesome.js Class api

window.awesome = new Awesome; is called automatically to instantiate a global awesome object for your use right away.

Kind: global namespace
Properties

Name Type Description
awesome.path String Path to folder awesome.js is located in
awesome.bower String path to bower components
constants Object awesome constants
constants.components ShallowMergeObject shallow merge for awesome.constants.components
constants.stores ShallowMergeObject shallow merge for awesome.constants.stores
constants.actions ShallowMergeObject shallow merge for awesome.constants.actions
config DeepMergeObject deep recursive merge for awesome config object
language Object awesome language objects
language.default Object awesome default language object
language.current Object awesome language object merged default and desiredLanguage
language.* Object awesome language objects for specific languages like awesome.language.en or awesome.language.ru
setLanguage function set the current language
dynamicLanguageString function a way to pass variables to language strings. This is helpful when you support languages with a variety of grammatical structures
dispatchers Object dispatchers for store/action/component messages
stores Object registered awesome.Store instances. These are designed to support 1 way data flows for use by components
Store Class Store class, used to create new stores
loadTemplate function fetches nested template contents for inclusion in awesome-component
requireScript function inject script tag into header
requireCSS function inject stylesheet link tag into header
mergeDataset function merges element's data-* attributes with the defaults for that component element
updateAttributesFromData function maps data-* values to * attribute values
uniqueEntries function ensures that keys and values of an object unique

awesome.Store

Kind: static class of awesome
Properties

Name Type Description
state Object state data of store exposed for reading by components via expose. The store modifies this as a shallow merge Object.
defaultState Object default store state
ignoreResetEvent Boolean flag to ignore the global reset event USE WITH CAUTION
resetState function rests the store state
expose function registers the read-only state with awesome.stores[store name] for components to use

Store.state : Object

state data of store exposed for reading by components via expose. The store modifies this as a shallow merge Object.

Kind: static property of Store
Access: protected
Example

//set the store state with a shallow merge
 myStoreState = {
    property: 'prop'
 }
 store.state = myStoreState;

//get the store state
 const state = store.state

Store.defaultState : Object

default store state

Kind: static property of Store
Example

//set your default store
store.defaultState = {
    defaultProperty1: 'red',
    defaultProperty2: 'white',
    defaultPropertyN: 'mandalorian'
}

Store.ignoreResetEvent : Boolean

flag to ignore the global reset event USE WITH CAUTION

Kind: static property of Store
Example

//ignore the global reset event
 store.ignoreResetEvent = true;

Store.expose(instance, name)

registers the read-only state with awesome.stores[store name] for components to use

Kind: static method of Store

Param Type Description
instance Store your instantiated Store instance
name String The name of your store

Example

//expose your store
store.expose(yourStoreScope, 'yourStoreName');

Store.resetState(events)

rests the store state

Kind: static method of Store

Param Type Description
events Object your stores event-pubsub instance

Example

//reset the store state
store.resetState();

"change"

Store.state change event used to notify component that the store state has changed.

Kind: event emitted by Store

awesome.path : String

Path to folder awesome.js is located in.

Kind: static property of awesome
Access: protected
Example

//use awesome.path to reference the awesome-webcomponents directory
awesome.requireCSS(`${awesome.path}components/buttons/awesome-buttonset.css`);
awesome.requireScript(`${awesome.path}components/buttons/awesome-buttonset.js`);

awesome.constants : Object

extensible/overwriteable constansts used in awesome apps

Kind: static property of awesome
Properties

Name Type Description
action Object action constants
store Object store constants
component Object component constants

constants.action : Object

Shallow merge action constants object

Kind: static property of constants

action.RESET_STORES : EventName

all stores should reset their state

Kind: static property of action

action.FILE_LOADED : String

files loaded and available

Kind: static property of action

action.LOGOUT_REQUEST : EventName

logout request

Kind: static property of action
Memeber: awesome.constants.action.LOGOUT_REQUEST

action.LOGIN_REQUEST : EventName

login request

Kind: static property of action
Memeber: awesome.constants.action.LOGIN_REQUEST

action.getter() ⇒ ActionConstants

action constants getter

Kind: static method of action
Returns: ActionConstants - action constants
Access: protected

action.setter(constants) ⇒ ActionConstants

action constants setter : merges the current action constants and the new constants via shallow merge.

Kind: static method of action
Returns: ActionConstants - actions merged constants
Access: protected

Param Type Description
constants Object constants to merge

Example

//original constants
{
    ACTION_CONSTANT1: 'actionConst1',
    ACTION_CONSTANT2: 'actionConst2',
}
myNewConstants = {
    NEW_CONSTANT_1: 'const1',
    NEW_CONSTANT_2: 'const2'
}

awesome.action.constants = myNewConstants;

//action constants will now be
//awesome.constants.action
{
    ACTION_CONSTANT1: 'actionConst1',
    ACTION_CONSTANT2: 'actionConst2',
    NEW_CONSTANT_1: 'const1',
    NEW_CONSTANT_2: 'const2'
}

constants.store : Object

Shallow merge store constants object

Kind: static property of constants

store.RESET : EventName

all stores should reset their state

Kind: static property of store

store.LOGIN_ERROR : EventName

user supplied bad credentials

Kind: static property of store

store.LOGOUT_ERROR : EventName

there was an error logging out

Kind: static property of store

store.LOGIN_SUCCESS : EventName

login was successful

Kind: static property of store

store.LOGOUT_SUCCESS : EventName

logout was successful

Kind: static property of store

store.FILE_LIST : String

file list available

Kind: static property of store

store.getter() ⇒ StoreConstants

store constants getter

Kind: static method of store
Returns: StoreConstants - store constants
Access: protected

store.setter(constants) ⇒ StoreConstants

action constants setter : merges the current store constants and the new constants via shallow merge.

Kind: static method of store
Returns: StoreConstants - stores merged constants
Access: protected

Param Type Description
constants Object constants to merge

Example

//original constants
{
    STORE_CONSTANT1: 'actionConst1',
    STORE_CONSTANT2: 'actionConst2',
}

myNewConstants = {
    NEW_CONSTANT_1: 'const1',
    NEW_CONSTANT_2: 'const2'
}

awesome.constantants.store = myNewConstants;

//action constants will now be
//awesome.constants.store
{
    STORE_CONSTANT1: 'actionConst1',
    STORE_CONSTANT2: 'actionConst2',
    NEW_CONSTANT_1: 'const1',
    NEW_CONSTANT_2: 'const2'
}

constants.component : Object

Shallow merge constants constants object *

Kind: static property of constants

component.VALIDATE_USERNAME : EventName

regular expression for validating user name

Kind: static property of component
Memeber: awesome.constants.component.VALIDATE_USERNAME
Example

const constanst = awesome.constansts.components;

//input pattern for a valid username, alphanumeric
<input class = 'yourUserNameInput'
    pattern = constansts.VALIDATE_EMAIL
></input>
// a user submission of userName will not be accepter but rather userName@group would

component.VALIDATE_EMAIL : EventName

regular expression for validating user email

Kind: static property of component
Memeber: awesome.constansts.component.VALIDATE_EMAIL
Example

const constanst = awesome.constansts.components;

//input patter for a valid email address, alphanumeric
<input class = 'yourEmailInput'
    pattern = constansts.VALIDATE_EMAIL
></input>
// an email submission of user@site will not be accepted but rather user@site.company would

component.VALIDATE_URL : EventName

regular expression for validating url

Kind: static property of component
Memeber: awesome.constansts.component.VALIDATE_URL
Example

const constanst = awesome.constansts.components;

//input pattern for a valid url
<input
    pattern = constansts.VALIDATE_URL
></input>
// a url submission of www.nodejs.org would not be accepter but rather
// https://nodejs.org or http://www.yourSite.yourDomain

component.getter() ⇒ ComponentConstants

component constants getter

Kind: static method of component
Returns: ComponentConstants - component constants
Access: protected

component.setter(constants) ⇒ ComponentConstants

component constants setter : merges the current component constants and the new constants via shallow merge.

Kind: static method of component
Returns: ComponentConstants - components merged constants
Access: protected

Param Type Description
constants Object constants to merge

Example

//original constants
{
    COMPONENT_CONSTANT1: 'actionConst1',
    COMPONENT_CONSTANT2: 'actionConst2',
}

myNewConstants = {
    NEW_CONSTANT_1: 'const1',
    NEW_CONSTANT_2: 'const2'
}

awesome.constants.components = myNewConstants;

//action constants will now be
//awesome.constants.component
{
    COMPONENT_CONSTANT1: 'actionConst1',
    COMPONENT_CONSTANT2: 'actionConst2',
    NEW_CONSTANT_1: 'const1',
    NEW_CONSTANT_2: 'const2'
}

awesome.config : Object

extensible/overwriteable constansts used in awesome apps

Kind: static property of awesome

config.setter() ⇒ Object

Deep merge config object

Kind: static method of config
Returns: Object - awesome.config
Example


// awesome.config could be
{
    a:1,
    b:{
        c:3
    },
    d:{
        e:55,
        f:{
            g:99
        }
    },
    q:{
        r:77
    }
}

awesome.configMerge(
    {
        b:{
            x:{
                y:{
                    z:99999
                }
            }
        },         *
        d:{
            f:{
                h:55
            }
        },
        q:33
    }
)


//now awesome.config would look like
{
    a:1,
    b:{
        c:3
            x:{
                y:{
                    z:99999
                }
            }
        }
    },
    d:{
        e:55,
        f:{
            g:99,
            h:55
        }
    },
    q:33
}

awesome.language : Object

language objects used by awesome components

Kind: static property of awesome

awesome.dispatchers : Object

dispatchers for awesome 1 way data flow

Kind: static property of awesome
Access: protected
Properties

Name Type Description
action Object action dispatcher
store Object store dispatcher
component Object component dispatcher

dispatchers.action : EventEmitter

awesome dispatcher for actions, uses event-pubsub

Kind: static property of dispatchers
Properties

Name Type Description
on function binds handler to action event
off function unbinds handler from action event
trigger function fires store event

Example

const dispatcher = awesome.dispatchers.action;
const constants = awesome.constants;

//trigger an event to store
dispatcher.trigger(
    constants.store.YOUR_STORE_CONSTANT,
    {
        data1 : 'data1',
        data2 : 'data2'
    }
);

//listen to an event from a component
dispatcher.on(
    constants.components.YOUR_COMPONENT_CONSTANT,
    yourHanderFunction
);

//stop listening to the event
dispatcher.off(
    constants.components.YOUR_COMPONENT_CONSTANT,
    yourHanderFunction
);

dispatchers.component : EventEmitter

awesome dispatcher for components, uses event-pubsub

Kind: static property of dispatchers
Properties

Name Type Description
trigger function fires action event

Example

const dispatcher = awesome.dispatcher.component;
const constants = awesome.constants;

//trigger an event to action
dispatcher.trigger(
    constants.action.YOUR_COMPONENT_CONSTANT,
    {
        data1 : 'data1',
        data2 : 'data2'
    }
);

dispatchers.store : EventEmitter

awesome dispatcher for stores, uses event-pubsub

Kind: static property of dispatchers
Properties

Name Type Description
on function binds handler to store events
off function unbinds handler from store event
events function fires event

Example

const dispatcher = awesome.dispatcher.store;
const constants = awesome.constants;

//listen to an event from an action
dispatcher.on(
    constants.action.YOUR_STORE_CONSTANT,
    yourHanderFunction
);

//stop listening to the event
 dispatcher.off(
    constants.components.YOUR_STORE_CONSTANT,
    yourHanderFunction
);

awesome.stores : Object

awesome 1 way data flow stores for use by component

Kind: static property of awesome
Example

state=awesome.stores.auth.state;

state.on(
    'change',
    this.yourAwesomeUpdateHandler.bind(this)
);

awesome.bower : String

Path to bower components

Kind: static property of awesome
Access: protected
Example

//include bower components using the bower components path
awesome.requireScript(`${awesome.bower}bower-component/bower-component.js`);

awesome.loadTemplate(instance) ⇒ Object

loadTemplate collects template element and returns element

Kind: static method of awesome
Returns: Object - contents of template element
Access: protected

Param Type Description
instance Object instance or scope of template element

Example

//taken from awesome-list example, loadTemplate will load template element of awesome-component
//and returns element

//html snippet

 <awesome-list>
       <template>
           <li>
               Test 1
           </li>
           <li>
               Test 2
           </li>
           <li>
               Test 3
           </li>
       </template>
   </awesome-list>

//js

const content=awesome.loadTemplate(this);

//constents of content
       `<li>
           Test 1
       </li>
       <li>
           Test 2
       </li>
       <li>
           Test 3
       </li>`

//usage
//this content can now be loaded into awesome-list

this.innerHTML=`
    <ul>
        ${content}
    </ul>
`;

awesome.requireScript(path) ⇒ Boolean

requireScript appends scripts to the docuyment head with a differed false

Kind: static method of awesome
Returns: Boolean - true
Access: protected

Param Type Description
path String path to script

Example

//here we require the dispatcher to action and the constants to stores and actions
awesome.requireScript(`${awesome.path}dispatchers/action.js`);
awesome.requireScript(`${awesome.path}actions/constants.js`);
awesome.requireScript(`${awesome.path}stores/constants.js`);

awesome.requireScript(path) ⇒ Boolean

requireLanguage includes js scripts into document

Kind: static method of awesome
Returns: Boolean - true
Access: protected

Param Type Description
path String path to script

awesome.requireCSS(path) ⇒ Boolean

requireCSS requires and appends scripts to CSS head

Kind: static method of awesome
Returns: Boolean - false if stylesheet has already been loaded into document

Param Type Description
path String Path to CSS stylesheet

Example

//require any CSS to script
awesome.requireCSS(`${awesome.path}components/your-component/your-component.css`);

awesome.mergeDataset(el, defaults)

mergeDataset merges element's dataset to current default dataset of document

Kind: static method of awesome

Param Type Description
el HTMLElement element with dataset to be merged
defaults Object default dataset

Example

defaultElementDataset = {
    property1: 'one',
    property2: 'two'
}

function componentCreatedCallback(componentDataset){
        mergeDataset(myElement, componentDataset);
}

//after the component is created it will contain
//ElementDataset
 {
    property1 : 'newProp1',
    property2 : 'newProp2'
 }

awesome.updateAttributesFromData(el, key, value) ⇒ HTMLElement

updateAttributesFromData updates an element's attributes

Kind: static method of awesome
Returns: HTMLElement - updated element object

Param Type Description
el HTMLElement element object
key String key of element
value String value to update data to

Example

//orginal element attributes
{
    attribute1 : 'green',
    attribute2 : 'red',
    attribute3 : 'white'
}

yourElementAttributeUpdater(element, attribute3, black);

function yourElementAttributeUpdater(element, elementKey,newValue){
    awesome.updateAttributesFromData(element, elementKey, newValue);
}

//resulting element attributes
{
    attribute1 : 'green',
    attribute2 : 'red',
    attribute3 : 'black'
}

awesome.uniqueEntries(data) ⇒ Boolean

uniqueEntries ensures that keys and values of data array are unique

Kind: static method of awesome
Returns: Boolean - true

Param Type Description
data Object Data object or array with unique entries

Example

//check that your constants all have unique entries as they should
 const constans = awesome.constans;

awesome.uniqueEntries(constans.store);
awesome.uniqueEntries(constans.components);
awesome.uniqueEntries(constans.actions);

//if entires are not unique an error will be thrown
`duplicate key of yourKey const keys mist be unique!`
//or
`duplicate value of yourConstant found on yourKey and yourKeyDuplicate const value strings MUST be unique!`

"awesome-language-set" (e)

emitted when the language is set or changed via awesome.setLanguage.

Kind: event emitted by awesome

Param Type Description
e Event Event Data
e.detail String languageCode

"awesome-script-loaded" (e)

emitted when a script included via requireScript has completed loading a script.

Kind: event emitted by awesome

Param Type Description
e Event Event Data
e.detail String path of the loaded script

Example

window.on(
    'awesome-script-loaded',
    yourAwesomeLoadedHandler
);

"awesome-script-error" (e)

emitted when a script included via requireScript can NOT be loaded.

Kind: event emitted by awesome

Param Type Description
e Event Event Data
e.detail String path of the loaded script

"awesome-language-loaded" (e)

emitted when a new language file included via awesome.requireLanguage has completed loading.

Kind: event emitted by awesome

Param Type Description
e Event Event Data
e.detail String path of the loaded language

"awesome-ready"

emitted when all queued scripts included via requireScript have completed loading. This will fire each time awesome deems it is ready for use. So if you include more scripts long after load it will fire again once all the new scripts are loaded.

Kind: event emitted by awesome

"awesome-wants-lang" (e)

emitted when a language check is performed for the first time and the language script is NOT in the head. This is useful when you have your own language files to load.

Kind: event emitted by awesome

Param Type Description
e Event Event Data
e.detail String desired language code

setLanguage(languageCode)

Merge a specific language and the default languages. If the languageCode has not been populated on the awesome.language object, the awesome.language.default will be used.

Kind: global function

Param Type Description
languageCode String like 'en', 'en-US', 'es' or 'zh' etc.

Example

//if awesome.language.default is
{
    hello:'Hello',
    appName:'My Awesome App'
}

//and awesome.language.es is
{
    hello:'Ola'
}

awesome.setLanguage('es');

//will result in awesome.language.current being
{
    hello:'Ola',
    appName:'My Awesome App'
}