├── .gitignore ├── .nvmrc ├── LICENSE ├── README.md ├── example ├── react │ ├── package.json │ └── react.js └── ui-ponies │ └── ui-field.js ├── package.json ├── ponies.js └── test ├── index.html └── test.js /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | 5 | # Runtime data 6 | pids 7 | *.pid 8 | *.seed 9 | 10 | # Directory for instrumented libs generated by jscoverage/JSCover 11 | lib-cov 12 | 13 | # Coverage directory used by tools like istanbul 14 | coverage 15 | 16 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 17 | .grunt 18 | 19 | # node-waf configuration 20 | .lock-wscript 21 | 22 | # Compiled binary addons (http://nodejs.org/api/addons.html) 23 | build/Release 24 | 25 | # Dependency directory 26 | # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git 27 | node_modules 28 | -------------------------------------------------------------------------------- /.nvmrc: -------------------------------------------------------------------------------- 1 | v6 -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The Artistic License 2.0 2 | 3 | Copyright (c) 2015 Jesse Hattabaugh 4 | 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | This license establishes the terms under which a given free software 11 | Package may be copied, modified, distributed, and/or redistributed. 12 | The intent is that the Copyright Holder maintains some artistic 13 | control over the development of that Package while still keeping the 14 | Package available as open source and free software. 15 | 16 | You are always permitted to make arrangements wholly outside of this 17 | license directly with the Copyright Holder of a given Package. If the 18 | terms of this license do not permit the full use that you propose to 19 | make of the Package, you should contact the Copyright Holder and seek 20 | a different licensing arrangement. 21 | 22 | Definitions 23 | 24 | "Copyright Holder" means the individual(s) or organization(s) 25 | named in the copyright notice for the entire Package. 26 | 27 | "Contributor" means any party that has contributed code or other 28 | material to the Package, in accordance with the Copyright Holder's 29 | procedures. 30 | 31 | "You" and "your" means any person who would like to copy, 32 | distribute, or modify the Package. 33 | 34 | "Package" means the collection of files distributed by the 35 | Copyright Holder, and derivatives of that collection and/or of 36 | those files. A given Package may consist of either the Standard 37 | Version, or a Modified Version. 38 | 39 | "Distribute" means providing a copy of the Package or making it 40 | accessible to anyone else, or in the case of a company or 41 | organization, to others outside of your company or organization. 42 | 43 | "Distributor Fee" means any fee that you charge for Distributing 44 | this Package or providing support for this Package to another 45 | party. It does not mean licensing fees. 46 | 47 | "Standard Version" refers to the Package if it has not been 48 | modified, or has been modified only in ways explicitly requested 49 | by the Copyright Holder. 50 | 51 | "Modified Version" means the Package, if it has been changed, and 52 | such changes were not explicitly requested by the Copyright 53 | Holder. 54 | 55 | "Original License" means this Artistic License as Distributed with 56 | the Standard Version of the Package, in its current version or as 57 | it may be modified by The Perl Foundation in the future. 58 | 59 | "Source" form means the source code, documentation source, and 60 | configuration files for the Package. 61 | 62 | "Compiled" form means the compiled bytecode, object code, binary, 63 | or any other form resulting from mechanical transformation or 64 | translation of the Source form. 65 | 66 | 67 | Permission for Use and Modification Without Distribution 68 | 69 | (1) You are permitted to use the Standard Version and create and use 70 | Modified Versions for any purpose without restriction, provided that 71 | you do not Distribute the Modified Version. 72 | 73 | 74 | Permissions for Redistribution of the Standard Version 75 | 76 | (2) You may Distribute verbatim copies of the Source form of the 77 | Standard Version of this Package in any medium without restriction, 78 | either gratis or for a Distributor Fee, provided that you duplicate 79 | all of the original copyright notices and associated disclaimers. At 80 | your discretion, such verbatim copies may or may not include a 81 | Compiled form of the Package. 82 | 83 | (3) You may apply any bug fixes, portability changes, and other 84 | modifications made available from the Copyright Holder. The resulting 85 | Package will still be considered the Standard Version, and as such 86 | will be subject to the Original License. 87 | 88 | 89 | Distribution of Modified Versions of the Package as Source 90 | 91 | (4) You may Distribute your Modified Version as Source (either gratis 92 | or for a Distributor Fee, and with or without a Compiled form of the 93 | Modified Version) provided that you clearly document how it differs 94 | from the Standard Version, including, but not limited to, documenting 95 | any non-standard features, executables, or modules, and provided that 96 | you do at least ONE of the following: 97 | 98 | (a) make the Modified Version available to the Copyright Holder 99 | of the Standard Version, under the Original License, so that the 100 | Copyright Holder may include your modifications in the Standard 101 | Version. 102 | 103 | (b) ensure that installation of your Modified Version does not 104 | prevent the user installing or running the Standard Version. In 105 | addition, the Modified Version must bear a name that is different 106 | from the name of the Standard Version. 107 | 108 | (c) allow anyone who receives a copy of the Modified Version to 109 | make the Source form of the Modified Version available to others 110 | under 111 | 112 | (i) the Original License or 113 | 114 | (ii) a license that permits the licensee to freely copy, 115 | modify and redistribute the Modified Version using the same 116 | licensing terms that apply to the copy that the licensee 117 | received, and requires that the Source form of the Modified 118 | Version, and of any works derived from it, be made freely 119 | available in that license fees are prohibited but Distributor 120 | Fees are allowed. 121 | 122 | 123 | Distribution of Compiled Forms of the Standard Version 124 | or Modified Versions without the Source 125 | 126 | (5) You may Distribute Compiled forms of the Standard Version without 127 | the Source, provided that you include complete instructions on how to 128 | get the Source of the Standard Version. Such instructions must be 129 | valid at the time of your distribution. If these instructions, at any 130 | time while you are carrying out such distribution, become invalid, you 131 | must provide new instructions on demand or cease further distribution. 132 | If you provide valid instructions or cease distribution within thirty 133 | days after you become aware that the instructions are invalid, then 134 | you do not forfeit any of your rights under this license. 135 | 136 | (6) You may Distribute a Modified Version in Compiled form without 137 | the Source, provided that you comply with Section 4 with respect to 138 | the Source of the Modified Version. 139 | 140 | 141 | Aggregating or Linking the Package 142 | 143 | (7) You may aggregate the Package (either the Standard Version or 144 | Modified Version) with other packages and Distribute the resulting 145 | aggregation provided that you do not charge a licensing fee for the 146 | Package. Distributor Fees are permitted, and licensing fees for other 147 | components in the aggregation are permitted. The terms of this license 148 | apply to the use and Distribution of the Standard or Modified Versions 149 | as included in the aggregation. 150 | 151 | (8) You are permitted to link Modified and Standard Versions with 152 | other works, to embed the Package in a larger work of your own, or to 153 | build stand-alone binary or bytecode versions of applications that 154 | include the Package, and Distribute the result without restriction, 155 | provided the result does not expose a direct interface to the Package. 156 | 157 | 158 | Items That are Not Considered Part of a Modified Version 159 | 160 | (9) Works (including, but not limited to, modules and scripts) that 161 | merely extend or make use of the Package, do not, by themselves, cause 162 | the Package to be a Modified Version. In addition, such works are not 163 | considered parts of the Package itself, and are not subject to the 164 | terms of this license. 165 | 166 | 167 | General Provisions 168 | 169 | (10) Any use, modification, and distribution of the Standard or 170 | Modified Versions is governed by this Artistic License. By using, 171 | modifying or distributing the Package, you accept this license. Do not 172 | use, modify, or distribute the Package, if you do not accept this 173 | license. 174 | 175 | (11) If your Modified Version has been derived from a Modified 176 | Version made by someone other than you, you are nevertheless required 177 | to ensure that your Modified Version complies with the requirements of 178 | this license. 179 | 180 | (12) This license does not grant you the right to use any trademark, 181 | service mark, tradename, or logo of the Copyright Holder. 182 | 183 | (13) This license includes the non-exclusive, worldwide, 184 | free-of-charge patent license to make, have made, use, offer to sell, 185 | sell, import and otherwise transfer the Package with respect to any 186 | patent claims licensable by the Copyright Holder that are necessarily 187 | infringed by the Package. If you institute patent litigation 188 | (including a cross-claim or counterclaim) against any party alleging 189 | that the Package constitutes direct or contributory patent 190 | infringement, then this Artistic License to you shall terminate on the 191 | date that such litigation is filed. 192 | 193 | (14) Disclaimer of Warranty: 194 | THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS 195 | IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED 196 | WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR 197 | NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL 198 | LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL 199 | BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL 200 | DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF 201 | ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 202 | 203 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ponies 🐎🐎🐎 2 | 3 | My little library for creating [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) that automatically update when their attributes change. The hard work is done by [yo-yo](https://www.npmjs.com/package/yo-yo) which uses [bel](https://www.npmjs.com/package/bel) to render [tagged template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals) as DOM elements, and [morphdom](https://www.npmjs.com/package/morphdom) to do DOM Diffing. It's lightweight so you can use it to create libraries of components that other people can easily add to their pages. 4 | 5 | ## Basic Example 6 | 7 | ```js 8 | const ponies = require('ponies'); 9 | 10 | ponies.register({ 11 | render() { 12 | return ponies.render` 13 | 14 |

