fix: Documentation and commentS (#15)

nfreear · Mar 14, 2022 · 15b39e6 · 15b39e6
1 parent f251bbe
commit 15b39e6
Show file tree

Hide file tree

Showing 16 changed files with 84 additions and 54 deletions.
diff --git a/README.md b/README.md
@@ -41,10 +41,14 @@ About [Web Components][mdn].
 ```js
 import { customImport } from 'https://nfreear.github.io/web-components/custom.js';
 
-const MOD = await customImport('my-star-rating,my-map');
+const MOD = await customImport('my-star-rating, my-skip-link');
 ```
 
+Then:
+
 ```html
+<my-skip-link></my-skip-link>
+
 <my-star-rating></my-star-rating>
 ```
 

diff --git a/demo/app.js b/demo/app.js
@@ -1,5 +1,5 @@
 /**
- * Javascript specific to the Demo.
+ * Javascript specific to the TTS Demo.
  *
  * @copyright © Nick Freear, 27-Jan-2022.
  */

diff --git a/demo/index.html b/demo/index.html
@@ -1,6 +1,6 @@
 <!doctype html><html lang="en" style="opacity:0"><title> My Web Components </title>
 
-<meta name="robots" content="noindex">
+<!-- <meta name="robots" content="noindex"> -->
 <meta name="viewport" content="width=device-width,initial-scale=1">
 
 <link rel="stylesheet" href="style/app.css" />
@@ -14,12 +14,14 @@ <h2> Demo Index </h2>
   <ol>
     <li><a href="my-analytics.html"   >my-analytics</a>
     <li><a href="my-busy-spinner.html">my-busy-spinner</a>
+    <!-- <li><a href="my-font.html"        >my-font</a> -->
     <li><a href="my-map.html"         >my-map</a>
     <li><a href="my-notice.html"      >my-notice</a>
     <li><a href="my-options.html"     >my-options</a>
     <li><a href="my-page.html"        >my-page</a>
     <li><a href="my-skip-link.html"   >my-skip-link</a>
     <li><a href="my-star-rating.html" >my-star-rating</a>
+    <li><a href="my-speech.html"      >my-text-to-speech</a>
   </ol>
 
 </my-page>

diff --git a/demo/my-analytics.html b/demo/my-analytics.html
@@ -20,10 +20,6 @@ <h2> my-analytics </h2>
 &lt;/my-analytics>
 </my-code>
 
-<my-code language="javascript">
-console.debug('Hello world');
-</my-code>
-
 </my-page>
 
 

diff --git a/demo/my-bookmarklet.html b/demo/my-bookmarklet.html
@@ -1,11 +1,16 @@
-<!doctype html><html lang="en" style="opacity:0"><title> My Web Components </title>
+<!doctype html><html lang="en" style="opacity:0"><title> my-bookmarklet </title>
 
 <meta name="robots" content="noindex">
 <meta name="viewport" content="width=device-width,initial-scale=1">
 
 <link rel="stylesheet" href="style/app.css" />
 
 <my-page>
+  <h2> my-bookmarklet </h2>
+
+  <p> Embed a bookmarklet Javascript. </p>
+
+  <p> Uses <a href="https://terser.org/">terser</a> and <a href="https://craig.is/making/rainbows">Rainbow</a>. </p>
 
   <my-bookmarklet
     src="./data/example.bookmarklet.js"

diff --git a/demo/my-busy-spinner.html b/demo/my-busy-spinner.html
@@ -8,6 +8,8 @@
 <my-page>
   <h2> my-busy-spinner </h2>
 
+  <p> A Busy Spinner animation - pure CSS. </p>
+
   <my-busy-spinner></my-busy-spinner>
 
 </my-page>

diff --git a/demo/my-map.html b/demo/my-map.html
@@ -13,6 +13,10 @@
 >
   <h1> my-map Web Component </h1>
 
+  <p> Easily embed a map powered by <a href="https://leafletjs.com/">Leaflet.js</a>
+    — optionally with a GeoJSON feed. Includes accessibility fixes.
+  </p>
+
   <p> A map showing London landmarks. </p>
 
   <my-code>

diff --git a/demo/my-skip-link.html b/demo/my-skip-link.html
@@ -8,13 +8,15 @@
 <my-page>
   <h2> Skip link </h2>
 
+  <p> Add a <q>skip to main content</q> link which becomes visible on focus. </p>
+
   <p> The main content, with a <a href="#"> link</a>! </p>
 
-  <pre>
+  <my-code>
   &lt;my-skip-link>&lt;/my-skip-link>
-  </pre>
+</my-code>
 
-  <my-lorem-ipsum />
+  <my-lorem-ipsum paras="4"></my-lorem-ipsum>
 
 </my-page>
 

diff --git a/demo/my-speech.html b/demo/my-speech.html
@@ -8,11 +8,14 @@
 <my-page>
   <h2> my-text-to-speech </h2>
 
+  <p> Text to speech (TTS) — Speech Synthesis — using the Web Speech API. </p>
+
+
   <my-text-to-speech lang="en" rate="0.9">
     <div contenteditable="true">
       <!--<p> Hello world!-->
       <!--<p>If a dog chews shoes, whose shoes does he choose?</p>-->
-      <p>Rory the warrior and Roger the worrier were reared wrongly in a rural brewery.</p>
+      <p><q>Rory the warrior and Roger the worrier were reared wrongly in a rural brewery.</q></p>
     </div>
   </my-text-to-speech>
 
@@ -35,8 +38,14 @@ <h2> my-text-to-speech </h2>
     </p>
   </my-text-to-speech>
 
+
   <my-code>
-&lt;my-text-to-speech lang="fr" lang-regex="fr.*" rate="0.9" vox-regex="(Amelie|Google français)">
+&lt;my-text-to-speech
+  lang="fr"
+  lang-regex="fr.*"
+  rate="0.9"
+  vox-regex="(Amelie|Google français)"
+  >
   &lt;p>Bonjour. Je m'appelle Amelie!&lt;/p>
 &lt;/my-text-to-speech>
 </my-code>

diff --git a/demo/my-star-rating.html b/demo/my-star-rating.html
@@ -9,6 +9,8 @@
 
 <h2> My radio star rating </h2>
 
+<p> A keyboard accessible interactive to give a star rating. </p>
+
 <p><a href="#">Before</a></p>
 
 <form>

diff --git a/src/MyElement.js b/src/MyElement.js
@@ -33,7 +33,7 @@ export class MyElement extends HTMLElement {
     customElements.define(klass.getTag(), klass);
   }
 
-  getTemplateUrl (id) {
+  _getTemplateUrl (id) {
     const HOST = getOpt('templateHost');
 
     // URL is relative to the HTML page!
@@ -57,7 +57,7 @@ export class MyElement extends HTMLElement {
     // const template = document.getElementById('my-map-template');
     // const templateContent = template.content;
 
-    const url = this.getTemplateUrl(tag);
+    const url = this._getTemplateUrl(tag);
 
     const resp = await fetch(url);
     const html = await resp.text();

diff --git a/src/components/MyFontElement.js b/src/components/MyFontElement.js
@@ -6,7 +6,6 @@
  * @see https://gist.github.com/nfreear/3ad861197288cec0179716fe49c9567c
  * @see https://developer.mozilla.org/en-US/docs/Web/API/FontFace
  * @see https://fontsource.org/fonts/aclonica
- * @see https://opendyslexic.org/
  */
 
 import { MyElement } from '../MyElement.js';

diff --git a/src/components/MyForkMeElement.js b/src/components/MyForkMeElement.js
@@ -1,10 +1,10 @@
 /**
-  Add a "Fork me on GitHub" ribbon.
-
-  © Nick Freear, 09-Dec-2021.
-
-  @see http://simonwhitaker.github.io/github-fork-ribbon-css/
-*/
+ * Add a "Fork me on GitHub" ribbon.
+ *
+ * @copyright © Nick Freear, 09-Dec-2021.
+ *
+ * @see http://simonwhitaker.github.io/github-fork-ribbon-css/
+ */
 
 import { MyElement } from '../MyElement.js';
 

diff --git a/src/components/MyMapElement.js b/src/components/MyMapElement.js
@@ -1,10 +1,13 @@
-/*!
- Easily embed a map powered by Leaflet.js - optionally with a GeoJSON feed.
-
-  Nick Freear, 27-Nov-2021.
-
+/**
+ * Easily embed a map powered by Leaflet.js - optionally with a GeoJSON feed.
+ *
+ * Contains accessibility fixes.
+ *
+ * @copyright © Nick Freear, 27-Nov-2021.
+ *
+ * @see https://leafletjs.com/
  * @WAS 'my-map.js'
-*/
+ */
 
 import { leafletViaCdn } from '../external-cdn.js';
 import { MyElement } from '../MyElement.js';

diff --git a/src/components/MySkipLinkElement.js b/src/components/MySkipLinkElement.js
@@ -1,7 +1,8 @@
-/*!
-
-  © Nick Freear, 08-Dec-2021.
-*/
+/**
+ * Add a "skip to main content" link which becomes visible on focus.
+ *
+ * @copyright Nick Freear, 08-Dec-2021.
+ */
 
 import { MyElement } from '../MyElement.js';
 

diff --git a/src/components/MyStarRatingElement.js b/src/components/MyStarRatingElement.js
@@ -1,9 +1,10 @@
-/*!
-
-  © Nick Freear, 04-Dec-2021.
-
-  Was: MyRadioStarRatingElement.
-*/
+/**
+ * A keyboard accessible interactive to give a star rating.
+ *
+ * @copyright © Nick Freear, 04-Dec-2021.
+ *
+ * @WAS MyRadioStarRatingElement.
+ */
 
 import { MyElement } from '../MyElement.js';
 
@@ -15,35 +16,35 @@ export class MyStarRatingElement extends MyElement { // HTMLInputElement {
   async connectedCallback () {
     const name = this.getAttribute('name') || 'my-star-rating-1';
 
-    await this.initialize({ name });
+    await this._initialize({ name });
   }
 
-  async initialize (attr) {
+  async _initialize (attr) {
     const templates = await this.getTemplate('my-star-rating');
 
     const labels = this.shadowRoot.querySelectorAll('label');
     const fieldset = this.shadowRoot.querySelector('fieldset');
 
-    const hiddenInput = this.createHiddenInput(attr.name);
+    const hiddenInput = this._createHiddenInput(attr.name);
 
     this.after(hiddenInput);
 
     this.$$ = {
       ...attr, hiddenInput, labels, fieldset, templates
     };
 
-    this.appendStars(labels, templates[1]);
+    this._appendStars(labels, templates[1]);
 
-    fieldset.addEventListener('click', ev => this.clickEventHandler(ev));
+    fieldset.addEventListener('click', ev => this._clickEventHandler(ev));
     fieldset.addEventListener('mouseout', ev => {
-      this.unfocusStars();
+      this._unfocusStars();
       // console.debug('mouseout');
     });
 
     console.debug('my-star-rating (radio):', this.$$, this);
   }
 
-  createHiddenInput (name) {
+  _createHiddenInput (name) {
     const INPUT = document.createElement('input');
     INPUT.id = 'my-star-rating-input-1';
     INPUT.type = 'hidden';
@@ -53,7 +54,7 @@ export class MyStarRatingElement extends MyElement { // HTMLInputElement {
     return INPUT;
   }
 
-  appendStars (labels, starSvgTemplate) {
+  _appendStars (labels, starSvgTemplate) {
     // const starSvgTemplate = templates[ 1 ];
     [...labels].forEach(label => {
       const starSvg = starSvgTemplate.content.cloneNode(true);
@@ -62,35 +63,35 @@ export class MyStarRatingElement extends MyElement { // HTMLInputElement {
     });
   }
 
-  updateValue (value) {
+  _updateValue (value) {
     this.title = `${value} stars`;
     this.setAttribute('data-value', value);
     // this.$$.hiddenInput.setAttribute('data-value', value);
     this.$$.hiddenInput.value = value;
   }
 
-  unfocusStars () {
+  _unfocusStars () {
     [...this.$$.labels].map(label => label.classList.remove('focused'));
   }
 
-  updateState (VALUE) {
+  _updateState (VALUE) {
     [...this.$$.labels].forEach((label, idx) => {
       label.setAttribute('data-star', idx < VALUE ? 'yes' : 'no');
     });
   }
 
-  clickEventHandler (ev) {
+  _clickEventHandler (ev) {
     const LABEL = ev.target.parentElement;
     const VALUE = parseInt(ev.target.value); // Was: ev.target.getAttribute('data-rating'));
 
     if (ev.target.nodeName !== 'INPUT') { // NaN.
-      this.unfocusStars();
+      this._unfocusStars();
       return;
     }
 
-    this.updateValue(VALUE);
-    this.updateState(VALUE);
-    this.unfocusStars();
+    this._updateValue(VALUE);
+    this._updateState(VALUE);
+    this._unfocusStars();
 
     LABEL.classList.add('focused');
-Original file line number
+Diff line change
@@ Expand Up / @@ -9,6 +9,8 @@ @@
     <h2> My radio star rating </h2>
+    <p> A keyboard accessible interactive to give a star rating. </p>
     <p><a href="#">Before</a></p>
     <form>
@@ Expand Down @@