From 9e61a1433c36887e8ae2f1bb5a8ec08fc8d9fbca Mon Sep 17 00:00:00 2001
From: Matthieu Dumont <jerska@live.fr>
Date: Tue, 3 Nov 2015 10:50:44 +0100
Subject: [PATCH] feat(clearAll): New widget

- ClearAll: Component + tests
- clearAll: Widget + tests
- Documentation
- Default style
---
 components/ClearAll/ClearAll.js               |  49 +++++++
 .../ClearAll/__tests__/ClearAll-test.js       |  73 ++++++++++
 css/default/_clear-all.scss                   |  20 +++
 css/instantsearch.scss                        |   1 +
 dev/app.js                                    |   7 +
 dev/index.html                                |   1 +
 docs/_includes/widget-jsdoc/clearAll.md       |  16 +++
 docs/documentation.md                         |  41 ++++++
 lib/main.js                                   |   1 +
 widgets/clear-all/__tests__/clear-all-test.js | 130 ++++++++++++++++++
 widgets/clear-all/clear-all.js                |  93 +++++++++++++
 widgets/clear-all/defaultTemplates.js         |   5 +
 12 files changed, 437 insertions(+)
 create mode 100644 components/ClearAll/ClearAll.js
 create mode 100644 components/ClearAll/__tests__/ClearAll-test.js
 create mode 100644 css/default/_clear-all.scss
 create mode 100644 docs/_includes/widget-jsdoc/clearAll.md
 create mode 100644 widgets/clear-all/__tests__/clear-all-test.js
 create mode 100644 widgets/clear-all/clear-all.js
 create mode 100644 widgets/clear-all/defaultTemplates.js

