Change auto-placement directions

Author: kuy

README.md

@@ -82,7 +82,8 @@ That's it!
 A tooltip component. Please wrap a content which should be shown in a tooltip.
 
 + `name` *(`string`)*: A name of tooltip. This is used by `<Origin />` component.
-+ `place` *(`string`|`string[]`)*: A default direction of tooltip. This value can be overwritten by `<Origin />`'s `place` prop.
++ `place` *(`string`|`string[]`)*: A direction of tooltip. This value can be overwritten by `<Origin />`'s `place` prop. Default is `top`.
++ `auto` *(`boolean`)*: A switch to enable/disable the auto-placement feature. Default is `true`.
 + `within` *(`DOM`)*: A DOM element which is used to restrict the position where this tooltip is placed within.
 + `onHover` *(`Function`)*: A callback function to be called on mouseover at tooltip.
 + `onLeave` *(`Function`)*: A callback function to be called on mouseout at tooltip.
@@ -96,6 +97,7 @@ For advanced usage, you can override the default handlers; `onMouseEnter` and `o
 + `name` *(`string`|`string[]`)*: A name(s) to specify which tooltip(s) should be used.
 + `content` *(`string`|`DOM`|`DOM[]`)*: A content for tooltip. If string, it's sanitized by [DOMPurify](https://github.com/cure53/DOMPurify).
 + `place` *(`string`|`string[]`)*: A name of direction to specify a location of tooltip.
++ `auto` *(`boolean`)*: A switch to enable/disable the auto-placement feature.
 + `tagName` *(`string`)*: A tag name of wrapper element. Default is `span`.
 + `delay` *(`boolean`|`number`|`string`)*: A number of duration for delay feature.
 + `delayOn` *(`string`)*: A name of timing to enable the delay. `show`, `hide`, or `both`. Default is `hide`.

examples/content/app.js

@@ -45,11 +45,11 @@ class App extends Component {
         <p>
           If you provide a <Origin className="target custom" content="This is a custom content.">custom</Origin> content via Origin component's prop,
           it will overwrite a <Origin className="target default">default</Origin> content of Tooltip component.<br />
-          <Origin className="target html" place="right" content="This is a <b>html</b> content.<br />Sanitized by <a href='#'>DOMPurify</a>.<script>console.log('Hello XSS!');</script>">HTML</Origin> as string and <Origin className="target dom" content={dom}>DOM element</Origin> are also supported.
+          <Origin className="target html" content="This is a <b>html</b> content.<br />Sanitized by <a href='#'>DOMPurify</a>.<script>console.log('Hello XSS!');</script>">HTML</Origin> as string and <Origin className="target dom" content={dom}>DOM element</Origin> are also supported.
         </p>
 
         <p>
-          What time is it <Origin className="target right" place="right" onHover={this.handleHover} onLeave={this.handleLeave}>now</Origin>?
+          What time is it <Origin className="target time" onHover={this.handleHover} onLeave={this.handleLeave}>now</Origin>?
         </p>
 
         <Tooltip>

examples/place/app.js

@@ -46,11 +46,11 @@ class App extends Component {
           The 'place' prop <Origin className="target auto-string" place="left,bottom">can</Origin> be also passed as a comma separated string.
         </p>
 
-        <div ref="restricted" style={{ width: '400px', height: '160px', backgroundColor: 'lightgray', padding: '10px', position: 'relative' }}>
-          In default, <Origin name="restricted" className="target auto-top" place="top">redux-tooltip</Origin> supposes you want to do auto-placement within the browser window.<br />
+        <div ref="restricted" style={{ width: '388px', height: '160px', backgroundColor: 'lightgray', padding: '16px', position: 'relative' }}>
+          In default, <Origin name="restricted" className="target auto-top" place="top">redux-tooltip</Origin> supposes you want to do auto-placement within the browser window.<br /><br />
           Using <code>within</code> prop, you can specify <Origin name="restricted" className="target auto-right" place="right">DOM element</Origin> instead of BODY element.
-          <div style={{ position: 'absolute', bottom: '10px' }}>
-            This is a <Origin name="restricted" className="target auto-bottom" place="bottom">bottom</Origin> origin.
+          <div style={{ position: 'absolute', bottom: '16px' }}>
+            <Origin name="restricted" className="target auto-bottom" place="bottom">This</Origin> is a bottom origin.
           </div>
         </div>
 

src/utils.js

@@ -71,32 +71,21 @@ export function placement(place, content, origin) {
 }
 
 /**
- * Returns an opposite direction based on the given.
+ * Completes missing directions in given direction(s).
  *
- * @param {string|Array} dir - 'top', 'right', 'bottom', or 'left'.
- * @return {string} an opposite direction.
- * @throw
+ * @param {string|Array} dir - a direction or a list of directions.
+ * @return {Array}
  */
-export function opposite(dir) {
-  let place = dir;
-
-  // Alrays use first direction if Array is passed
-  if (typeof place === 'object' && typeof place.length === 'number' && 0 < place.length) {
-    place = place[0];
-  }
-
-  switch (place) {
-  case 'top':
-    return 'bottom';
-  case 'bottom':
-    return 'top';
-  case 'right':
-    return 'left';
-  case 'left':
-    return 'right';
+const DIRS = ['top', 'right', 'bottom', 'left'];
+export function complete(dir) {
+  if (typeof dir === 'string') {
+    dir = [dir];
+  } else {
+    dir = [...dir];
   }
 
-  throw new Error(`Unknown direction: "${dir}"`);
+  const missings = DIRS.filter(d => dir.indexOf(d) === -1);
+  return dir.concat(missings);
 }
 
 /**
@@ -193,7 +182,7 @@ export function overDirs(tip, el) {
  * Places and adjusts a tooltip.
  *
  * @param {Object} content - DOM element which contans a content.
- * @param {Object} props
+ * @param {Object} props - props set from Tooltip component.
  * @return {Object} 'offset': style data to locate, 'place': final direction of the tooltip
  */
 export function adjust(content, props) {
@@ -203,8 +192,8 @@ export function adjust(content, props) {
   if (typeof place === 'string') {
     place = place.split(',').map(p => p.trim());
   }
-  if (auto && place.length === 1) {
-    place.push(opposite(place));
+  if (auto) {
+    place = complete(place);
   }
 
   let pos, dirs, current, first;

tests/feature/content.js

@@ -102,7 +102,7 @@ describe('Content Example', () => {
   describe('continuous updating content', () => {
     it('should be worked', () => {
       // Mouseover
-      const origin = firstComponent(tree, Origin.WrappedComponent, { className: 'target right' }).refs.wrapper;
+      const origin = firstComponent(tree, Origin.WrappedComponent, { className: 'target time' }).refs.wrapper;
       TestUtils.Simulate.mouseEnter(origin);
 
       const tooltip = firstComponent(tree, Tooltip.WrappedComponent).refs.tooltip;
@@ -123,7 +123,7 @@ describe('Content Example', () => {
 
     it('should re-calculate a position of the tooltip', () => {
       // Mouseover to 'now' origin
-      const now = firstComponent(tree, Origin.WrappedComponent, { className: 'target right' }).refs.wrapper;
+      const now = firstComponent(tree, Origin.WrappedComponent, { className: 'target time' }).refs.wrapper;
       TestUtils.Simulate.mouseEnter(now);
 
       clock.tick(500);

tests/feature/place.js

@@ -180,7 +180,7 @@ describe('Place Example', () => {
 
       const topTipPos = position(tooltip);
       const topOriPos = position(top);
-      assert(topOriPos.bottom < topTipPos.top, 'tooltip should be located on bottom of the origin');
+      assert(topOriPos.right < topTipPos.left, 'tooltip should be located on right of the origin');
 
       // Mouseover to right
       const right = firstComponent(tree, Origin.WrappedComponent, { className: 'target auto-right' }).refs.wrapper;
@@ -189,7 +189,7 @@ describe('Place Example', () => {
 
       const rightTipPos = position(tooltip);
       const rightOriPos = position(right);
-      assert(rightTipPos.right < rightOriPos.left, 'tooltip should be located left of the origin');
+      assert(rightTipPos.bottom < rightOriPos.top, 'tooltip should be located top of the origin');
 
       // Mouseover to bottom
       const bottom = firstComponent(tree, Origin.WrappedComponent, { className: 'target auto-bottom' }).refs.wrapper;
@@ -198,7 +198,7 @@ describe('Place Example', () => {
 
       const bottomTipPos = position(tooltip);
       const bottomOriPos = position(bottom);
-      assert(bottomTipPos.bottom < bottomOriPos.top, 'tooltip should be located on top of the origin');
+      assert(bottomOriPos.right < bottomTipPos.left, 'tooltip should be located on right of the origin');
     });
 
     it("should be disabled by auto={false}", () => {

tests/unit/test_utils.js

@@ -2,29 +2,27 @@ import assert from 'power-assert';
 import * as utils from '../../src/utils';
 
 describe('utils', () => {
-  describe('.opposite', () => {
+  describe('.complete', () => {
     context('with a direction', () => {
-      it('returns an opposite direction', () => {
-        assert(utils.opposite('top') === 'bottom');
-        assert(utils.opposite('right') === 'left');
-        assert(utils.opposite('bottom') === 'top');
-        assert(utils.opposite('left') === 'right');
-      });
-    });
+      it('returns a completed list', () => {
+        assert.deepStrictEqual(utils.complete('top'), ['top', 'right', 'bottom', 'left']);
+        assert.deepStrictEqual(utils.complete('right'), ['right', 'top', 'bottom', 'left']);
+        assert.deepStrictEqual(utils.complete('bottom'), ['bottom', 'top', 'right', 'left']);
+        assert.deepStrictEqual(utils.complete('left'), ['left', 'top', 'right', 'bottom']);
 
-    context('with directions as Array', () => {
-      it('returns an opposite direction', () => {
-        assert(utils.opposite(['top']) === 'bottom');
-        assert(utils.opposite(['right', 'left']) === 'left');
+        assert.deepStrictEqual(utils.complete(['top']), ['top', 'right', 'bottom', 'left']);
+        assert.deepStrictEqual(utils.complete(['right']), ['right', 'top', 'bottom', 'left']);
+        assert.deepStrictEqual(utils.complete(['bottom']), ['bottom', 'top', 'right', 'left']);
+        assert.deepStrictEqual(utils.complete(['left']), ['left', 'top', 'right', 'bottom']);
       });
     });
 
-    context('with invalid direction', () => {
-      it('throws an exception', () => {
-        assert.throws(() => utils.opposite(), Error);
-        assert.throws(() => utils.opposite(''), Error);
-        assert.throws(() => utils.opposite(123), Error);
-        assert.throws(() => utils.opposite([]), Error);
+    context('with a list of directions', () => {
+      it('returns a completed list', () => {
+        assert.deepStrictEqual(utils.complete(['top', 'bottom']), ['top', 'bottom', 'right', 'left']);
+        assert.deepStrictEqual(utils.complete(['left', 'right']), ['left', 'right', 'top', 'bottom']);
+        assert.deepStrictEqual(utils.complete(['top', 'right', 'bottom', 'left']), ['top', 'right', 'bottom', 'left']);
+        assert.deepStrictEqual(utils.complete(['top', 'right', 'bottom', 'left']), ['top', 'right', 'bottom', 'left']);
       });
     });
   });