@progressiveui/react 1.22.0

package/src/globals/js/mixins/README.md

@@ -0,0 +1,207 @@
+# Carbon component mixins
+
+Carbon component mixins, based on [Subclass Factory Pattern](https://github.com/justinfagnani/proposal-mixins#subclass-factory-pattern), provides the basis for Carbon component classes by allowing component implementation to compose small pieces of functionalities to base them on, instead of introducing "fat base class".
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+* [Component lifecycle (`create-component.js`)](#component-lifecycle-create-componentjs)
+  * [Creation](#creation)
+  * [Clean-up](#clean-up)
+  * [Component registry](#component-registry)
+* [Sugar layers for component instantiation](#sugar-layers-for-component-instantiation)
+  * [Searching for DOM nodes to intantiate components on (`init-component-by-search.js`)](#searching-for-dom-nodes-to-intantiate-components-on-init-component-by-searchjs)
+  * [Lazily instantiating a component upon an event on a root element (`init-component-by-event.js`)](#lazily-instantiating-a-component-upon-an-event-on-a-root-element-init-component-by-eventjs)
+  * [Lazily instantiating a component upon an event on a launcher button (`init-component-by-launcher.js`)](#lazily-instantiating-a-component-upon-an-event-on-a-launcher-button-init-component-by-launcherjs)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Component lifecycle ([`create-component.js`](./create-component.js))
+
+[`create-component.js`](./create-component.js) mixin covers component lifecycle, which is, [creation](#creation) and [clean-up](#clean-up).
+
+### Creation
+
+[Static `.create(element)` method](https://github.com/carbon-design-system/carbon-components/blob/0336425/src/globals/js/mixins/create-component.js#L44-L46) covers the creation part. It first checks if there is an instance of the same component class with by looking up static `components` property for one associated with the given `element`, and simply returns it if there is one. Otherwise, a new instance of the component is created by calling the constructor with the given `element` and returns the new instance.
+
+A Carbon component works with the given `element` and its descendants to hook event handlers on, change DOM properties of, mangle styles of, and so on. We call it the _root element_ of the component.
+
+```javascript
+import mixin from 'carbon-components/src/globals/js/misc/mixin.js';
+import createComponent from 'carbon-components/src/globals/js/mixins/create-component.js';
+
+class MyClass extends mixin(createComponent) {
+  …
+
+  // Every component must define static `components` property
+  static components = new WeakMap();
+
+  // Every component must define static `options` property
+  static options = { foo: 'foo0', bar: 'bar0' };
+}
+
+const div = document.body.appendChild(document.createElement('div'));
+const options = { foo: 'foo1', baz: 'baz1' };
+const myClassInstance = MyClass.create(div, options);
+```
+
+The constructor in `create-component.js` mixin sets the following properties:
+
+| Name       | Description                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `element`  | The root element of the component (see above).                                                                                                                                                                                                                                                                                                                                                     |
+| `options`  | The component options.                                                                                                                                                                                                                                                                                                                                                                             |
+| `children` | The array of Carbon component instances that has to be released along with this component. An exanple is with [overflow menu](http://www.carbondesignsystem.com/components/overflow-menu/code) component which creates another Carbon component called [floating menu](../../../components/floating-menu/floating-menu.js), and the floating menu has to be released along with the overflow menu. |
+
+The `.options` property inherits static `.options` property and merges in the 2nd argument of static `.create()` method. In above example, `.options` will be equal to `{ foo: 'foo1', bar: 'bar0', baz: 'baz1' }`.
+
+### Clean-up
+
+[`.release()`](https://github.com/carbon-design-system/carbon-components/blob/0336425/src/globals/js/mixins/create-component.js#L51-L57) method covers the clean-up part. It takes care of cleaning-up Carbon components in `.children` property as well as one in static `.components` property.
+
+If a Carbon component has other things to clean-up (e.g. event listeners), it can override the `.release()` method and write code there to clean things up.
+
+`.release()` method should return `null` to allow the caller of `.release()` e.g. to assign the return value to a variable referring to Carbon component instance, marking that the instance is gone.
+
+### Component registry
+
+Every component must define static `components` property, which is an instance of [`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap). The constructor in `create-component.js` [sets the component instance to static `.components` property](https://github.com/carbon-design-system/carbon-components/blob/0336425/src/globals/js/mixins/create-component.js#L37), mapped with the DOM element the component is instantiated on. This allows application code to grab a Carbon component instance associated with the root element.
+
+## Sugar layers for component instantiation
+
+Carbon defines three types of mixins to allow applications to instantiate components in batch. A component can inherit one of those three mixins to support batch instantiation.
+
+### Searching for DOM nodes to intantiate components on ([`init-component-by-search.js`](./init-component-by-search.js))
+
+The most basic one is [`init-component-by-search.js`](./init-component-by-search.js), which searches for DOM elements matching component option's `.selectorInit` property.
+
+For example, given the following HTML:
+
+```html
+<main>
+  <div data-my-component>The content of component 0</div>
+  <div data-my-component>The content of component 1</div>
+</main>
+```
+
+The call of static `.init()` method below instantiates components on the two `<div>`s above:
+
+```javascript
+import mixin from 'carbon-components/src/globals/js/misc/mixin.js';
+import createComponent from 'carbon-components/src/globals/js/mixins/create-component.js';
+import initComponentBySearch from 'carbon-components/src/globals/js/mixins/init-component-by-search.js';
+
+class MyClass extends mixin(createComponent, initComponentBySearch) {
+  …
+
+  static components = new WeakMap();
+  static options = {
+    selectorInit: '[data-my-component]',
+  };
+}
+
+const main = document.querySelector('main');
+
+// Instantiates components on two `<div>`s above
+MyClass.init(main);
+```
+
+### Lazily instantiating a component upon an event on a root element ([`init-component-by-event.js`](./init-component-by-event.js))
+
+[`init-component-by-event.js`](./init-component-by-event.js) mixin allows delaying component instantiation until an event happens on a DOM element that will be the root element. For example, the static `.init()` method of Carbon [`Tooltip` component](http://www.carbondesignsystem.com/components/tooltip/code) delays instantiating the components until user hovers the mouse over a trigger button or user puts the keyboard focus on a trigger buton.
+
+Given the same example HTML as the one for `init-component-by-search.js` above, the call of static `.init()` method below detects `click` events on DOM elements with `data-my-component` attribute, and instantiates the component when such event happens:
+
+```javascript
+import mixin from 'carbon-components/src/globals/js/misc/mixin.js';
+import createComponent from 'carbon-components/src/globals/js/mixins/create-component.js';
+import initComponentByEvent from 'carbon-components/src/globals/js/mixins/init-component-by-event.js';
+
+class MyClass extends mixin(createComponent, initComponentByEvent) {
+  constructor(element) {
+    super(element);
+    // Side note: Make sure calling `.removeEventListener()` in the `.release()` method
+    element.addEventListener('click', this._handleClick);
+  }
+
+  // Called when this component is instantiated upon an event
+  createdByEvent(evt) {
+    this._handleClick(evt);
+  }
+
+  …
+
+  _handleClick = evt => {
+    alert('clicked!');
+  };
+
+  …
+
+  static components = new WeakMap();
+  static options = {
+    selectorInit: '[data-my-component]',
+    // Clicking on a DOM element with `data-my-component` attribute will instantiate this component
+    initEventNames: ['click'],
+  };
+}
+
+const main = document.querySelector('main');
+MyClass.init(main);
+```
+
+Changing `initEventNames` option above allows you to hook more/different event types to instantiate components upon.
+
+`.createdByEvent()` method allows you to run an event handler of the event that caused instantiating the component.
+
+### Lazily instantiating a component upon an event on a launcher button ([`init-component-by-launcher.js`](./init-component-by-launcher.js))
+
+[`init-component-by-launcher.js`](./init-component-by-launcher.js) mix-in allows delaying component instantiation until an event happens on an element that has semantic association to the compoennt. For example, the static `.init()` method of Carbon [`Modal` component](http://www.carbondesignsystem.com/components/modal/code) delays instantiating the components until user clicks on a launcher button.
+
+```html
+<main>
+  <button class="wfp--btn wfp--btn--secondary" type="button"
+    data-my-component-target="#id-of-my-component">
+    Launch
+  </button>
+  <div data-my-component id="id-of-my-component">The content of my component</div>
+</main>
+```
+
+Given the example HTML above, the call of static `.init()` method below detects `click` events on DOM elements with `data-my-component-target` attribute, and when one happens, looks for the DOM element the element's `data-my-component-target` attribute points to as a selector, and instantiates a component on the DOM element if found.
+
+```javascript
+import mixin from 'carbon-components/src/globals/js/misc/mixin.js';
+import createComponent from 'carbon-components/src/globals/js/mixins/create-component.js';
+import initComponentByLauncher from 'carbon-components/src/globals/js/mixins/init-component-by-launcher.js';
+
+class MyClass extends mixin(createComponent, initComponentByLauncher) {
+  …
+
+  // Called when user clicks on the launcher button
+  createdByLauncher(evt) {
+    alert('launched!');
+  }
+
+  …
+
+  static components = new WeakMap();
+  static options = {
+    selectorInit: '[data-my-component]',
+    // Clicking on DOM elements with `data-my-component-target` attribute
+    // will look for a DOM element `data-my-component-target` points to,
+    // and will instantiate this component on the DOM element found
+    attribInitTarget: 'data-my-component-target',
+    initEventNames: ['click'],
+  };
+}
+
+const main = document.querySelector('main');
+MyClass.init(main);
+```
+
+Changing `attribInitTarget` option above allows you to change the attribute name to associate a trigger button with a component's root element.
+
+Changing `initEventNames` option above allows you to hook more/different event types to instantiate components upon.
+
+`.createdByLauncher()` method allows you to run an event handler of the event that caused instantiating the component.

package/src/globals/js/mixins/create-component.js

@@ -0,0 +1,69 @@
+export default function(ToMix) {
+  class CreateComponent extends ToMix {
+    /**
+     * The component instances managed by this component.
+     * Releasing this component also releases the components in `this.children`.
+     * @type {Component[]}
+     */
+    children = [];
+
+    /**
+     * Mix-in class to manage lifecycle of component.
+     * The constructor sets up this component's effective options,
+     * and registers this component't instance associated to an element.
+     * @implements Handle
+     * @param {HTMLElement} element The element working as this component.
+     * @param {Object} [options] The component options.
+     */
+    constructor(element, options = {}) {
+      super(element, options);
+
+      if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+        throw new TypeError(
+          'DOM element should be given to initialize this widget.'
+        );
+      }
+
+      /**
+       * The element the component is of.
+       * @type {Element}
+       */
+      this.element = element;
+
+      /**
+       * The component options.
+       * @type {Object}
+       */
+      this.options = Object.assign(
+        Object.create(this.constructor.options),
+        options
+      );
+
+      this.constructor.components.set(this.element, this);
+    }
+
+    /**
+     * Instantiates this component of the given element.
+     * @param {HTMLElement} element The element.
+     */
+    static create(element, options) {
+      return this.components.get(element) || new this(element, options);
+    }
+
+    /**
+     * Releases this component's instance from the associated element.
+     */
+    release() {
+      for (
+        let child = this.children.pop();
+        child;
+        child = this.children.pop()
+      ) {
+        child.release();
+      }
+      this.constructor.components.delete(this.element);
+      return null;
+    }
+  }
+  return CreateComponent;
+}

package/src/globals/js/mixins/evented-show-hide-state.js

@@ -0,0 +1,40 @@
+import eventedState from './evented-state';
+import getLaunchingDetails from '../misc/get-launching-details';
+
+function eventedShowHideState(ToMix) {
+  /**
+   * Mix-in class to launch a floating menu.
+   * @class EventedShowHideState
+   */
+  class EventedShowHideState extends ToMix {
+    /**
+     */
+    /**
+     * Switch to 'shown' state.
+     * @param [evtOrElem] The launching event or element.
+     * @param {EventedState~changeStateCallback} [callback] The callback.
+     */
+    show(evtOrElem, callback) {
+      if (!evtOrElem || typeof evtOrElem === 'function') {
+        callback = evtOrElem; // eslint-disable-line no-param-reassign
+      }
+      this.changeState('shown', getLaunchingDetails(evtOrElem), callback);
+    }
+
+    /**
+     * Switch to 'hidden' state.
+     * @param [evtOrElem] The launching event or element.
+     * @param {EventedState~changeStateCallback} [callback] The callback.
+     */
+    hide(evtOrElem, callback) {
+      if (!evtOrElem || typeof evtOrElem === 'function') {
+        callback = evtOrElem; // eslint-disable-line no-param-reassign
+      }
+      this.changeState('hidden', getLaunchingDetails(evtOrElem), callback);
+    }
+  }
+  return EventedShowHideState;
+}
+
+const exports = [eventedState, eventedShowHideState];
+export default exports;

package/src/globals/js/mixins/evented-state.js

@@ -0,0 +1,124 @@
+export default function(ToMix) {
+  /**
+   * Mix-in class to manage events associated with states.
+   * @class EventedState
+   */
+  class EventedState extends ToMix {
+    // eslint-disable-next-line jsdoc/check-param-names
+    /**
+     * The internal implementation for {@link EventedState#changeState `.changeState()`}, performing actual change in state.
+     * @param {string} [state] The new state. Can be an omitted, which means toggling.
+     * @param {Object} [detail]
+     *   The object that should be put to event details that is fired before/after changing state.
+     *   Can have a `group` property, which specifies what state to be changed.
+     * @param {EventedState~changeStateCallback} callback The callback called once changing state is finished or is canceled.
+     * @private
+     */
+    _changeState() {
+      throw new Error(
+        '_changeState() should be overriden to perform actual change in state.'
+      );
+    }
+
+    // eslint-disable-next-line jsdoc/check-param-names
+    /**
+     * Changes the state of this component.
+     * @param {string} [state] The new state. Can be an omitted, which means toggling.
+     * @param {Object} [detail]
+     *   The object that should be put to event details that is fired before/after changing state.
+     *   Can have a `group` property, which specifies what state to be changed.
+     * @param {EventedState~changeStateCallback} [callback] The callback called once changing state is finished or is canceled.
+     */
+    changeState(...args) {
+      const state = typeof args[0] === 'string' ? args.shift() : undefined;
+      const detail =
+        Object(args[0]) === args[0] && typeof args[0] !== 'function'
+          ? args.shift()
+          : undefined;
+      const callback = typeof args[0] === 'function' ? args.shift() : undefined;
+
+      if (
+        typeof this.shouldStateBeChanged === 'function' &&
+        !this.shouldStateBeChanged(state, detail)
+      ) {
+        if (callback) {
+          callback(null, true);
+        }
+        return;
+      }
+
+      const data = {
+        group: detail && detail.group,
+        state,
+      };
+
+      const eventNameSuffix = [data.group, state]
+        .filter(Boolean)
+        .join('-')
+        .split('-') // Group or state may contain hyphen
+        .map(item => item[0].toUpperCase() + item.substr(1))
+        .join('');
+
+      const eventStart = new CustomEvent(
+        this.options[`eventBefore${eventNameSuffix}`],
+        {
+          bubbles: true,
+          cancelable: true,
+          detail,
+        }
+      );
+
+      const fireOnNode = (detail && detail.delegatorNode) || this.element;
+      const canceled = !fireOnNode.dispatchEvent(eventStart);
+
+      if (canceled) {
+        if (callback) {
+          const error = new Error(
+            `Changing state (${JSON.stringify(data)}) has been canceled.`
+          );
+          error.canceled = true;
+          callback(error);
+        }
+      } else {
+        const changeStateArgs = [state, detail].filter(Boolean);
+        this._changeState(...changeStateArgs, () => {
+          fireOnNode.dispatchEvent(
+            new CustomEvent(this.options[`eventAfter${eventNameSuffix}`], {
+              bubbles: true,
+              cancelable: true,
+              detail,
+            })
+          );
+          if (callback) {
+            callback();
+          }
+        });
+      }
+    }
+
+    /**
+     * Tests if change in state should happen or not.
+     * Classes inheriting {@link EventedState `EventedState`} should override this function.
+     * @function EventedState#shouldStateBeChanged
+     * @param {string} [state] The new state. Can be an omitted, which means toggling.
+     * @param {Object} [detail]
+     *   The object that should be put to event details that is fired before/after changing state.
+     *   Can have a `group` property, which specifies what state to be changed.
+     * @returns {boolean}
+     *   `false` if change in state shouldn't happen, e.g. when the given new state is the same as the current one.
+     */
+  }
+
+  /**
+   * The callback called once changing state is finished or is canceled.
+   * @callback EventedState~changeStateCallback
+   * @param {Error} error
+   *   An error object with `true` in its `canceled` property if changing state is canceled.
+   *   Cancellation happens if the handler of a custom event, that is fired before changing state happens,
+   *   calls `.preventDefault()` against the event.
+   * @param {boolean} keptState
+   *   `true` if the call to {@link EventedState#changeState `.changeState()`} didn't cause actual change in state.
+   */
+
+  return EventedState;
+}

package/src/globals/js/mixins/handles.js

@@ -0,0 +1,45 @@
+export default function(ToMix) {
+  /**
+   * Mix-in class to manage handles in component.
+   * Managed handles are automatically released when the component with this class mixed in is released.
+   * @class Handles
+   * @implements Handle
+   */
+  class Handles extends ToMix {
+    /**
+     * The handled managed by this component.
+     * Releasing this component releases the handles.
+     * @type {Set<Handle>}
+     */
+    handles = new Set();
+
+    /**
+     * Manages the given handle.
+     * @param {Handle} handle The handle to manage.
+     * @returns {Handle} The given handle.
+     */
+    manage(handle) {
+      this.handles.add(handle);
+      return handle;
+    }
+
+    /**
+     * Stop managing the given handle.
+     * @param {Handle} handle The handle to stop managing.
+     * @returns {Handle} The given handle.
+     */
+    unmanage(handle) {
+      this.handles.delete(handle);
+      return handle;
+    }
+
+    release() {
+      this.handles.forEach(handle => {
+        handle.release();
+        this.handles.delete(handle);
+      });
+      return super.release();
+    }
+  }
+  return Handles;
+}

package/src/globals/js/mixins/init-component-by-event.js

@@ -0,0 +1,84 @@
+import eventMatches from '../misc/event-matches';
+import on from '../misc/on';
+
+export default function(ToMix) {
+  /**
+   * Mix-in class to instantiate components upon events.
+   * @class InitComponentByEvent
+   */
+  class InitComponentByEvent extends ToMix {
+    /**
+     * `true` suggests that this component is lazily initialized upon an action/event, etc.
+     * @type {boolean}
+     */
+    static forLazyInit = true;
+
+    /**
+     * Instantiates this component in the given element.
+     * If the given element indicates that it's an component of this class, instantiates it.
+     * Otherwise, instantiates this component by clicking on this component in the given node.
+     * @param {Node} target The DOM node to instantiate this component in. Should be a document or an element.
+     * @param {Object} [options] The component options.
+     * @param {string} [options.selectorInit] The CSS selector to find this component.
+     * @returns {Handle} The handle to remove the event listener to handle clicking.
+     */
+    static init(target = document, options = {}) {
+      const effectiveOptions = Object.assign(
+        Object.create(this.options),
+        options
+      );
+      if (
+        target.nodeType !== Node.ELEMENT_NODE &&
+        target.nodeType !== Node.DOCUMENT_NODE
+      ) {
+        throw new TypeError(
+          'DOM document or DOM element should be given to search for and initialize this widget.'
+        );
+      }
+      if (
+        target.nodeType === Node.ELEMENT_NODE &&
+        target.matches(effectiveOptions.selectorInit)
+      ) {
+        this.create(target, options);
+      } else {
+        // To work around non-bubbling `focus` event, use `focusin` event instead of it's available, and "capture mode" otherwise
+        const hasFocusin =
+          'onfocusin' in
+          (target.nodeType === Node.ELEMENT_NODE
+            ? target.ownerDocument
+            : target
+          ).defaultView;
+        const handles = effectiveOptions.initEventNames.map(name => {
+          const eventName = name === 'focus' && hasFocusin ? 'focusin' : name;
+          return on(
+            target,
+            eventName,
+            event => {
+              const element = eventMatches(
+                event,
+                effectiveOptions.selectorInit
+              );
+              // Instantiated components handles events by themselves
+              if (element && !this.components.has(element)) {
+                const component = this.create(element, options);
+                if (typeof component.createdByEvent === 'function') {
+                  component.createdByEvent(event);
+                }
+              }
+            },
+            name === 'focus' && !hasFocusin
+          );
+        });
+        return {
+          release() {
+            for (let handle = handles.pop(); handle; handle = handles.pop()) {
+              handle.release();
+            }
+          },
+        };
+      }
+      return '';
+    }
+  }
+  return InitComponentByEvent;
+}

package/src/globals/js/mixins/init-component-by-launcher.js

@@ -0,0 +1,89 @@
+import eventMatches from '../misc/event-matches';
+import on from '../misc/on';
+
+export default function(ToMix) {
+  /**
+   * Mix-in class to instantiate components events on launcher button.
+   * @class InitComponentByLauncher
+   */
+  class InitComponentByLauncher extends ToMix {
+    /**
+     * `true` suggests that this component is lazily initialized upon an action/event, etc.
+     * @type {boolean}
+     */
+    static forLazyInit = true;
+
+    /**
+     * Instantiates this component in the given element.
+     * If the given element indicates that it's an component of this class, instantiates it.
+     * Otherwise, instantiates this component by clicking on launcher buttons
+     * (buttons with attribute that `options.attribInitTarget` points to) of this component in the given node.
+     * @param {Node} target The DOM node to instantiate this component in. Should be a document or an element.
+     * @param {Object} [options] The component options.
+     * @param {string} [options.selectorInit] The CSS selector to find this component.
+     * @param {string} [options.attribInitTarget] The attribute name in the launcher buttons to find target component.
+     * @returns {Handle} The handle to remove the event listener to handle clicking.
+     */
+    static init(target = document, options = {}) {
+      const effectiveOptions = Object.assign(
+        Object.create(this.options),
+        options
+      );
+      if (
+        target.nodeType !== Node.ELEMENT_NODE &&
+        target.nodeType !== Node.DOCUMENT_NODE
+      ) {
+        throw new TypeError(
+          'DOM document or DOM element should be given to search for and initialize this widget.'
+        );
+      }
+      if (
+        target.nodeType === Node.ELEMENT_NODE &&
+        target.matches(effectiveOptions.selectorInit)
+      ) {
+        this.create(target, options);
+      } else {
+        const handles = effectiveOptions.initEventNames.map(name =>
+          on(target, name, event => {
+            const launcher = eventMatches(
+              event,
+              `[${effectiveOptions.attribInitTarget}]`
+            );
+
+            if (launcher) {
+              event.delegateTarget = launcher; // eslint-disable-line no-param-reassign
+              const elements = [
+                ...launcher.ownerDocument.querySelectorAll(
+                  launcher.getAttribute(effectiveOptions.attribInitTarget)
+                ),
+              ];
+              if (elements.length > 1) {
+                throw new Error('Target widget must be unique.');
+              }
+
+              if (elements.length === 1) {
+                if (launcher.tagName === 'A') {
+                  event.preventDefault();
+                }
+
+                const component = this.create(elements[0], options);
+                if (typeof component.createdByLauncher === 'function') {
+                  component.createdByLauncher(event);
+                }
+              }
+            }
+          })
+        );
+        return {
+          release() {
+            for (let handle = handles.pop(); handle; handle = handles.pop()) {
+              handle.release();
+            }
+          },
+        };
+      }
+      return '';
+    }
+  }
+  return InitComponentByLauncher;
+}