diff --git a/components/ClearAll/ClearAll.js b/components/ClearAll/ClearAll.js
new file mode 100644
index 0000000000..7b23bb3c21
--- /dev/null
+++ b/components/ClearAll/ClearAll.js
@@ -0,0 +1,49 @@
+let React = require('react');
+
+let Template = require('../Template.js');
+
+let {isSpecialClick} = require('../../lib/utils.js');
+
+class ClearAll extends React.Component {
+  handleClick(e) {
+    if (isSpecialClick(e)) {
+      // do not alter the default browser behavior
+      // if one special key is down
+      return;
+    }
+    e.preventDefault();
+    this.props.clearAll();
+  }
+
+  render() {
+    const className = this.props.cssClasses.link;
+    const data = {
+      hasRefinements: this.props.hasRefinements
+    };
+
+    return (
+      <a
+        className={className}
+        href={this.props.url}
+        onClick={this.handleClick.bind(this)}
+      >
+        <Template
+          data={data}
+          templateKey="link"
+          {...this.props.templateProps}
+        />
+      </a>);
+  }
+}
+
+ClearAll.propTypes = {
+  clearAll: React.PropTypes.func.isRequired,
+  cssClasses: React.PropTypes.shape({
+    link: React.PropTypes.string
+  }),
+  hasRefinements: React.PropTypes.bool.isRequired,
+  templateProps: React.PropTypes.object.isRequired,
+  url: React.PropTypes.string.isRequired
+};
+
+module.exports = ClearAll;
diff --git a/components/ClearAll/__tests__/ClearAll-test.js b/components/ClearAll/__tests__/ClearAll-test.js
new file mode 100644
index 0000000000..8b30c94586
--- /dev/null
+++ b/components/ClearAll/__tests__/ClearAll-test.js
@@ -0,0 +1,73 @@
+/* eslint-env mocha */
+
+import React from 'react';
+import expect from 'expect';
+import sinon from 'sinon';
+import TestUtils from 'react-addons-test-utils';
+import ClearAll from '../ClearAll.js';
+import Template from '../../Template.js';
+
+import expectJSX from 'expect-jsx';
+expect.extend(expectJSX);
+
+let {createRenderer} = TestUtils;
+
+describe('ClearAll', () => {
+  let renderer;
+  let defaultProps = {
+    clearAll: () => {},
+    cssClasses: {
+      link: 'custom-link'
+    },
+    hasRefinements: false,
+    templateProps: {},
+    url: '#all-cleared!'
+  };
+
+  beforeEach(() => {
+    renderer = createRenderer();
+  });
+
+  it('should render <ClearAll />', () => {
+    let out = render();
+    expect(out).toEqualJSX(
+      <a
+        className="custom-link"
+        href="#all-cleared!"
+        onClick={() => {}}
+      >
+        <Template
+          data={{hasRefinements: false}}
+          templateKey="link"
+        />
+      </a>);
+  });
+
+  it('should handle clicks (and special clicks)', () => {
+    let props = {
+      clearAll: sinon.spy()
+    };
+    let preventDefault = sinon.spy();
+    let component = new ClearAll(props);
+    ['ctrlKey', 'shiftKey', 'altKey', 'metaKey'].forEach((e) => {
+      let event = {preventDefault};
+      event[e] = true;
+      component.handleClick(event);
+      expect(props.clearAll.called).toBe(false, 'clearAll never called');
+      expect(preventDefault.called).toBe(false, 'preventDefault never called');
+    });
+    component.handleClick({preventDefault});
+    expect(props.clearAll.calledOnce).toBe(true, 'clearAll called once');
+    expect(preventDefault.calledOnce).toBe(true, 'preventDefault called once');
+  });
+
+
+  function render(extraProps = {}) {
+    let props = {
+      ...defaultProps,
+      ...extraProps
+    };
+    renderer.render(<ClearAll {...props} />);
+    return renderer.getRenderOutput();
+  }
+});
diff --git a/css/default/_clear-all.scss b/css/default/_clear-all.scss
new file mode 100644
index 0000000000..94473499b3
--- /dev/null
+++ b/css/default/_clear-all.scss
@@ -0,0 +1,20 @@
+@import "../base";
+@import "variables";
+
+@include block(clear-all) {
+  @include element(header) {
+    /* widget header */
+  }
+
+  @include element(body) {
+    /* widget body */
+  }
+
+  @include element(link) {
+    /* widget link */
+  }
+
+  @include element(footer) {
+    /* widget footer */
+  }
+}
diff --git a/css/instantsearch.scss b/css/instantsearch.scss
index 541d31c452..78072d0c5b 100644
--- a/css/instantsearch.scss
+++ b/css/instantsearch.scss
@@ -11,4 +11,5 @@
 @import "default/hierarchical-menu";
 @import "default/range-slider";
 @import "default/price-ranges" ;
+@import "default/clear-all";
 
diff --git a/dev/app.js b/dev/app.js
index 435e9f3c1a..87f545dcfe 100644
--- a/dev/app.js
+++ b/dev/app.js
@@ -74,6 +74,13 @@ search.addWidget(
   })
 );
 
