Skip to content

orneryd/web-components

Repository files navigation

Classes

htmlLoader
ContextBinding
DataStore
EventMap
I18nMessage
I18n

Functions

bindEvents(root, context)HTMLElement

helper function used by the loader when importing html files as a template fucntion for using attributes such as "onclick" within your html templates. You do not need to call this yourself if you are importing your html files using the loader

getFromObj(path, obj, fb)* | String

Returns the value of an object via the path as a string

template(tmpl, map, fallback)* | String

Processes a string formatted like an ES6 template against an object

stripES6(expr, context)String

removes the ${} wrapping from an es6 template literal expression.

arrayParser(val, key, params)Boolean

In the event that the search string has multiple values with the same key it will convert that into an array of those values for the given key.

While there is no defined standard in RFC 3986 Section 3.4, most web frameworks accept and serialize them in the following manner as outlined in MSDN

toParams(str, options)Object

Converts URL parameters to a Object collection of key/value pairs Decodes encoded url characters to back to normal strings.

toSearch(options, base)String

Converts an Object of String/Value pairs to a query string for URL parameters prepended with the "base" character. Encodes unsafe url characters to url safe encodings.

prefixKeys(obj, prefix)Object

Convenience method that converts the keys of an object to have a prefix. This is faster than stringification.

toDataAttrs(obj, stringify)Object

Convenience method that wraps prefixKeys with 'data-' for easier property spreading within other frameworks such as react. This is preferrable over stringifying objects as parsing json is slow in the browser

htmlLoader

Kind: global class

new htmlLoader(content)

The HTML file is converted into a module that exports a function. That function takes a single argument (p shorthand for "props"). Also provides sass support by incliding a link tag in your html file to the scss file.

We use the builtin DOMParser to parse the HTML template to reduce runtime dependencies. an IIFE that takes a single argument (props) and returns the compiled template literal tring and passes it into the DOMParser.parseFromString fn.

The IIFE ends with fn.call(p, p) which ensures that the es6 template context supports both "this" and "props" within the template.

${this.myValue} and ${props.myValue} are treated identically and can be used interchangably For on*="" HTML5 event attributes, the loader replaces any ES6 syntax before babel conversion to the es6 template literal. This way, the interaction between the on* events and the ContextBinding mixin does not break. @see ContextBinding for more details.

Returns: String - it returns the HTML content wrapped as a module function

Param Type Description
content String fileContent from webpack

Example (webpack.config.js)

    {
      module: {
        rules: [
          {
            // set this to match the paths of the html files you want to import as functions.
            test: /web-components\/.+\.html$/,
            exclude: /node_modules/,
            use: [{
                loader: '@ornery/web-components/loader',
                options: {
                    minimize: true,
                    removeComments: true,
                    collapseWhitespace: true,
                    exportAsEs6Default: true,
                    attrs: false,
                    interpolate: false
                }
            }]
          }
        ]
      }
    }

Example (example.scss)

.example-list {
  padding: 0;
  margin: 0;

  .example-list-item {
    line-height: 1rem;
    margin: .5rem;
  }
}

Example (example.html)

<link src="./example.scss" />
<h3>${this.headerText}</h3>
<ul class="example-list">
    ${this.items.map(item => `<li class="example-list-item">${item}</li>`).join("")}
</ul>

Example

// becomes converted into:
const {bindEvents, setupConnect} = require("@ornery/web-components/templates");
module.exports = (p = {})=> {
  const parsed = new DOMParser().parseFromString(function(props){
  return "<style>.example-list{padding: 0;margin: 0;} .example-list .example-list-item{line-height: 1rem;margin: .5rem;}</style>" +
    "<h3>" + this.headerText + "</h3>" +
        "<ul>" +
    this.items.map(function(item){return "<li>" + item + "</li>"; })
                     .join("") +
        "</ul>"
  }.call(p, p), 'text/html');

  const elements = [...parsed.head.children, ...bindEvents(parsed.body, p).childNodes];
  return setupConnect(elements, p)
}

