Subscribe component: Better destroy(), add init() (#1882)

Author: gerardo-rodriguez

.changeset/gold-shirts-yell.md

@@ -0,0 +1,19 @@
+---
+'@cloudfour/patterns': major
+---
+
+Enhances the Subscribe component's ability to programmatically control its UI via 
+`destroy()`/`init()` methods
+
+- `initSubscribe()` was renamed to `createSubscribe()`
+- `init()` must now be explicitly called to initialize
+- `destroy()` hides CTA buttons UI, shows digests sign up form
+
+```js
+// Initialize
+const subscribe = createSubscribe(document.querySelector('.js-subscribe'));
+subscribe.init();
+
+// Remove all event listeners, show subscription form
+subscribe.destroy();
+```

package.json

@@ -148,6 +148,7 @@
     "release": "npm run build && changeset publish"
   },
   "jest": {
+    "testTimeout": 15000,
     "setupFilesAfterEnv": [
       "./jest.setup.js"
     ],

src/components/subscribe/demo/demo.twig

@@ -1,3 +1,5 @@
+{# This demo is used by tests, do not delete #}
+
 {% embed '@cloudfour/components/subscribe/subscribe.twig' with {
   form_id: 'test',
   weekly_digests_heading: 'Get Weekly Digests',

src/components/subscribe/demo/destroy-init.twig

@@ -0,0 +1,16 @@
+{# This demo is used by tests, do not delete #}
+
+{% embed '@cloudfour/objects/rhythm/rhythm.twig' only %}
+  {% block content %}
+    {% include '@cloudfour/components/subscribe/subscribe.twig' with {
+      form_id: 'test',
+      weekly_digests_heading: 'Get Weekly Digests',
+      subscribe_heading: 'Never miss an article!',
+    } only %}
+
+    <div>
+      <a href="#">Testing link</a>
+    </div>
+  {% endblock %}
+{% endembed %}
+

src/components/subscribe/demo/storybook-demo.twig

@@ -0,0 +1,11 @@
+{# This demo is used by storybook, do not delete #}
+
+{% embed '@cloudfour/objects/rhythm/rhythm.twig' %}
+  {% block content %}
+    <button class="js-destroy-button">Destroy Subscribe component</button>
+    <button class="js-init-button">Initialize Subscribe component</button>
+
+    {% include '@cloudfour/components/subscribe/subscribe.twig' %}
+  {% endblock %}
+{% endembed %}
+

src/components/subscribe/subscribe.scss

@@ -34,6 +34,8 @@
 
 ///
 /// 1. Ensures the form background color matches the current theme
+/// 2. In the "destroyed" state, the CTA buttons are hidden so we
+///    don't need the form to be absolutely positioned.
 ///
 
 .c-subscribe__form {
@@ -43,7 +45,10 @@
   inline-size: 100%;
   inset-block-start: 0;
   inset-inline-start: 0;
-  position: absolute;
+
+  .c-subscribe__controls-ui:not([hidden]) ~ & {
+    position: absolute; // 2
+  }
 
   ///
   /// 1. Allows for the visually hidden form to be keyboard accessible, will be

src/components/subscribe/subscribe.stories.mdx

@@ -1,16 +1,27 @@
 import { ArgsTable, Canvas, Meta, Story } from '@storybook/addon-docs';
 import { useEffect } from '@storybook/client-api';
 import { makeTwigInclude } from '../../make-twig-include.js';
-import template from './subscribe.twig';
-import { initSubscribe } from './subscribe.ts';
+import template from './demo/storybook-demo.twig';
+import { createSubscribe } from './subscribe.ts';
 // Helper function to initialize toggling button JS
 const templateStory = (args) => {
   useEffect(() => {
-    const templateEls = [...document.querySelectorAll('.js-subscribe')].map(
-      (templateEl) => initSubscribe(templateEl)
+    // Initialize the component
+    const subscribeComponent = createSubscribe(
+      document.querySelector('.js-subscribe')
     );
+    subscribeComponent.init();
+    // Set up the demo destroy button
+    const destroyBtn = document.querySelector('.js-destroy-button');
+    destroyBtn.addEventListener('click', subscribeComponent.destroy);
+    // Set up the demo init button
+    const initBtn = document.querySelector('.js-init-button');
+    initBtn.addEventListener('click', subscribeComponent.init);
     return () => {
-      for (const templateEl of templateEls) templateEl.destroy();
+      // Make sure to cleanup
+      destroyBtn.removeEventListener('click', subscribeComponent.destroy);
+      initBtn.removeEventListener('click', subscribeComponent.init);
+      subscribeComponent.destroy();
     };
   });
   return template(args);
@@ -172,6 +183,14 @@ The Subscribe component provides the UI to subscribe to notifications and/or ema
 
 This component embeds the [Button Swap component](/?path=/docs/components-button-swap--default-story) for the "Get Notifications" button.
 
+## Destroy/Initialize
+
+The Subscribe component allows you to programmatically disable/enable the JavaScript functionality via its `destroy()` and `init()` methods. When "destroyed," the following will occur:
+
+- The "Get notifications"/"Get Weekly Digests" UI will be removed
+- The weekly digests form will be shown
+- All Subscribe component JavaScript will be removed
+
 <Canvas>
   <Story
     name="Default"
@@ -213,7 +232,7 @@ The Subscribe component UX can be progressively enhanced using JavaScript. Enhan
 ### Syntax
 
 ```js
-initSubscribe(subscribeEl);
+const subscribe = createSubscribe(subscribeEl);
 ```
 
 ### Parameters
@@ -224,42 +243,55 @@ The Subscribe component `.js-subscribe` root element.
 
 ### Return value
 
-An object with a `destroy` function that removes all event listeners added by this component.
+An object with two functions to programmatically control the Subscribe component's
+state:
 
 ```js
 {
+  init: () => void
   destroy: () => void
 }
 ```
 
+| Method                | Description                                                                                                                                         |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subscribe.init()`    | Initializes the Subscribe component to its default UI state, including all JavaScript functionality.                                                |
+| `subscribe.destroy()` | Removes the "Get notifications"/"Get Weekly Digests" CTA UI leaving only the weekly digests sign up form. All JavaScript functionality is disabled. |
+
 ### Examples
 
 #### Single Subscribe component on the page
 
 ```js
 // Initialize
-const subscribeEl = initSubscribe(document.querySelector('.js-subscribe'));
+const subscribe = createSubscribe(document.querySelector('.js-subscribe'));
+subscribe.init();
 
-// Remove all event listeners
-subscribeEl.destroy();
+// Remove all event listeners, show subscription form
+subscribe.destroy();
 ```
 
 #### Multiple Subscribe components on the page
 
 ```js
 // Initialize
-const subscribeEls = [...document.querySelectorAll('.js-subscribe')].map(
-  (subscribeEl) => initSubscribe(subscribeEl)
+const subscribeComponents = [...document.querySelectorAll('.js-subscribe')].map(
+  (subscribeEl) => {
+    const subscribe = createSubscribe(subscribeEl);
+    subscribe.init();
+    return subscribe;
+  }
 );
 
-// Remove all event listeners
-for (const subscribeEl of subscribeEls) {
-  subscribeEl.destroy();
+// Remove all event listeners, show subscription form
+for (const subscribe of subscribeComponents) {
+  subscribe.destroy();
 }
 ```
 
 ### Note
 
 You will need to initialize the "Get Notifications" button as well, see the
 [Button Swap component](/?path=/docs/components-button-swap--default-story#javascript)
-for initialization docs.
+for initialization docs. Alternatively, you can write custom JavaScript to swap
+the "Get Notifications" buttons if you prefer.

src/components/subscribe/subscribe.test.ts

@@ -13,6 +13,9 @@ const componentMarkup = (args = {}) =>
   });
 // Helper to load the demo Twig template file
 const demoMarkup = loadTwigTemplate(path.join(__dirname, './demo/demo.twig'));
+const demoDestroyInitMarkup = loadTwigTemplate(
+  path.join(__dirname, './demo/destroy-init.twig')
+);
 
 /**
  * Helper function that checks the `clientHeight` and `clientWidth` of
@@ -50,13 +53,14 @@ const expectElementNotToBeVisuallyHidden = async (
 // Helper to initialize the component JS
 const initJS = (utils: PleasantestUtils) =>
   utils.runJS(`
-    import { initSubscribe } from './subscribe'
-    export default () => initSubscribe(
+    import { createSubscribe } from './subscribe';
+    const subscribe = createSubscribe(
       document.querySelector('.js-subscribe')
-    )
+    );
+    subscribe.init();
   `);
 
-describe('Subscription', () => {
+describe('Subscription component', () => {
   test(
     'should use semantic markup',
     withBrowser(async ({ utils, page }) => {
@@ -266,4 +270,100 @@ describe('Subscription', () => {
       });
     })
   );
+
+  test(
+    'should destroy and initialize',
+    withBrowser(async ({ utils, screen, waitFor, page }) => {
+      await loadGlobalCSS(utils);
+      await utils.loadCSS('./subscribe.scss');
+      await utils.injectHTML(await demoDestroyInitMarkup());
+      await utils.runJS(`
+        import { createSubscribe } from './subscribe';
+        // We attach it to the window object as a workaround to have access to
+        // the subscribeComponent later in this test.
+        window.subscribeComponent = createSubscribe(
+          document.querySelector('.js-subscribe')
+        );
+        // Set it to the "destroyed" state
+        window.subscribeComponent.destroy();
+      `);
+
+      // The form should be active/visible when `destroy()` is called
+      const form = await screen.getByRole('form', {
+        name: 'Get Weekly Digests',
+      });
+      await expectElementNotToBeVisuallyHidden(form);
+
+      // Tab all the way to the "testing" link
+      await page.keyboard.press('Tab'); // Email input
+      await page.keyboard.press('Tab'); // Subscribe button
+      await page.keyboard.press('Tab'); // "Testing" link
+
+      // The "testing" link should be in focus
+      const testingLink = await screen.getByRole('link', {
+        name: 'Testing link',
+      });
+      await expect(testingLink).toHaveFocus();
+
+      // After a timeout, the form should not visually hide
+      await new Promise((resolve) => {
+        setTimeout(resolve, 2000);
+      });
+      await expectElementNotToBeVisuallyHidden(form);
+
+      // Initialize the Subscribe component
+      await utils.runJS(`
+        window.subscribeComponent.init();
+      `);
+
+      // The form should be visually hidden after `init()` is called
+      await expectElementToBeVisuallyHidden(form);
+
+      // Navigate back into the form
+      await page.keyboard.down('Shift'); // Navigate backwards
+      await page.keyboard.press('Tab'); // Form Subscribe submit button
+      await page.keyboard.up('Shift'); // Release Shift key
+
+      // The form should be visible when you move the focus back into the form
+      await expectElementNotToBeVisuallyHidden(form);
+
+      // Navigate away from the form
+      await page.keyboard.press('Tab'); // "Testing" link
+
+      // Immediately, the form should stay visible
+      await expectElementNotToBeVisuallyHidden(form);
+
+      // After a timeout, the form eventually visually hides
+      await waitFor(
+        async () => {
+          await expectElementToBeVisuallyHidden(form);
+        },
+        {
+          timeout: 2000,
+          interval: 1000,
+        }
+      );
+
+      // Cover a race condition where the timeout and destroy get called quickly
+      // one after the other causing an unexpected UI state when the Subscribe
+      // component timeout isn't cleared.
+      // Set the focus in the form first (on the submit button)
+      const formSubmitBtn = await screen.getByRole('button', {
+        name: 'Subscribe',
+      });
+      formSubmitBtn.focus();
+      // Then blur the focus
+      await formSubmitBtn.evaluate((btn) => btn.blur());
+      // And immediately run the `destroy()`
+      await utils.runJS(`
+        window.subscribeComponent.destroy();
+      `);
+      // Wait out the Subscribe component timeout
+      await new Promise((resolve) => {
+        setTimeout(resolve, 2000);
+      });
+      // The form should be visible
+      await expectElementNotToBeVisuallyHidden(form);
+    })
+  );
 });