+search.addWidget(
+  instantsearch.widgets.clearAll({
+    container: '#clear-all',
+    autoHideContainer: false
+  })
+);
+
 search.addWidget(
   instantsearch.widgets.refinementList({
     container: '#brands',
diff --git a/dev/index.html b/dev/index.html
index 01025cb4b8..741f90c8a9 100644
--- a/dev/index.html
+++ b/dev/index.html
@@ -21,6 +21,7 @@ <h1><a href="./">Instant search demo</a> <small>using instantsearch.js</small></
 
     <div class="row search search--hidden">
       <div class="col-md-3">
+        <div id="clear-all"></div>
         <div class="facet" id="hierarchical-categories"></div>
         <div class="facet" id="brands"></div>
         <div class="facet" id="price-range"></div>
diff --git a/docs/_includes/widget-jsdoc/clearAll.md b/docs/_includes/widget-jsdoc/clearAll.md
new file mode 100644
index 0000000000..31f032fc26
--- /dev/null
+++ b/docs/_includes/widget-jsdoc/clearAll.md
@@ -0,0 +1,16 @@
+| Param | Description |
+| --- | --- |
+|  <span class='attr-required'>`options.container`</span> | CSS Selector or DOMElement to insert the widget |
+|  <span class='attr-optional'>`options.cssClasses`</span> | CSS classes to add |
+|  <span class='attr-optional'>`options.cssClasses.root`</span> | CSS class to add to the root element |
+|  <span class='attr-optional'>`options.cssClasses.header`</span> | CSS class to add to the header element |
+|  <span class='attr-optional'>`options.cssClasses.body`</span> | CSS class to add to the body element |
+|  <span class='attr-optional'>`options.cssClasses.footer`</span> | CSS class to add to the footer element |
+|  <span class='attr-optional'>`options.cssClasses.link`</span> | CSS class to add to the link element |
+|  <span class='attr-optional'>`options.templates`</span> | Templates to use for the widget |
+|  <span class='attr-optional'>`options.templates.header`</span> | Header template |
+|  <span class='attr-optional'>`options.templates.link`</span> | Link template |
+|  <span class='attr-optional'>`options.templates.footer`</span> | Footer template |
+|  <span class='attr-optional'>`options.autoHideContainer`</span> | Hide the container when there's no refinement to clear |
+
+<p class="attr-legend">* <span>Required</span></p>
diff --git a/docs/documentation.md b/docs/documentation.md
index 9702771114..54de173d9c 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -752,6 +752,47 @@ instantsearch.widgets.priceRanges(options);
 
 <div id="price-ranges" class="widget-container"></div>
 
+#### clearAll
+
+<div class="codebox-combo">
+
+<img class="widget-icon pull-left" src="../img/icon-widget-clearall.svg">
+This filtering widget lets the user choose between ranges of price. Those ranges are dynamically computed based on the returned results.
+{:.description}
+
+<div class="code-box">
+  <div class="code-sample-snippet">
+{% highlight javascript %}
+search.addWidget(
+  instantsearch.widgets.clearAll({
+    container: '#clear-all',
+    templates: {
+      link: 'Reset everything'
+    },
+    cssClasses: {
+      root: '',
+      header: '',
+      body: '',
+      footer: '',
+      link: '',
+      },
+      autoHideContainer: false
+  })
+);
+{% endhighlight %}
+  </div>
+  <div class="jsdoc" style='display:none'>
+{% highlight javascript %}
+instantsearch.widgets.clearAll(options);
+{% endhighlight %}
+{% include widget-jsdoc/clearAll.md %}
+  </div>
+</div>
+
+</div>
+
+<div id="clear-all" class="widget-container"></div>
+
 ### Sort
 
 #### indexSelector
diff --git a/lib/main.js b/lib/main.js
index 305c3b2633..44606d2028 100644
--- a/lib/main.js
+++ b/lib/main.js
@@ -8,6 +8,7 @@ let instantsearch = toFactory(InstantSearch);
 let algoliasearchHelper = require('algoliasearch-helper');
 
 instantsearch.widgets = {
+  clearAll: require('../widgets/clear-all/clear-all.js'),
   hierarchicalMenu: require('../widgets/hierarchical-menu/hierarchical-menu.js'),
   hits: require('../widgets/hits/hits'),
   hitsPerPageSelector: require('../widgets/hits-per-page-selector/hits-per-page-selector'),
diff --git a/widgets/clear-all/__tests__/clear-all-test.js b/widgets/clear-all/__tests__/clear-all-test.js
new file mode 100644
index 0000000000..40ace0ff20
--- /dev/null
+++ b/widgets/clear-all/__tests__/clear-all-test.js
@@ -0,0 +1,130 @@
+/* eslint-env mocha */
+
+import React from 'react';
+
+import expect from 'expect';
+import sinon from 'sinon';
+import jsdom from 'mocha-jsdom';
+
+import expectJSX from 'expect-jsx';
+expect.extend(expectJSX);
+
+import clearAll from '../clear-all';
+import ClearAll from '../../../components/ClearAll/ClearAll';
+
+describe('clearAll()', () => {
+  jsdom({useEach: true});
+
+  let ReactDOM;
+  let container;
+  let widget;
+  let props;
+  let results;
+  let helper;
+  let autoHideContainerHOC;
+  let headerFooterHOC;
+  let createURL;
+
+  beforeEach(() => {
+    ReactDOM = {render: sinon.spy()};
+    autoHideContainerHOC = sinon.stub().returns(ClearAll);
+    headerFooterHOC = sinon.stub().returns(ClearAll);
+    createURL = sinon.stub().returns('#all-cleared');
+
+    clearAll.__Rewire__('ReactDOM', ReactDOM);
+    clearAll.__Rewire__('autoHideContainerHOC', autoHideContainerHOC);
+    clearAll.__Rewire__('headerFooterHOC', headerFooterHOC);
+
+    container = document.createElement('div');
+    widget = clearAll({container, autoHideContainer: true});
+
+    results = {};
+    helper = {
+      state: {
+        clearRefinements: sinon.spy(),
+        clearTags: sinon.spy()
+      },
+      search: sinon.spy()
+    };
+
+    props = {
+      clearAll: sinon.spy(),
+      cssClasses: {
+        root: 'ais-clear-all',
+        header: 'ais-clear-all--header',
+        body: 'ais-clear-all--body',
+        footer: 'ais-clear-all--footer',
+        link: 'ais-clear-all--link'
+      },
+      hasRefinements: false,
+      shouldAutoHideContainer: true,
+      templateProps: {
+        templates: require('../defaultTemplates'),
+        templatesConfig: undefined,
+        transformData: undefined,
+        useCustomCompileOptions: {header: false, footer: false, link: false}
+      },
+      url: '#all-cleared'
+    };
+  });
+
+  it('configures nothing', () => {
+    expect(widget.getConfiguration).toEqual(undefined);
+  });
+
+  it('calls the decorators', () => {
+    widget.render({results, helper, state: helper.state, createURL});
+    expect(headerFooterHOC.calledOnce).toBe(true);
+    expect(autoHideContainerHOC.calledOnce).toBe(true);
+  });
+
+  context('without refinements', () => {
+    beforeEach(() => {
+      helper.state.facetsRefinements = {};
+      props.hasRefinements = false;
+      props.shouldAutoHideContainer = true;
+    });
+
+    it('calls twice ReactDOM.render(<ClearAll props />, container)', () => {
+      widget.render({results, helper, state: helper.state, createURL});
+      widget.render({results, helper, state: helper.state, createURL});
+
+      expect(ReactDOM.render.calledTwice).toBe(true, 'ReactDOM.render called twice');
+      expect(ReactDOM.render.firstCall.args[0]).toEqualJSX(<ClearAll {...getProps()} />);
+      expect(ReactDOM.render.firstCall.args[1]).toEqual(container);
+      expect(ReactDOM.render.secondCall.args[0]).toEqualJSX(<ClearAll {...getProps()} />);
+      expect(ReactDOM.render.secondCall.args[1]).toEqual(container);
+    });
+  });
+
+  context('with refinements', () => {
+    beforeEach(() => {
+      helper.state.facetsRefinements = ['something'];
+      props.hasRefinements = true;
+      props.shouldAutoHideContainer = false;
+    });
+
+    it('calls twice ReactDOM.render(<ClearAll props />, container)', () => {
+      widget.render({results, helper, state: helper.state, createURL});
+      widget.render({results, helper, state: helper.state, createURL});
+
+      expect(ReactDOM.render.calledTwice).toBe(true, 'ReactDOM.render called twice');
+      expect(ReactDOM.render.firstCall.args[0]).toEqualJSX(<ClearAll {...getProps()} />);
+      expect(ReactDOM.render.firstCall.args[1]).toEqual(container);
+      expect(ReactDOM.render.secondCall.args[0]).toEqualJSX(<ClearAll {...getProps()} />);
+      expect(ReactDOM.render.secondCall.args[1]).toEqual(container);
+    });
+  });
+
+  afterEach(() => {
+    clearAll.__ResetDependency__('ReactDOM');
+    clearAll.__ResetDependency__('defaultTemplates');
+  });
+
+  function getProps(extraProps = {}) {
+    return {
+      ...props,
+      ...extraProps
+    };
+  }
+});
diff --git a/widgets/clear-all/clear-all.js b/widgets/clear-all/clear-all.js
new file mode 100644
index 0000000000..7817c7424d
--- /dev/null
+++ b/widgets/clear-all/clear-all.js
@@ -0,0 +1,93 @@
+let React = require('react');
+let ReactDOM = require('react-dom');
+
+let {bemHelper, getContainerNode, prepareTemplateProps, getRefinements} = require('../../lib/utils.js');
+let bem = bemHelper('ais-clear-all');
+let cx = require('classnames');
+
+let autoHideContainerHOC = require('../../decorators/autoHideContainer');
+let headerFooterHOC = require('../../decorators/headerFooter');
+
+let defaultTemplates = require('./defaultTemplates');
+
+/**
+ * Allows to clear all refinements at once
+ * @param  {string|DOMElement} options.container CSS Selector or DOMElement to insert the widget
+ * @param  {Object} [options.cssClasses] CSS classes to be added
+ * @param  {string|string[]} [options.cssClasses.root] CSS class to add to the root element
+ * @param  {string|string[]} [options.cssClasses.header] CSS class to add to the header element
+ * @param  {string|string[]} [options.cssClasses.body] CSS class to add to the body element
+ * @param  {string|string[]} [options.cssClasses.footer] CSS class to add to the footer element
+ * @param  {string|string[]} [options.cssClasses.link] CSS class to add to the link element
+ * @param  {Object} [options.templates] Templates to use for the widget
+ * @param  {string|Function} [options.templates.header=''] Header template
+ * @param  {string|Function} [options.templates.link] Link template
+ * @param  {string|Function} [options.templates.footer=''] Footer template
+ * @param  {boolean} [options.autoHideContainer=true] Hide the container when there's no refinement to clear
+ * @return {Object}
+ */
+const usage = `Usage:
+toggle({
+  container,
+  [cssClasses.{root,header,body,footer,link}={}],
+  [templates.{header,link,footer}={header: '', link: 'Clear all', footer: ''}],
+  [autoHideContainer=true]
+})`;
+function clearAll({
+    container,
+    templates = defaultTemplates,
+    cssClasses: userCssClasses = {},
+    autoHideContainer = true
+  } = {}) {
+  if (!container) {
+    throw new Error(usage);
+  }
+
+  let containerNode = getContainerNode(container);
+  let ClearAll = headerFooterHOC(require('../../components/ClearAll/ClearAll.js'));
+  if (autoHideContainer === true) {
+    ClearAll = autoHideContainerHOC(ClearAll);
+  }
+
+  return {
+    _clearAll: function(helper) {
+      helper.clearTags().clearRefinements().search();
+    },
+
+    render: function({results, helper, state, templatesConfig, createURL}) {
+      let hasRefinements = getRefinements(results, state).length !== 0;
+
+      let cssClasses = {
+        root: cx(bem(null), userCssClasses.root),
+        header: cx(bem('header'), userCssClasses.header),
+        body: cx(bem('body'), userCssClasses.body),
+        footer: cx(bem('footer'), userCssClasses.footer),
+        link: cx(bem('link'), userCssClasses.link)
+      };
+
+      let url = createURL(state.clearRefinements());
+
+      let handleClick = this._clearAll.bind(null, helper);
+
+      let templateProps = prepareTemplateProps({
+        defaultTemplates,
+        templatesConfig,
+        templates
+      });
+
+      ReactDOM.render(
+        <ClearAll
+          clearAll={handleClick}
+          cssClasses={cssClasses}
+          hasRefinements={hasRefinements}
+          shouldAutoHideContainer={!hasRefinements}
+          templateProps={templateProps}
+          url={url}
+        />,
+        containerNode
+      );
+    }
+  };
+}
+
+module.exports = clearAll;
diff --git a/widgets/clear-all/defaultTemplates.js b/widgets/clear-all/defaultTemplates.js
new file mode 100644
index 0000000000..a0f7448bc7
--- /dev/null
+++ b/widgets/clear-all/defaultTemplates.js
@@ -0,0 +1,5 @@
+module.exports = {
+  header: '',
+  link: 'Clear all',
+  footer: ''
+};