Example

import listTemplate from './example.html';
const fruits = ["apple", "orange", "banana"];

const compiledDOMNodeArray = listTemplate({
  headerText: "List of fruits.",
  items: fruits
});

console.log(compiledDOMNodeArray.length) // 2
console.log(compiledDOMNodeArray[0].tagName) // "h3"
console.log(compiledDOMNodeArray[0].innerHTML) // "List of fruits."
console.log(compiledDOMNodeArray[1].tagName) // "ul"
console.log(compiledDOMNodeArray[1].children[0].tagName) // "li"
console.log(compiledDOMNodeArray[1].children[0].innerHTML) // "apple"
console.log(compiledDOMNodeArray[1].children[1].tagName) // "li"
console.log(compiledDOMNodeArray[1].children[1].innerHTML) // "orange"
console.log(compiledDOMNodeArray[1].children[2].tagName) // "li"
console.log(compiledDOMNodeArray[1].children[2].innerHTML) // "banana"

ContextBinding

Kind: global class

new ContextBinding(superclass)

helper mixins for parsing data-* attributes as json objects via get/setAttribute.

Param Type Description
superclass class inheriting class

Example

//import the ContextBinding mixin
import ContextBinding from 'mck-webcomponents/lib/context-binding';

// define your custom element.
export default class ListComponent extends HTMLElement {
  constructor(self) {
    super(self);
    self = this;
  }

  connectedCallback() {
      this.shadowRoot.innerHTML = "";
      // ContextBinding allows you to access data-* attributes as JSON objects with or without the "data-" prefix.
      let items = this.getAttribute('items');
      listTemplate({
          items,
     }).forEach((node) => this.shadowRoot.appendChild(node));
  }
}

// Before registering, apply the mixin to your class.
customElements.define('list-component', ContextBinding(MainComponent));

Example

<!-- Usage in raw HTML -->
<list-component data-items="['apple','orange','banana']" selected-item="apple"></list-component>

ContextBinding.getAttribute(attrKey) ⇒ String

If using data-attributes, it will handle the string->JSON conversion for you. You may reference the data-* attributes with or without the data- prefix for convenience.

Kind: static method of ContextBinding
Returns: String - current attribute value.

Param Type
attrKey String

ContextBinding.setAttribute(attrKey, attrVal)

If using data-attributes, it will handle the JSON->string conversion for you when the value to set is not a string. You may reference the data-* attributes with or without the data- prefix for convenience. Bubbles up the attributeChangedCallback to your class when values are set.

Kind: static method of ContextBinding

Param Type Description
attrKey String the attribute key to set.
attrVal String | * the value to set the attribute to.

DataStore

Kind: global class

new DataStore()

Configuration values can be set and propagated to consuming components via this static class or through the corresponding wc-config element

DataStore.get(key) ⇒ Object

Kind: static method of DataStore
Returns: Object - the current value of the requested property name.

Param Type
key String

DataStore.getState() ⇒ Object

Kind: static method of DataStore
Returns: Object - the current state object.

DataStore.set(key, value) ⇒ Object | *

wraps this.set

Kind: static method of DataStore

Param Type Description
key String | Object the name of the value to set. It can also be called with an {} query to set multiple values at once.
value * the value of the property to set it to.

DataStore.setState(newState) ⇒ Object | *

wraps this.set

Kind: static method of DataStore

Param Type Description
newState Object the new state object.

DataStore.subscribe(callback) ⇒ Object | *

call destroy() on the returned object to remove the event listener.

Kind: static method of DataStore

Param Type Description
callback function is the function to execute when any property changes.

DataStore.subscribeTo(keys, callback) ⇒ Object | *

call destroy() on the returned object to remove the event listener.

Kind: static method of DataStore

Param Type Description
keys Array the property names to be notified when they mutate
callback function the callback to be executed when any of the value for any of those keys have changed.

