{"_id":"@ahabra/webitem","_rev":"5-3624f692c01b9f0eb5732408a010cd53","name":"@ahabra/webitem","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.1":{"name":"@ahabra/webitem","version":"0.0.1","description":"Library to simplify crerating Web Components/Custom Elements","author":{"name":"Abdul Habra"},"license":"Apache","repository":{"type":"git","url":"git+https://github.com/ahabra/webitem.git"},"main":"dist/webitem-esm.js","keywords":["web component","custom element"],"engines":{"node":">=15.0.0","npm":">=7.0.0"},"scripts":{"clean":"node scripts/clean.js","build":"node scripts/build.js","server":"node scripts/server.js","test":"web-test-runner","test:watch":"web-test-runner --watch","lint":"eslint src --fix"},"devDependencies":{"@esm-bundle/chai":"^4.1.5","@web/test-runner":"^0.10.0","@web/test-runner-commands":"^0.2.1","@web/test-runner-puppeteer":"^0.7.3","chalk":"^2.4.1","esbuild":"^0.8.12","eslint":"^7.14.0","fs-extra":"^9.0.1","serve":"^11.3.2"},"dependencies":{"@ahabra/data-bind":"^0.5.0"},"gitHead":"b5b6104f0439e692ac3df9d698aa074795e4eba5","bugs":{"url":"https://github.com/ahabra/webitem/issues"},"homepage":"https://github.com/ahabra/webitem#readme","_id":"@ahabra/webitem@0.0.1","_nodeVersion":"15.2.1","_npmVersion":"7.0.10","dist":{"integrity":"sha512-BfBmxOQukl/oClpP/lMJf46VaFTMXbt1YiYWieMcHCajOlYdsjf/P4muCLWOHUYDN1C/iYC5yHN2znir/T+brw==","shasum":"0b7e777f321f7fd0980e47ede10f0b6a2bb4bc70","tarball":"https://registry.npmjs.org/@ahabra/webitem/-/webitem-0.0.1.tgz","fileCount":25,"unpackedSize":56085,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJf85RMCRA9TVsSAnZWagAAZZ8P/iYDj2QiHOv/z7p5tp89\nGkXLDlv6dX4hSHCVP1EGPRmN7KjHRyNeLpoCtUuF32kgoJXkaZDpaB0ZcpgR\n+CEoJjndBZeotjdBOSsTngbpKbGQy0oAxj++8RcEW8geC4aeKgNwkvrepBAP\nXKVivJ+creHT0Ez5NzEqO+FOulzsxu3+tJEWo7fNJaxPSOmKgD7156eAh2+9\n5K60jIL2U/2qffDV+lw207dbldLP3U3BYsz3wf6l7j28ZRKqndFvsjA3jj5U\nyqweqJSY0Ax2susGf42A7AcqQUjIHLaSa4x+geS8IViwyESxpMfKSD5WMLXM\n4u/W095HZnVPOAuxPLBW00jU18RU7dSnpJEAvApidYt5l95YVXQZU5LS8f0G\n1K/347ZYd1NNC0ko8cQz8JVwo8Bg90Z12vg/kVslUnSUiP7goATb3G9xgJoM\n5MMGZ4+3vJk5Ac042PsCx3PeQNhFzCDuDJS54ckMI23it3V0ds782UJxCFp9\n3Wq8QRJaslY+kVuSvODmz3rPCkoFZ8t556I0Rpi16ut9fmmIHZ3RdlE0mJ+p\nyW9KQa9py+c8zzlqfe/18G6uBcotd/g/B/Z2B1C5nlUhn3MQ8YZ6OVEHq2Qz\n/imkAFbuqCGYkRFKDibiOUIDjzVupUi5gl30YRiteEM8HfmmedzeMZKBddPz\nuH0S\r\n=g+Sn\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIGljb7ahrz/6cWjLYUTdYVQZPt1am6I4ZzKoqTs3MuNeAiEAut6MhGC/V7xI9HttsOAnqjeBkmp+3G+lduCSCwANGvg="}]},"_npmUser":{"name":"ahabra","email":"ahabra@yahoo.com"},"directories":{},"maintainers":[{"name":"ahabra","email":"ahabra@yahoo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/webitem_0.0.1_1609798732047_0.4286591274474778"},"_hasShrinkwrap":false,"deprecated":"This package has moved to @techexp/webitem"},"0.0.2":{"name":"@ahabra/webitem","version":"0.0.2","description":"Library to simplify crerating Web Components/Custom Elements","author":{"name":"Abdul Habra"},"license":"Apache","repository":{"type":"git","url":"git+https://github.com/ahabra/webitem.git"},"main":"dist/webitem-esm.js","keywords":["web component","custom element"],"engines":{"node":">=15.0.0","npm":">=7.0.0"},"scripts":{"clean":"node scripts/clean.js","build":"node scripts/build.js","server":"node scripts/server.js","test":"web-test-runner","test:watch":"web-test-runner --watch","lint":"eslint src --fix"},"devDependencies":{"@esm-bundle/chai":"^4.1.5","@web/test-runner":"^0.10.0","@web/test-runner-commands":"^0.2.1","@web/test-runner-puppeteer":"^0.7.3","chalk":"^2.4.1","esbuild":"^0.8.12","eslint":"^7.14.0","fs-extra":"^9.0.1","serve":"^11.3.2"},"dependencies":{"@ahabra/data-bind":"^0.5.0"},"gitHead":"d40a53fe643526da39e1e0f33b4bdfbd14ce47a7","bugs":{"url":"https://github.com/ahabra/webitem/issues"},"homepage":"https://github.com/ahabra/webitem#readme","_id":"@ahabra/webitem@0.0.2","_nodeVersion":"15.2.1","_npmVersion":"7.0.10","dist":{"integrity":"sha512-wA1s/7SfOgPqYeIsWu7+gEJ2VEosLJ9c2D7PofYPQsQoJTYPsowBFUo9Ndhe7ksAPrs25n9PXC/TfLboZy2Iow==","shasum":"cb564b54f8f36fa0d67bf538b0a5599ff2c14bc8","tarball":"https://registry.npmjs.org/@ahabra/webitem/-/webitem-0.0.2.tgz","fileCount":25,"unpackedSize":62276,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJf9SgXCRA9TVsSAnZWagAAdKAP/0lNDeHUVlzFnLXjP732\nEInwtyDII4K6A86K4mBBCrXMAPhEkSke6JGpxry9pxVjePDQqlf23IR6oyVC\nBWzxBCKzl2aRsbtrav9lCeCKvtUyAILCnWllsehdeLt8tCqduQ7yFUBTLy7Z\niO39sFUrVb7nroc/kaUEVMkiS4rq3DyuJmZfviZ36KlgKGjqxQ447FIyXtUP\nHf6vbSznzzAki7Z2RdAOAzD+RzEyCCCfPDts/1qA6c0/GDCrkWqiYu7JjP1N\n9IE0/X1U/KmzKkRWpjqKkUiWatUrQJSzWo0kyn1vkh1GkB7ziz4Awzx8ipdH\n8HDS1pjqPx+by7Ve9UQc6H8AmNTOIILvpDoibdmupFzvouMuxTj3LlU3/51y\nZ9XKpTCbtKfM+WWaBSVSuzpC73Z928SmyscSRKgePVdqtMerQ3+2GQftzlwL\nxyxzwTEc04uGlHI92th5txwTMutwIMOI/IFXPwKLNks+nrR/W0ToNWy+lTyf\nYvI9CKiQbJS9/AiqKc9LLTrB7ueM79K5fbtz6ISOQV6PaoW8knVSW0aYmKen\nmq3fpEvF5tscs5svKSLbXhwvw0a5Irmdvb2woeSiOyVb3Zyelu2mzHK4XvKW\nWPAn6TgF9kjESQPO64mwTUWF6JeDnfUQOmqapr+4Agu9q135kiUa9MxZMsQz\nfJHg\r\n=HV7m\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCcdi9Vd2PhbBLMc+sLXmyW36zTCUU10/Y1CLYtrgUoogIhAM8+KWry7070Xh0NqAFpp2OM01QLbbci0wOJX5C3BEhP"}]},"_npmUser":{"name":"ahabra","email":"ahabra@yahoo.com"},"directories":{},"maintainers":[{"name":"ahabra","email":"ahabra@yahoo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/webitem_0.0.2_1609902103266_0.1762040330961998"},"_hasShrinkwrap":false,"deprecated":"This package has moved to @techexp/webitem"},"0.1.0":{"name":"@ahabra/webitem","version":"0.1.0","description":"Library to simplify crerating Web Components/Custom Elements","author":{"name":"Abdul Habra"},"license":"Apache","repository":{"type":"git","url":"git+https://github.com/ahabra/webitem.git"},"main":"dist/webitem-esm.js","keywords":["web component","custom element"],"engines":{"node":">=15.0.0","npm":">=7.0.0"},"scripts":{"clean":"node scripts/clean.js","build":"node scripts/build.js","server":"node scripts/server.js","test":"web-test-runner","test:watch":"web-test-runner --watch","lint":"eslint src --fix"},"devDependencies":{"@esm-bundle/chai":"^4.1.5","@web/test-runner":"^0.12.6","@web/test-runner-commands":"^0.4.0","@web/test-runner-puppeteer":"^0.9.1","chalk":"^4.1.0","esbuild":"^0.8.34","eslint":"^7.18.0","fs-extra":"^9.1.0","serve":"^11.3.2"},"dependencies":{"@ahabra/data-bind":"^0.6.0"},"gitHead":"9d63ecd34bdbf12e8a206a5aceea48304f0bc592","bugs":{"url":"https://github.com/ahabra/webitem/issues"},"homepage":"https://github.com/ahabra/webitem#readme","_id":"@ahabra/webitem@0.1.0","_nodeVersion":"15.2.1","_npmVersion":"7.0.10","dist":{"integrity":"sha512-O5NG9TAWspZhAZIAXrJcFK/oM/LQilWMhDO0bUqUiUi9iZYrCISj54DRWT/hfX/uFrI+ckGIV6ERkvVgafTiGg==","shasum":"fb5f7485d476220788dba76b5e3f1ce63403dbf5","tarball":"https://registry.npmjs.org/@ahabra/webitem/-/webitem-0.1.0.tgz","fileCount":25,"unpackedSize":71961,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJgEamkCRA9TVsSAnZWagAAZK4P/R+J9lwU8F3mqVXI2usq\njv5OVdJ1t1fdSHtsUJiD7OizqC84TN0MUcs6+Wi3r7yOpNsQMTaYfi/eB9Zx\n2w4HwIFKCglyP88Dm79CPGBsvpL+qzbS6LmfDfAObBzyDJGzm//zanB4EKtD\nfOOqMXrdGJtuRlnDNTSgGp9rlydFc7Ye1hB95btej4lx4cFJaLxUnhITEuP+\nNkDSSGvAwFALeq0PLcUagQ5K9M68b103ogk1arUscDlT9kusu0Hap8LXMyLB\n6tHHFAmPdj6lmI/mePr9e2CU25KVeuOo8gnXwtnI23eBCTdmDv41mpHdIv05\njZHSDINCbGVKiKRjNEwxAdWaek4G1RYuNjF0KkBgSK6SABihqzoSVYWesWR/\ngwv5maOz8JUQ0I1x9mwFNzhYI05/h/MLDLyTCJZvIE1KFTs7k1B22Es8uy8d\naegQych6frvxGjsJynNOUewZ55GX12VtCU98UxRJ3BNMKKax7TQDMFiYqF/V\nQeSgl7Ci0W1ZzvpLPqJBTS19Zq29nkvbST+2Nnb7jQkoHfr2yexLFxAOhZpM\nypdI2n/KAiJ5Pite742gv0Xz3g2Gwf45nAUNjHHh6iMYPQxrsKziNPRGCg3b\nTy+hUXsP/8g6ZNkp0QPAAg17J7vgxNTgJJhdw7ZcztEnCKQWJET6agSZWj9c\nvwqI\r\n=hg93\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCRz+YyQRJLJ3dn1isVYMMm7wzmO4nd6f577fahIB5PzgIhAPa6wYXpLrMO1z+t/rmylLLJU/IwmoN6NiIC86ekc4mu"}]},"_npmUser":{"name":"ahabra","email":"ahabra@yahoo.com"},"directories":{},"maintainers":[{"name":"ahabra","email":"ahabra@yahoo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/webitem_0.1.0_1611770276153_0.6930715488766417"},"_hasShrinkwrap":false,"deprecated":"This package has moved to @techexp/webitem"}},"time":{"created":"2021-01-04T22:18:51.994Z","0.0.1":"2021-01-04T22:18:52.186Z","modified":"2022-04-04T12:11:49.694Z","0.0.2":"2021-01-06T03:01:43.404Z","0.1.0":"2021-01-27T17:57:56.282Z"},"maintainers":[{"email":"ahabra@yahoo.com","name":"abdul-techexp"}],"description":"Library to simplify crerating Web Components/Custom Elements","homepage":"https://github.com/ahabra/webitem#readme","keywords":["web component","custom element"],"repository":{"type":"git","url":"git+https://github.com/ahabra/webitem.git"},"author":{"name":"Abdul Habra"},"bugs":{"url":"https://github.com/ahabra/webitem/issues"},"license":"Apache","readme":"# WEBITEM.JS\nA library to simplify creating HTML5 Web Components (Custom Elements).\n\n## Introduction\nIn modern HTML, you can create web components using [customElements.define()](https://developer.mozilla.org/en-US/docs/Web/Web_Components). This API is powerfull, but can be verbose and complicated. The _webitem.js_ library provides a wrapper around that API in an attempt to make it simple for the application's programmer.\n\nThe size of this library, minified and zipped is about 2KB.\n\n## Install\nYou can use this library as either an EcmaScript module, or the old way as a script which you include in your html file.\n\n### Install as NPM EcmaScript Module\nIf you plan to use this package as an NPM module:\n\n```bash\n npm install @ahabra/webitem\n```\n\n### Install as a Script\nIf you plan to use this package as a JS script library\n\n```html\n \n```\n\nAlternatively, you can download the file `https://raw.githubusercontent.com/ahabra/webitem/master/dist/webitem-script-min.js` and use directly. Note that there is a non-minified version at the same location.\n\n## Usage\nIf you installed as an EcmaScript module\n```js\nimport * as webitem from '@ahabra/webitem'\n```\n\nIf you installed as a Script, the library is available at `window.webitem`\n\n### Quick Code Demo\nThis example shows how to create a bare-bone web item, it creates a Web Component named `bare-bone` which you can use in the html code.\n\n```js\nimport * as webitem from '@ahabra/webitem'\n// or use window.webitem if you are using the script.\n\nwebitem.defineElement({\n nameWithDash: 'bare-bone',\n html: `\n
\n

Bare-Bone Web Item

\n
\n `\n})\n```\n\n```html\n\n\n```\n\n### API\nThis library consists of a single function `defineElement(object)`. It accepts a single argument object with the following keys:\n\n1. `nameWithDash`: Required, String. Name of the web component. Must contain the dash/hyphen '`-`' character within the name. This is required by the browser's API.\n2. `html`: Optional, String or Function. The HTML content of the web component.\n 1. When `html` is a string, it is the literal html of the compnent.\n 2. When `html` is a function, the function will have this signature:\n `(webitem) => string`. Look down for an example.\n3. `css`: Optional, String. The CSS to apply on the web component. This CSS will be name-spaced within the component, and is not visible outside it.\n4. `propertyList`: Optional, Array of objects. Objects defining properties of the component. Each property definition consists of `{name, value, [sel], [attr]}`.\n 1. `name`: Name of the property.\n 2. `value`: Initial value of the property.\n 3. `sel`: Optional, String. A CSS selector that binds the property to a DOM element in the component.\n 4. `attr`: Optional, String. An attribute on the DOM element to bind its value.\n 5. `onChange`: Optional. Function. A function to be called when the property's value change through an API call. The function can take three arguments `(webitem, oldValue, newValue)`\n5. `eventHandlerList`: Optional, Array of objects. Objects define event handlers of the component. Each event handler definition consists of `{sel, eventName, listener}`.\n 1. `sel`: A CSS selector of an element in the component.\n 2. `eventName`: Name of the event to bind to, e.g. `click`.\n 3. `listener`: A function to be called when the event occures. The function accepts two arguments, an [event](https://developer.mozilla.org/en-US/docs/Web/API/Event) object, and `webitem` which is the web component.\n6. `display`: Optional, String. A CSS display attribute. A possible value can be `inline` (default if missing), `inline-block`, or `block`. This controls how the component is displayed inside its container.\n\n\n#### Note About Using Common CSS Files\nCSS applied to a web component (_through shadow DOM_) is scoped to the component, it does not interact with CSS outside the component.\n\nIf you need to use a common CSS file within the component, a possible solution is to use the `` tag in the component's html, for exmaple, add the next line at the top of your component's html:\n\n```html\n\n```\n\n## Examples\nThere is a full set of examples in the repo's `src/` directory in both `index.html` and `test/webitem.test.js`. Next we will show some as well.\n\n### Provide html as a function\nThis example shows how to provide the html content of the component as a function. The function takes the comonent itself as an argument and returns a string representing the html of the component.\n\nThis approach allows you to introspect the definition of the element as given on the page.\n\n```js\nwebitem.defineElement({\n nameWithDash: 'wi-t3',\n html: el => {\n // el references the instance of the web component\n const h = el.innerHTML // Hello\n const attr = el.getAttribute('at1') // world\n return `\n
\n

${h}

\n at1: ${attr}\n
\n `\n }\n})\n```\n\n```html\nHello\n```\n\nNotice how you can access the data in the component's instance.\n\n### Bound Properties\nOne of the distinct features of this library is the ability to bind properties to DOM elements within the component. Consider this example:\n\n```js\nwebitem.defineElement({\n nameWithDash: 'wi-t5',\n html: `\n

wi-t5 - Bound Properties

\n In the browser's console, inspect $('wi-t5').properties\n

Country:

\n

Capital:

\n `,\n propertyList: [\n {name: 'country', value:'Syria', sel: '#country'},\n {name: 'capital', value:'Damascus', sel:'#capital'},\n {name: 'style', value:'color:green', sel:'h3', attr:'style'}\n ]\n})\n```\n\n```html\n\n```\n\n_Note: The `$()` function listed above with the browser console is NOT a jQuery function, it is an alias for `document.querySelector()` that most browsers support at the console._\n\nThe `propertyList` array defines three properties that are bound to three elements in the html of the component:\n1. `country` property has an initial value of `Syria` and is bound to the input element with CSS selector `#country`.\n2. `capital` property has an initial value of `Damascus` and is bound to the input element with CSS selector `#capital`.\n3. `style` property has an initial value of `color:green` and is bound to the `style` attribute of the element with CSS selector `h3`.\n\nTo use these properties:\n```js\n$('#bounded').properties.country = 'USA'\n$('#bounded').properties.capital = 'DC'\n$('#bounded').properties.style = 'color.blue'\n\nconsole.log($('#bounded').properties.country) // prints USA\n```\n\nThe binding is _bi-directional_, changing the property's value will change the view, and changing the value in the view will change the property's value.\n\nBinding properties to DOM elements is optional, you can choose to define a proiperty without `sel` value.\n\nFor more details about bound properties, check [Data Bind](https://www.npmjs.com/package/@ahabra/data-bind) NPM package which is used by this library.\n\n\n### Event Handler\nYou can define a function to be invoked when a certain DOM event happens.\n\n```js\nwebitem.defineElement({\n nameWithDash: 'wi-t6',\n html: `\n \n 0\n `,\n propertyList: [\n {name: 'counter', value: '0', sel: '#counter'}\n ],\n eventHandlerList: [\n {\n sel: 'button',\n eventName: 'click',\n listener: (ev, el) => {\n const counter = parseInt(el.properties.counter, 10)\n el.properties.counter = counter + 1\n }\n }\n ]\n})\n```\n\nHere we define a property `counter` which is bound to the span with `id=\"counter\"`.\n\nWe also define a listener for the `click` event on `button`. The listener takes two arguments, the [event](https://developer.mozilla.org/en-US/docs/Web/API/Event) object and the web component element.\n\n### Actions\nYou can define actions (functions) that can execute with the web item context. Consider this example:\n\n```js\nwebitem.defineElement({\n nameWithDash: 'wi-t8',\n html: `

wi-t8 - Actions

\n `,\n propertyList: [\n {name: 'color', value: 'green', sel:'button', attr: 'style'}\n ],\n eventHandlerList: [\n {\n sel: 'button',\n eventName: 'click',\n listener: (ev, el) => el.actions.updateColor(el)\n }\n ],\n actionList: [\n {name: 'updateColor', action: function(el) {\n if (el !== this) {\n console.warn(`Warning: 'this' should be equal to 'el'`)\n }\n el.properties.color = `background-color:${getRandomColor()}`\n }}\n ]\n})\n```\n\n```html\n\n```\n\nThe `actionList` is an array which contains objects with two keys:\n1. `name`: The name of the action (function)\n2. `action`: The definition of the action/function. **Note:** If you declare the action as a _classic_ function (as opposed to an arrow '`=>`' function) then its `this` variable will point to the web item itself.\n\nYou can access actions through the `actions` property, so for the above example, you can:\n\n```js\n$('wi-t8').actions.updateColor()\n```\n\n### Property's Change Callback\nWhen you define a property, you can provide a callback function to be called whenever the property's value is changed (throug an API call).\nThe function expects two arguments, oldValue and newValue.\nConsider this example:\n\n```js\nwebitem.defineElement({\n nameWithDash: 'wi-t9',\n html: `\n

wi-t9 - onChange

\n \n oldValue: ,\n newValue: \n `,\n propertyList: [\n {name: 'color', value: 'green',\n onChange: (el, oldValue, newValue) => {\n el.shadowRoot.querySelector('button').style = `background-color:${newValue}`\n\n function showColor(selector, color) {\n const span = el.shadowRoot.querySelector(selector)\n span.innerText = color\n span.style = `background-color:${color}`\n }\n showColor('#oldValue', oldValue)\n showColor('#newValue', newValue)\n }}\n ],\n eventHandlerList: [\n {\n sel: 'button',\n eventName: 'click',\n listener: (ev, el) => {\n // getRandomColor() returns names of random colors\n el.properties.color = getRandomColor()\n }\n }\n ]\n})\n```\n\n```html\n\n```\n\nIn the above example, we change the `color` property in the click listener, which will invoke the `onChange` callbak on the propeerty.","readmeFilename":"README.md"}