diff --git a/README.md b/README.md index 245d68f..125229a 100644 --- a/README.md +++ b/README.md @@ -103,9 +103,7 @@ This mental model attempts to reduce the cognitive complexity of authoring compo ## Prop Access - The `WebComponent.props` read-only property is provided for easy access to *any* observed attribute. - -This API gives us read/write access to any attribute properties: + The `props` property of the `WebComponent` interface is provided for easy read/write access to a camelCase counterpart of *any* observed attribute. ```js class HelloWorld extends WebComponent { @@ -122,8 +120,7 @@ class HelloWorld extends WebComponent { } ``` -Assigning value to the `props.camelCase` counterpart will trigger an attribute change hook. - +Assigning a value to the `props.camelCase` counterpart of an observed attribute will trigger an "attribute change" hook. For example, assigning a value like so: ``` @@ -131,21 +128,20 @@ this.props.myName = 'hello' ``` ...is like calling the following: - ``` this.setAttribute('my-name','hello'); ``` Therefore, this will tell the browser that the UI needs a render if the attribute is one of the component's observed attributes we explicitly provided with `static properties = ['my-name']`; -> This works like [`HTMLElement.dataset`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset), except `dataset` is only for attributes prefixed with `data-*`. A camelCase counterpart using `props` will give read/write access to any attribute, with or without the `data-*` prefix. - +> The `props` property of `WebComponent` works like `HTMLElement.dataset`, except `dataset` is only for attributes prefixed with `data-`. A camelCase counterpart using `props` will give read/write access to any attribute, with or without the `data-` prefix. +> However, note that like `HTMLElement.dataset`, values assigned to properties using `WebComponent.props` is always converted into string. This will be improved in later versions. ### Alternatives The current alternatives are using what `HTMLElement` provides out-of-the-box, which are: -1. `HTMLElement.dataset` for attributes prefixed with `data-*` -1. Methods for reading/writing attribute values: `setAttribute(...)` and `getAttribute(...)`; note that managing the attribute names as strings can be difficult as the code grows +1. `HTMLElement.dataset` for attributes prefixed with `data-*`. Read more about this [`on MDN`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset). +1. Methods for reading/writing attribute values: `setAttribute(...)` and `getAttribute(...)`; note that managing the attribute names as strings can be difficult as the code grows. ## Quick Start Example diff --git a/package.json b/package.json index f22f5fa..546eaa4 100644 --- a/package.json +++ b/package.json @@ -19,8 +19,8 @@ "publish:minor": "npm version minor && npm run pub", "check:size": "npm run build && size-limit ./dist/WebComponent.js" }, - "repository": "https://git.sr.ht/~ayoayco/web-component-base", - "homepage": "https://git.sr.ht/~ayoayco/web-component-base#readme", + "repository": "https://github.com/ayoayco/web-component-base", + "homepage": "https://WebComponent.io", "keywords": [ "web components", "web component", @@ -30,7 +30,7 @@ "author": "Ayo Ayco", "license": "MIT", "bugs": { - "url": "https://todo.sr.ht/~ayoayco/web-component-base" + "url": "https://github.com/ayoayco/web-component-base/issues" }, "devDependencies": { "@size-limit/preset-small-lib": "^11.0.0", diff --git a/src/WebComponent.js b/src/WebComponent.js index ae38244..056b6f8 100644 --- a/src/WebComponent.js +++ b/src/WebComponent.js @@ -3,23 +3,6 @@ * @license MIT * @author Ayo Ayco * @see https://www.npmjs.com/package/web-component-base#readme - * @example - * - * import WebComponent from "https://unpkg.com/web-component-base/index.js"; - * - * class HelloWorld extends WebComponent { - * // tell the browser which attributes to cause a render - * static properties = ["data-name", "emotion"]; - * - * // give the component a readonly template - * // note: props have kebab-case & camelCase counterparts - * get template() { - * return ` - *

Hello ${this.props.dataName}${this.props.emotion === "sad" ? ". 😭" : "! 🙌"}

`; - * } - * } - * - * customElements.define('hello-world', HelloWorld); */ export class WebComponent extends HTMLElement { /** @@ -39,23 +22,10 @@ export class WebComponent extends HTMLElement { /** * Read-only property containing camelCase counterparts of observed attributes. - * This works like HTMLElement.dataset except dataset is only for attributes prefixed with `data-`. - * A camelCase counterpart using `WebComponent.props` will give read/write access to any attribute, with or without the `data-*` prefix. * @see https://www.npmjs.com/package/web-component-base#prop-access * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset * @typedef {{[name: string]: any}} PropStringMap * @type {PropStringMap} - * @example - * - * class HelloWorld extends WebComponent { - * static properties = ["my-prop"]; - * get template() { - * return ` - *

Hello ${this.props.myProp}

- *

Hello ${this["my-prop"]}

- * `; - * } - * } */ get props() { return this.#props; @@ -67,20 +37,17 @@ export class WebComponent extends HTMLElement { #props; /** - * Triggered after view is initialized. Best for querying DOM nodes that will only exist after render. - * @returns {void} + * Triggered after view is initialized */ afterViewInit() {} /** - * Triggered when the component is connected to the DOM. Best for initializing the component like attaching event handlers. - * @returns {void} + * Triggered when the component is connected to the DOM */ onInit() {} /** - * Triggered when the component is disconnected from the DOM. Any initialization done in `onInit` must be undone here. - * @returns {void} + * Triggered when the component is disconnected from the DOM */ onDestroy() {} @@ -91,7 +58,6 @@ export class WebComponent extends HTMLElement { * previousValue: any, * currentValue: any * }} changes - * @returns {void} */ onChanges(changes) {} @@ -179,6 +145,9 @@ export class WebComponent extends HTMLElement { }, }); + /** + * Initialize the `props` proxy object + */ #initializeProps() { if (!this.#props) { const { ...clone } = this; @@ -190,4 +159,4 @@ export class WebComponent extends HTMLElement { } } -export default WebComponent; // remove on v2 +export default WebComponent; \ No newline at end of file