EventMap

Kind: global class

new EventMap()

provides an event bus for when properties of the underlying Map change.

EventMap.module.exports#on(event, callback) ⇒ Object

call the destroy() function ont he returned object to remove the event listener

Kind: static method of EventMap
Returns: Object - with the subscriber function, the event name, and a destroy function.

Param Type Description
event String 'set'= after the property has been set
callback function notification channel

EventMap.module.exports#set(key, val, notify) ⇒ EventMap

call set() set the value for a given key in the map.

Kind: static method of EventMap
Returns: EventMap - this eventmap instance.

Param Type Description
key String
val Object | Array
notify Boolean set false to NOT notify subscribers.

EventMap.module.exports#replace(keyValuePairs, notify) ⇒ EventMap

call replace() to replace the existing state.

Kind: static method of EventMap
Returns: EventMap - this eventmap instance.

Param Type Description
keyValuePairs Object
notify Boolean set false to NOT notify subscribers.

EventMap.module.exports#del(key, notify) ⇒ EventMap

call del() to remove a value from the map.

Kind: static method of EventMap
Returns: EventMap - this eventmap instance.

Param Type Description
key * the key to remove from the map.
notify Boolean set false to NOT notify subscribers.

EventMap.module.exports#clear(notify) ⇒ Object

call clear() to remove all the key/value entries from the map.

Kind: static method of EventMap
Returns: Object - object hash of all the key value pairs.

Param Type Description
notify Boolean set false to NOT notify subscribers.

EventMap.module.exports#getAll() ⇒ Object

call getAll() to retrieve the current set of key/value pairs.

Kind: static method of EventMap
Returns: Object - object hash of all the key value pairs.

I18nMessage

Kind: global class

new I18nMessage(key, values, dataAttributes)

HTML element. Provides tranlsation and interpolation for translatable strings

Param Type Description
key String the key for the strings based on current language. can be set as the innerHTML or defined as the attibutes: key, id, data-key, data-id
values JSON can be passed as data-* attributes or as a json-parseable object string as "data-values"
dataAttributes String

Example (Given the following configuration)

import { I18n } from '@ornery/web-components';
I18n.addMessages('en-US', {
 'translatable.message.name': "I'm a translated string from i18n",
  'tokenized.message': "I have a ${color} ${animal}"
});

Example (With the following usage)

<i18n-message>translatable.message.name</i18n-message>
<div>
   <i18n-message data-values="{'color: 'grey', 'animal': 'monkey'}">tokenized.message</i18n-message>
   <i18n-message data-color="grey" data-animal="monkey">tokenized.message</i18n-message>
   <i18n-message key="tokenized.message"/>
   <!-- React does not pass key or ref props so you can use "data-key" or "data-id" as well-->
   <i18n-message data-key="tokenized.message"/>
   <i18n-message id="translatable.message.name"/>
   <i18n-message data-id="translatable.message.name"/>
</div>

Example (Renders the HTML)

<i18n-message>I'm a translated string from i18n</i18n-message>
<i18n-message>I have a grey monkey</i18n-message>

I18n

Kind: global class

new I18n()

Import strings here and call I18n.addStrings() with the supported locale identifier and the strings object exported from the language file By default, it will set the values on window.i18n, if defined when loaded, as the starting messages. This is useful if you wish to server-side render HTML certain content before laoding scripts on the client.

Example

import { I18n } from '@ornery/web-components';

I18n.addMessages('en-US', {
    'translatable.message.name': "I'm a translated string from i18n",
    'tokenized.message': "I have a ${this.color} ${this.animal}"
});

Example

window.i18n = {
    'en-US': {
        'translatable.message.name': "I'm a translated string from i18n",
        'tokenized.message': "I have a ${this.color} ${this.animal}"
    }
}

import { I18n } from '@ornery/web-components';

console.log(I18n.getMessages()) // will log the window.i18n object

I18n.getLang() ⇒ String

