@progressiveui/react 2.0.2 → 2.0.4

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

@@ -1,207 +0,0 @@
-# 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

@@ -1,69 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,124 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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

@@ -1,84 +0,0 @@
-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

@@ -1,89 +0,0 @@
-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;
-}