chore: clean up; update readme docs

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.
+ The `props` property of the `WebComponent` interface is provided for easy read/write access to a camelCase counterpart of *any* observed attribute.
-
-This API gives us read/write access to any attribute properties:
 
 ```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. `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
+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
 

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",
+  "repository": "https://github.com/ayoayco/web-component-base",
-  "homepage": "https://git.sr.ht/~ayoayco/web-component-base#readme",
+  "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",

src/WebComponent.js

@@ -3,23 +3,6 @@
  * @license MIT <https://opensource.org/licenses/MIT>
  * @author Ayo Ayco <https://ayo.ayco.io>
  * @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 `
- *         <h1>Hello ${this.props.dataName}${this.props.emotion === "sad" ? ". 😭" : "! 🙌"}</h1>`;
- *   }
- * }
- *
- * 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 `
-   *        <h1>Hello ${this.props.myProp}</h1>
-   *        <h2>Hello ${this["my-prop"]}</h2>
-   *     `;
-   *   }
-   * }
    */
   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.
+   * Triggered after view is initialized
-   * @returns {void}
    */
   afterViewInit() {}
 
   /**
-   * Triggered when the component is connected to the DOM. Best for initializing the component like attaching event handlers.
+   * Triggered when the component is connected to the DOM
-   * @returns {void}
    */
   onInit() {}
 
   /**
-   * Triggered when the component is disconnected from the DOM. Any initialization done in `onInit` must be undone here.
+   * Triggered when the component is disconnected from the DOM
-   * @returns {void}
    */
   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;