returns the current language. defaults to the browser's navigator.language value.

Kind: static method of I18n
Returns: String - lang
Example

navigator.language = 'en-US';
import { I18n } from '@ornery/web-components';

console.log(I18n.getLang()) // "en-US"

I18n.setLang(lang)

sets the current i18n language. This does not change the browser language.

Kind: static method of I18n

Param Type
lang String

Example

import { I18n } from '@ornery/web-components';

I18n.setLang('en-US')
console.log(I18n.getLang()) //'en-US'

I18n.getMessages() ⇒ String

returns the current i18n messages set in the DataManager

Kind: static method of I18n
Returns: String - lang

I18n.setMessages(values)

sets the strings as a whole. This overrides all existing strings. Use addMessages to add more strings to the existing set.

Kind: static method of I18n

Param Type
values Object

Example

import { I18n } from '@ornery/web-components';

I18n.setMessages({
    'en-US': {
        'translatable.message.name': "I'm a translated string from i18n",
        'tokenized.message': "I have a ${this.color} ${this.animal}"
    }
})

I18n.addMessages(lang, strings)

add more strings to the existing language set.

Kind: static method of I18n

Param Type
lang String
strings Object

Example

import { I18n } from '@ornery/web-components';
I18n.addMessages('en-US', {
 'translatable.message.name': "I'm a translated string from i18n",
  'tokenized.message': "I have a ${color} ${animal}"
});

I18n.get(key, data) ⇒ String

Returns the value for the key. If a context is provided as the second argument for tokens, the tokens will be replaced in the returned string.

Kind: static method of I18n
Returns: String - Returns the value for the key. Processed if a data context is provided as the second argument.

Param Type Description
key String they key of the string to retrieve from the current language set.
data Object Optional, The data to process tokens in the string with.

Example

import { I18n } from '@ornery/web-components';
I18n.addMessages('en-US', {
  'tokenized.message': "I have a ${color} ${animal}"
});

const stringTestData = {
    color: "grey",
    animal: "monkey"
};
console.log(I18n.get('tokenized.message', stringTestData)) // "I have a grey monkey"

I18n.getAll(namespace) ⇒ Object

If a namespace is provided, returns all the key value pairs for that namespace without the namespace in the keys.

Kind: static method of I18n
Returns: Object - Returns all the messages for the given language. Filtered to namespace if provided.

Param Type
namespace String

Example

import { I18n } from '@ornery/web-components';
I18n.addMessages('en-US', {
 'translatable.message.name': "I'm a translated string from i18n",
  'tokenized.message': "I have a ${color} ${animal}"
});

console.log(I18n.getAll('tokenized')) // {"message": "I have a ${color} ${animal}"}

bindEvents(root, context) ⇒ HTMLElement

helper function used by the loader when importing html files as a template fucntion for using attributes such as "onclick" within your html templates. You do not need to call this yourself if you are importing your html files using the loader

Kind: global function
Returns: HTMLElement - the root element passed in.

Param Type Description
root HTMLElement The root element to find all elements from.
context Object the context object for finding functions to bind against. default is the root element

Example

The event handler method signature is the exact same as standard HTML5 event handlers.
[standard HTML5 event handlers](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener).

Supported html5 events:
[onabort], [onafterprint], [onbeforeonload], [onbeforeprint], [onblur], [oncanplay], [oncanplaythrough], [onchange],
[onclick], [oncontextmenu], [ondblclick], [ondrag], [ondragend], [ondragenter], [ondragleave], [ondragover],
[ondragstart], [ondrop], [ondurationchange], [onemptied], [onended], [onerror], [onfocus], [onformchange],
[onforminput], [onhaschange], [oninput], [oninvalid], [onkeydown], [onkeypress], [onkeyup], [onload], [onloadeddata],
[onloadedmetadata], [onloadstart], [onmessage], [onmousedown], [onmousemove], [onmouseout], [onmouseover],
[onmouseup], [onmousewheel], [onoffline], [ononline], [onpagehide], [onpageshow], [onpause], [onplay], [onplaying],
[onpopstate], [onprogress], [onratechange], [onreadystatechange], [onredo], [onresize], [onscroll], [onseeked],
[onseeking], [onselect], [onstalled], [onstorage], [onsubmit], [onsuspend], [ontimeupdate], [onundo], [onunload],
[onvolumechange], [onwaiting]