Hello ${this.getAttribute('you') || "World"}

15 | this.setAttribute('you', ev.target.value)}/> 16 |
17 | `; 18 | } 19 | }); 20 | ``` 21 | 22 | Note that the root element must have a dash in it's tagName. Then use it like you would any other HTML element. 23 | 24 | ```html 25 | 26 | ``` 27 | 28 | Whenever the element's attributes change the render function gets called again and the element's DOM gets transformed to match the new result. 29 | 30 | ## Lifecycle Callbacks 31 | 32 | [Custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Custom_Elements) often need to do setup when they are first created or attached to the DOM, clean up after they are detached, or custom tasks when their attributes are changed. [Lifecycle callbacks](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Custom_Elements#Lifecycle_callbacks) are functions that you provide to handle these events. Ponies assigns these functions as methods of every instance of your component, so you can refer to the current element using `this`. 33 | 34 | ```js 35 | ponies.register({ 36 | render() { 37 | return ponies.render` 38 | 39 | 42 | 43 | `; 44 | } 45 | attached() { 46 | this.interval = window.setInterval(() => { 47 | this.logs.push(new Date()); 48 | this.update(); 49 | }, 1000); 50 | }, 51 | detached() { 52 | window.clearInterval(this.interval); 53 | } 54 | }); 55 | ``` 56 | 57 | ## Styling 58 | 59 | Ponies registers [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Custom_Elements), but it doesn't use [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Shadow_DOM). This means that the style of your components can be affected by the stylesheet of the page. You can style your components using style attributes which have high specificity, but these can still be overridden with `!important`. 60 | 61 | ## Polyfilling 62 | 63 | Native support for [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Custom_Elements) has been present in Chrome since 2014. [Firefox](https://platform-status.mozilla.org/#custom-elements), and [WebKit](https://webkit.org/status/#feature-custom-elements) support is in development. [Edge](https://developer.microsoft.com/en-us/microsoft-edge/platform/status/customelements) support is in consideration. In the mean time it is advised to use [a polyfill for document.registerElement](https://www.npmjs.com/package/document-register-element). 64 | 65 | ## Transpiling 66 | 67 | ES2015 features including [tagged template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals), classes, and `Object.assign` are used with aplomb. [You know what to do](https://babeljs.io/). -------------------------------------------------------------------------------- /example/react/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "ponies-react-example", 3 | "version": "0.0.0", 4 | "description": "An example using ponies in a react app", 5 | "scripts": { 6 | "test": "echo \"Error: no test specified\" && exit 1", 7 | "start": "budo react.js --host $IP --port $PORT -- -t babelify" 8 | }, 9 | "author": "Jesse Hattabaugh ", 10 | "license": "Artistic-2.0", 11 | "devDependencies": { 12 | "babel-preset-es2015": "^6.9.0", 13 | "babel-preset-react": "^6.11.1", 14 | "babelify": "^7.3.0", 15 | "budo": "^8.3.0", 16 | "react": "^15.1.0", 17 | "react-dom": "^15.1.0" 18 | }, 19 | "babel": { 20 | "presets": [ 21 | "es2015", 22 | "react" 23 | ] 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /example/react/react.js: -------------------------------------------------------------------------------- 1 | require('../ui-ponies/ui-field'); 2 | 3 | const React = require('react'); 4 | const ReactDOM = require('react-dom'); 5 | 6 | const App = React.createClass({ 7 | getInitialState: function () { 8 | return { 9 | name: 'World' 10 | }; 11 | }, 12 | render: function () { 13 | return
14 |

