add web components

ui/.storybook/preview.js

@@ -3,7 +3,7 @@ const preview = {
     parameters: {
         options: {
             storySort: {
-                order: ['Web UI Storybook', 'Design System', 'Layout','Forms', 'Components', 'Utilities', 'Pages'],
+                order: ['Web UI Storybook', 'Design System', 'Layout','Forms', 'Components', 'Web Components Or Custom Elements', 'Utilities', 'Pages'],
             },
         },
     },

ui/package.json

@@ -2,7 +2,7 @@
     "name": "web-ui-boilerplate",
     "description": "UI boilerplate for websites/webapps using vanilla HTML/CSS/JavaScript, powered by Storybook, bundled by Parcel.",
     "author": "basher",
-    "version": "2.0.0",
+    "version": "2.1.0",
     "license": "ISC",
     "repository": {
         "type": "git",

ui/src/javascript/modules/disclosure.ts

@@ -5,6 +5,8 @@ export default class Disclosure {
     private disclosure: Element;
     private btnDisclosure: HTMLButtonElement | null;
     private content: HTMLElement | null;
+    private bindEscapeKey?: boolean;
+    private bindClickOutside?: boolean;
 
     constructor(disclosure: Element) {
         this.disclosure = disclosure;
@@ -14,6 +16,12 @@ export default class Disclosure {
         this.content = this.disclosure.querySelector(
             '[data-disclosure-content]',
         );
+        this.bindEscapeKey = this.disclosure.hasAttribute(
+            'data-disclosure-escape-key',
+        );
+        this.bindClickOutside = this.disclosure.hasAttribute(
+            'data-disclosure-click-outside',
+        );
 
         this.init();
     }
@@ -35,20 +43,18 @@ export default class Disclosure {
     }
 
     private initdisclosure(): void {
+        const button = this.btnDisclosure;
+        const content = this.content;
+        const bindEscapeKey = this.bindEscapeKey;
+        const bindClickOutside = this.bindClickOutside;
+
         // Show/hide content.
-        const button = this.btnDisclosure as HTMLElement;
-        const content = this.content as HTMLElement;
-        const bindEscapeKey = this.disclosure.hasAttribute(
-            'data-disclosure-escape-key',
-        );
-        const bindClickOutside = this.disclosure.hasAttribute(
-            'data-disclosure-click-outside',
-        );
-        disclosure({
-            button,
-            content,
-            bindEscapeKey,
-            bindClickOutside,
-        });
+        button &&
+            disclosure({
+                button,
+                content,
+                bindEscapeKey,
+                bindClickOutside,
+            });
     }
 }

ui/src/javascript/ui-init.ts

@@ -13,6 +13,8 @@ import Tabs from './modules/tabs';
 import Toggle from './modules/toggle';
 import VideoPlayer from './modules/video-player';
 
+import WebDisclosure from './web-components/web-disclosure';
+
 // For DEMO purposes only.
 import demoAjaxFetchHTML from './modules/demo-ajax-fetch-html';
 
@@ -33,4 +35,8 @@ export const uiInit = (): void => {
 
     // For DEMO purposes only.
     demoAjaxFetchHTML.start();
+
+    // Define Web Components
+    !customElements.get('web-disclosure') &&
+        customElements.define('web-disclosure', WebDisclosure);
 };

ui/src/javascript/utils/disclosure.ts

@@ -14,7 +14,7 @@ import { randomString } from './random-string';
  *      disclosure({ button, content });
  */
 interface Disclosure {
-    button: HTMLElement;
+    button: HTMLButtonElement;
     content: HTMLElement | null;
     bindEscapeKey?: boolean;
     bindClickOutside?: boolean;

ui/src/javascript/web-components/web-disclosure.ts

@@ -0,0 +1,37 @@
+import { disclosure } from '../utils/disclosure';
+
+export default class WebDisclosure extends HTMLElement {
+    private trigger: HTMLButtonElement | null;
+    private content: HTMLElement | null;
+    private bindEscapeKey?: boolean;
+    private bindClickOutside?: boolean;
+
+    constructor() {
+        super();
+
+        this.trigger = this.querySelector('[trigger]');
+        this.content = this.querySelector('[content]');
+        this.bindEscapeKey = this.hasAttribute('bind-escape-key');
+        this.bindClickOutside = this.hasAttribute('bind-click-outside');
+
+        this.init();
+
+        // NOTE: There are NO event listeners here. All events are handled by the external 'discloure()' dependency.
+    }
+
+    private init(): void {
+        if (!this.trigger || !this.content) return;
+
+        const button = this.trigger;
+        const content = this.content;
+        const bindEscapeKey = this.bindEscapeKey;
+        const bindClickOutside = this.bindClickOutside;
+
+        disclosure({
+            button,
+            content,
+            bindEscapeKey,
+            bindClickOutside,
+        });
+    }
+}

ui/src/stylesheets/index.scss

@@ -45,6 +45,7 @@ CSS Cascade Layers.
     @layer components {
         @include meta.load-css('form');
         @include meta.load-css('components');
+        @include meta.load-css('web-components');
     }
 
     /*

ui/src/stylesheets/web-components/_index.scss

@@ -0,0 +1 @@
+@use 'web-disclosure';

ui/src/stylesheets/web-components/_web-disclosure.scss

@@ -0,0 +1,11 @@
+/*
+----------------------------------------------------------------------------
+Dependencies.
+----------------------------------------------------------------------------
+*/
+// @use '../base' as *;
+// @use '../mixins' as *;
+
+web-disclosure {
+    //
+}

ui/stories/3. Layout/UsefulTips.mdx

@@ -1,6 +1,6 @@
 import { Meta } from '@storybook/blocks';
 
-<Meta title="Layout/Useful layout tips" />
+<Meta title="Layout/Useful Layout Tips" />
 
 # Useful layout tips
 

ui/stories/5. Components/Disclosure/Disclosure.mdx

@@ -12,5 +12,8 @@ import * as Disclosure from './Disclosure.stories';
 - By adding the `data-disclosure-escape-key` attribute to the HTML, the `ESC` key can be used to hide the content.
 - Similarly, the `data-disclosure-click-outside` attribute hides the content when clicking anywhere outside the content.
 
+## Web component version
+- See the [web-disclosure](/story/web-components-web-disclosure--web-disclosure) component.
+
 <Canvas of={Disclosure.Disclosure} />
 <Controls of={Disclosure.Disclosure} />

ui/stories/5. Components/Disclosure/Disclosure.stories.js

@@ -1,7 +1,7 @@
 import { DisclosureHtml } from './Disclosure';
 
 export default {
-    title: 'Components/Disclosure',
+    title: 'Components/Disclosure (Or Show|Hide)',
     parameters: {
         status: {
             type: 'stable',
@@ -22,4 +22,3 @@ export default {
 export const Disclosure = {
     render: (args) => DisclosureHtml(args),
 };
-Disclosure.storyName = 'Disclosure (i.e. Show/Hide)';

ui/stories/6. Web Components Or Custom Elements/WebComponents.mdx

@@ -0,0 +1,13 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Web Components Or Custom Elements/Using Web Components" />
+
+# HTML Web Components
+- The Web Components in this boilerplate are simply `custom elements` that wrap normal HTML markup, therefore providing a progressive enhancement layer via JavaScript.
+- They are **not** empty shells that only work with JavaScript.
+- They also don't make use of the [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM).
+
+## Additional reading
+- Great explanation by Jeremy Keith (and others) about the power of [HTML Web Components](https://adactio.com/journal/20618).
+- Simple example from Chris Ferdinandi showing how to [create a Web Component from scratch](https://gomakethings.com/lets-create-a-web-component-from-scratch/). He also has lots more articles on this topic in his blog.
+- Some notes on the recommended use of [connectedCallback() lifecycle method and event listeners](https://hawkticehurst.com/writing/you-are-probably-using-connectedcallback-wrong/).

ui/stories/6. Web Components Or Custom Elements/WebDisclosure/WebDisclosure.js

@@ -0,0 +1,21 @@
+export const WebDisclosureHtml = (args) => `
+<web-disclosure
+    class="disclosure"
+    ${args.bindEscapeKey === true ? 'bind-escape-key' : ''}
+    ${args.bindClickOutside === true ? 'bind-click-outside' : ''}
+>
+    <button
+        type="button"
+        class="button button--text"
+        trigger
+        hidden
+    >
+        <span>Show / Hide</span>
+    </button>
+
+    <div content>
+        <p>Content to be shown/hidden.</p>
+        <p>Use this component when <code>accordion</code> or <code>tabs</code> components cannot be used.</p>
+    </div>
+</web-disclosure>
+`;

ui/stories/6. Web Components Or Custom Elements/WebDisclosure/WebDisclosure.mdx

@@ -0,0 +1,12 @@
+import { Meta, Canvas, Controls } from '@storybook/blocks';
+import * as WebDisclosure from './WebDisclosure.stories';
+
+<Meta of={WebDisclosure} />
+
+# `<web-disclosure>`
+- This is functionally equivalent to the [disclosure](/story/components-disclosure--disclosure) component, with the same accessibility considerations.
+- The attributes that bind clicking the `ESC` key and clicking outside are renamed to `bind-escape-key` and `bind-click-outside`.
+- To maintain the [DRY code](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) approach in this boilerplate, the JavaScript logic to handle showing/hiding of content is imported from an external shared utility function in `javascript/utils/disclosure.ts`.
+
+<Canvas of={WebDisclosure.WebDisclosure} />
+<Controls of={WebDisclosure.WebDisclosure} />

ui/stories/6. Web Components Or Custom Elements/WebDisclosure/WebDisclosure.stories.js

@@ -0,0 +1,25 @@
+import { WebDisclosureHtml } from './WebDisclosure';
+
+export default {
+    title: 'Web Components Or Custom Elements/<web-disclosure>',
+    parameters: {
+        status: {
+            type: 'stable',
+        },
+    },
+    argTypes: {
+        bindEscapeKey: {
+            control: 'boolean',
+            description: 'Close with ESC key.'
+        },
+        bindClickOutside: {
+            control: 'boolean',
+            description: 'Close by clicking outside'
+        },
+    },
+};
+
+export const WebDisclosure = {
+    render: (args) => WebDisclosureHtml(args),
+};
+WebDisclosure.storyName = '<web-disclosure>';

ui/stories/6. Utilities/Utilities.stories.js → ui/stories/7. Utilities/Utilities.stories.js

@@ -1,7 +1,7 @@
 import { MarginPaddingHtml } from './Utilities';
 
 export default {
-    title: 'Utilities/Helpers and utilities',
+    title: 'Utilities/Helpers and Utilities',
     parameters: {
         status: {
             type: 'stable',

ui/stories/6. Utilities/UtilitiesNoArgs.stories.js → ui/stories/7. Utilities/UtilitiesNoArgs.stories.js

@@ -5,7 +5,7 @@ import {
 } from './Utilities';
 
 export default {
-    title: 'Utilities/Helpers and utilities',
+    title: 'Utilities/Helpers and Utilities',
     parameters: {
         status: {
             type: 'stable',