Example

// By using the provided htmlLoader, you can use the ES6 template-literal syntax in on* HTML5 event attributes
<mwc-button onclick="${this.itemClick}" label="${props.text}"></mwc-button>
// If you are not using the loader, use the string name of the function to execute
// that is present on the custom element using the template
<mwc-button onclick="itemClick"></mwc-button>
// you can also use "this."
<mwc-button onclick="this.itemClick"></mwc-button>
// you can also refence properties of a member."
<mwc-button onclick="this.someObj.itemClick"></mwc-button>

Example

<!-- list.html: -->
<p id="selected-item-text" style="display:${props.selectedItemText ? 'block' : 'none'};">
  ${props.selectedItemText}
</p>
<mwc-formfield id="input-label" alignEnd label="${this.inputLabel}">
  <input onkeyup="${this.onInputKeyUp}" type="text">
</mwc-formfield>
<div>
  <mwc-button id="add-item" onclick="${this.clickHandler}" disabled="disabled">${this.buttonLabel}</mwc-button>
</div>
<ul>
  ${this.items.map((text) => {
    return `<li><mwc-button onclick="${this.itemClick}" label="${text}"></mwc-button></li>`
  }).join("")}
</ul>

Example

// define your custom element.
export default class ListComponent extends HTMLElement {
  constructor(self) {
    super(self);
    self = this;
    // use the shadow dom for best results.
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
      this.shadowRoot.innerHTML = "";
      listTemplate({
          // the html template loader will wire up the event handlers for you if you have defined them in your HTML
          onInputKeyUp: () => console.log("input contents changed:", this),
          itemClick: () =>  console.log("item clicked: ", this),
          clickHandler: () =>  console.log("button clicked: ", this),
          selectedItemText: this.getAttribute('selected-item'),
          inputLabel: buttonLabelBlank,
          buttonLabel: "add item to list."
     }).forEach((node) => this.shadowRoot.appendChild(node));
  }
}
customElements.define('list-component', MainComponent);

getFromObj(path, obj, fb) ⇒ * | String

Returns the value of an object via the path as a string

Kind: global function
Returns: * | String - whatever the value from the nested key path is or the default string '${path}'.

Param Type Description
path String
obj Object Object to find the property in
fb String Fallback string when not found

Example

let result = getFromObj('hello.foo', {
 hello: {
   foo: 'bar'
 }
});

result == 'bar';

template(tmpl, map, fallback) ⇒ * | String

Processes a string formatted like an ES6 template against an object

Kind: global function
Returns: * | String - whatever the value from the nested key path is or the default string '${path}'.

Param Type Description
tmpl String the string template
map Object Key/Value pairs to process the string against
fallback String they string fallback when the value is missing.

Example

let result = template('I am a string literal formatted ${message.label}.', {
 message: {
   label: 'to look like an ES6 template'
 }
});

result == 'I am a string literal formatted to look like an ES6 template.';

stripES6(expr, context) ⇒ String

removes the ${} wrapping from an es6 template literal expression.

Kind: global function
Returns: String - The cleaned sxpression without the ${}.

Param Type Description
expr String The es6 expression
context Options | Object the context object to find values for tokens.

arrayParser(val, key, params) ⇒ Boolean

In the event that the search string has multiple values with the same key it will convert that into an array of those values for the given key.

While there is no defined standard in RFC 3986 Section 3.4, most web frameworks accept and serialize them in the following manner as outlined in MSDN