Hello {this.state.name}

15 | console.log(ev)}/> 16 |
; 17 | } 18 | }); 19 | 20 | const root = document.createElement('main'); 21 | document.body.appendChild(root); 22 | 23 | ReactDOM.render(, root); -------------------------------------------------------------------------------- /example/ui-ponies/ui-field.js: -------------------------------------------------------------------------------- 1 | const ponies = require('../../ponies'); 2 | 3 | ponies.register({ 4 | render() { 5 | return ponies.render` 6 | 7 | 8 | 9 | `; 10 | } 11 | }); -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "ponies", 3 | "version": "0.0.1", 4 | "description": "My little library for building Web Components", 5 | "main": "ponies.js", 6 | "scripts": { 7 | "test": "budo test/test.js --dir test --host $IP --port $PORT --live" 8 | }, 9 | "repository": { 10 | "type": "git", 11 | "url": "git+https://github.com/jessehattabaugh/ponies.git" 12 | }, 13 | "keywords": [ 14 | "web-components", 15 | "components", 16 | "custom-elements", 17 | "dom-diffing", 18 | "tagged-template-literals" 19 | ], 20 | "author": "Jesse Hattabaugh ", 21 | "license": "Artistic-2.0", 22 | "bugs": { 23 | "url": "https://github.com/jessehattabaugh/ponies/issues" 24 | }, 25 | "homepage": "https://github.com/jessehattabaugh/ponies#readme", 26 | "dependencies": { 27 | "yo-yo": "^1.2.1" 28 | }, 29 | "devDependencies": { 30 | "budo": "^8.3.0", 31 | "document-register-element": "^0.5.4", 32 | "tape": "^4.6.0" 33 | } 34 | } 35 | -------------------------------------------------------------------------------- /ponies.js: -------------------------------------------------------------------------------- 1 | /*global HTMLElement*/ 2 | 3 | const yo = require('yo-yo'); 4 | 5 | exports.register = register; 6 | exports.render = yo; 7 | 8 | function register(def) { 9 | 10 | if (typeof def !== 'object') { 11 | throw new Error("Definition param must be an object"); 12 | } 13 | if (!def.render || typeof def.render !== 'function') { 14 | throw new Error("Definition object must have a render method"); 15 | } 16 | 17 | // Get the tagName of the root node returned from render() 18 | // since we are doing this before an element is instantiated we bind to a blank element 19 | let el = def.render.bind(document.createElement('DIV'))(); 20 | if (!el instanceof HTMLElement) { 21 | throw new Error("Render function must return a dom node"); 22 | } 23 | 24 | // Check for a dash in the tagname 25 | let tagName = el.tagName; 26 | if (tagName.indexOf('-') === -1) { 27 | throw new Error("The tagName of the root vnode returned by render() must contain a dash"); 28 | } 29 | 30 | class CustomElement extends HTMLElement { 31 | 32 | update() { 33 | //console.info(tagName + " updated"); 34 | yo.update(this, this.render()); 35 | } 36 | 37 | createdCallback() { 38 | //console.info(tagName + " created"); 39 | if (this.created) this.created(); 40 | } 41 | 42 | attachedCallback() { 43 | //console.info(tagName + " attached"); 44 | this.update(); 45 | this.isAttached = true; 46 | if (this.attached) this.attached(); 47 | } 48 | 49 | attributeChangedCallback(attrName, oldVal, newVal) { 50 | //console.info(`${tagName}'s ${attrName} changed from ${oldVal} to ${newVal}`); 51 | 52 | // don't update unattached elements 53 | if (!this.isAttached) return; 54 | 55 | this.update(); 56 | if (this.changed) this.changed(attrName, oldVal, newVal); 57 | } 58 | 59 | detachedCallback() { 60 | //console.info(tagName + " detached"); 61 | if (this.detached) this.detached(); 62 | } 63 | } 64 | 65 | // mixin the definition object 66 | Object.assign(CustomElement.prototype, def); 67 | 68 | document.registerElement(tagName, CustomElement); 69 | } -------------------------------------------------------------------------------- /test/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 |
7 |
8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | -------------------------------------------------------------------------------- /test/test.js: -------------------------------------------------------------------------------- 1 | const test = require('tape'); 2 | const p = require('../ponies').register; 3 | const h = require('../ponies').render; 4 | 5 | const $ = document.getElementById.bind(document); 6 | 7 | // polyfills 8 | require('document-register-element'); 9 | 10 | // one 11 | test("Exports the right stuff", function (t) { 12 | t.plan(2); 13 | t.equal(typeof p, 'function'); 14 | t.equal(h`
`.tagName, 'DIV'); 15 | }); 16 | 17 | // two 18 | test("Throws exceptions on invalid definition", function (t) { 19 | t.plan(6); 20 | t.throws(function () { 21 | p(); 22 | }, "no arguments"); 23 | t.throws(function () { 24 | p({}); 25 | }, "no render property"); 26 | t.throws(function () { 27 | p({render: 'invalid'}); 28 | }, "render property not a function"); 29 | t.throws(function () { 30 | p({render() {return 'invalid';}}); 31 | }, "render function doesn't return a node"); 32 | t.throws(function () { 33 | p({render() {return h``;}}); 34 | }, "root element tagName must contain a dash"); 35 | t.doesNotThrow(() => { 36 | p({render() {return h``;}}); 37 | }, "acceptable definition doesn't throw an error"); 38 | }); 39 | 40 | // three 41 | test("Replaces a Custom Element's DOM with a VDOM", function (t) { 42 | t.plan(3); 43 | t.equal($('id-three-old').tagName, 'DIV'); 44 | p({ 45 | render() { 46 | return h`
`; 47 | } 48 | }); 49 | t.equal($('id-three-old'), null); 50 | t.equal($('id-three-new').tagName, 'DIV'); 51 | }); 52 | 53 | // four 54 | test("Attached callback is executed", function (t) { 55 | t.plan(1); 56 | p({ 57 | render() { 58 | return h``; 59 | }, 60 | attached() { 61 | t.pass("callback called"); 62 | } 63 | }); 64 | t.timeoutAfter(1000); 65 | }); 66 | 67 | // five 68 | test("Render function can use attributes of element to render", function (t) { 69 | t.plan(1); 70 | p({ 71 | render() { 72 | let textFive = this.attributes['att-five'] ? this.attributes['att-five'].value: 'val-null'; 73 | return h`
${textFive}
`; 74 | } 75 | }); 76 | t.equal($('id-five').innerText, 'val-five'); 77 | }); 78 | 79 | // six 80 | test("Mutations of the element's attributes will trigger a render", function (t) { 81 | t.plan(1); 82 | p({ 83 | render() { 84 | let textSix = this.attributes['att-six'] ? this.attributes['att-six'].value : 'val-null'; 85 | return h`${textSix}`; 86 | } 87 | }); 88 | $('id-six').setAttribute('att-six', 'val-six-new'); 89 | // todo: if dom update takes too long this timeout interval might not work 90 | setTimeout(function () { 91 | t.equal($('id-six').innerText, 'val-six-new'); 92 | }, 1000); 93 | }); --------------------------------------------------------------------------------