Kind: global function
Returns: Boolean - returns the currently parsed value.

Param Type Description
val Object the value to parse
key String the name of the value to parse
params Object all of the parameters that have been parsed so far.

Example

window.location.search = '?values=foo&values=bar&values=hello&values=world';
const params = toParams(window.location.search, {});
console.log(params) // {values: ["foo","bar","hello", "world"]}

Example

window.location.search = '?values=1&values=2&values=3&values=5&values=7';
const params = toParams(window.location.search, {
    values: parseInt
});
console.log(params) // {values: [1, 2, 3, 5, 7]}

Example

window.location.search = '?answer=42';
const params = toParams(window.location.search, {
    answer: parseInt
});
console.log(params) // {answer: 42}

toParams(str, options) ⇒ Object

Converts URL parameters to a Object collection of key/value pairs Decodes encoded url characters to back to normal strings.

Kind: global function
Returns: Object - seach params as an object

Param Type Description
str String
options Object custom parser functions based on the key name

Example (convert query string to object:)

import {toParams} from '@ornery/web-components';
let paramsObject = toParams('?foo=bar&hello=world&hello=array&unsafe=I%20am%20an%20unsafe%20string');

console.log(paramsObject) // { foo: 'bar', hello: ['world', 'array'], unsafe: 'I am an unsafe string'}

Example (pass an optional parser object)

import {toParams} from '@ornery/web-components';
let paramsObject = toParams('?intvals=1&intvals=2&intvals=3', {
    intvals: parseInt
});

console.log(paramsObject) // { intvals: [ 1, 2, 3 ] }

Example (without psassing an optional parser object)

import {toParams} from '@ornery/web-components';
let paramsObject = toParams('?intvals=1&intvals=2&intvals=3');

console.log(paramsObject) // { intvals: [ "1", "2", "3" ] }

toSearch(options, base) ⇒ String

Converts an Object of String/Value pairs to a query string for URL parameters prepended with the "base" character. Encodes unsafe url characters to url safe encodings.

Kind: global function
Returns: String - the object represented as a query string.

Param Type
options Object
base String

Example (convert object to query string)

import {toSearch} from '@ornery/web-components';
let queryString = toSearch({
 foo: 'bar',
 hello: ['world', 'array'],
 unsafe: 'I am an unsafe string'

}, '#');

queryString == '#?foo=bar&hello=world&hello=array&unsafe=I%20am%20an%20unsafe%20string';

prefixKeys(obj, prefix) ⇒ Object

Convenience method that converts the keys of an object to have a prefix. This is faster than stringification.

Kind: global function
Returns: Object - The new object with transformed keys.

Param Type
obj Object
prefix String

Example

import {prefixKeys} from '@ornery/web-components';
let newObj = prefixKeys({
 foo: 'bar',
 hello: ['world', 'array'],
 unsafe: 'I am an unsafe string'

}, 'zoo-');

newObj == {
  'zoo-foo': 'bar',
  'zoo-hello': ['world', 'array']',
  'zoo-unsafe': 'I am an unsafe string'
};

toDataAttrs(obj, stringify) ⇒ Object

Convenience method that wraps prefixKeys with 'data-' for easier property spreading within other frameworks such as react. This is preferrable over stringifying objects as parsing json is slow in the browser

Kind: global function
Returns: Object - The new object with transformed keys.

Param Type Description
obj Object
stringify Boolean wether or not to stringify the values for each key.

Example (React example)

const stringTestData = {
 color: "black and white",
 animal: "panda"
};

const MyComponent = (props) => {
  const dataAttrs = toDataAttrs(stringTestData);
  return (<div>
    <div>
      <i18n-message
        data-key="tokenized.message"
        {...dataAttrs}/>
    </div>
    <div>
      <i18n-message
        data-id="tokenized.message"
        {...dataAttrs}
        data-color="red"/>
    </div>
  </div>);
};

const dataAttrs = toDataAttrs(stringTestData);

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published