Skip to content

Commit 5f5e8c8

Browse files
10xjs10xjs
authored
Merge pull request #37 from metalabdesign/5.x.x
Rewrite FlowTip component and layout algorithm
2 parents 9c4501b + 04381bc commit 5f5e8c8

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+14391
-2080
lines changed

‎.babelrc

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"presets": ["metalab"]
2+
"presets": ["env", "react", "stage-2"],
33
}

‎.editorconfig

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
#
2+
# EditorConfig: http://EditorConfig.org
3+
#
4+
# This files specifies some basic editor conventions for the files in this
5+
# project. Many editors support this standard, you simply need to find a plugin
6+
# for your favorite!
7+
#
8+
# For a full list of possible values consult the reference.
9+
# https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties
10+
#
11+
12+
# Stop searching for other .editorconfig files above this folder.
13+
root = true
14+
15+
# Pick some sane defaults for all files.
16+
[*]
17+
18+
# UNIX line-endings are preferred.
19+
# http://adaptivepatchwork.com/2012/03/01/mind-the-end-of-your-line/
20+
end_of_line = lf
21+
22+
# No reason in these modern times to use anything other than UTF-8.
23+
charset = utf-8
24+
25+
# Ensure that there's no bogus whitespace in the file.
26+
trim_trailing_whitespace = true
27+
28+
# A little esoteric, but it's kind of a standard now.
29+
# http://stackoverflow.com/questions/729692/why-should-files-end-with-a-newline
30+
insert_final_newline = true
31+
32+
# Pragmatism today.
33+
# http://programmers.stackexchange.com/questions/57
34+
indent_style = 2
35+
36+
# Personal preference here. Smaller indent size means you can fit more on a line
37+
# which can be nice when there are lines with several indentations.
38+
indent_size = 2
39+
40+
# Prefer a more conservative default line length – this allows editors with
41+
# sidebars, minimaps, etc. to show at least two documents side-by-side.
42+
# Hard wrapping by default for code is useful since many editors don't support
43+
# an elegant soft wrap; however, soft wrap is fine for things where text just
44+
# flows normally, like Markdown documents or git commit messages. Hard wrap
45+
# is also easier for line-based diffing tools to consume.
46+
# See: http://tex.stackexchange.com/questions/54140
47+
max_line_length = 80
48+
49+
# Markdown uses trailing spaces to create line breaks.
50+
[*.md]
51+
trim_trailing_whitespace = false

‎.eslintignore

+6-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,6 @@
1-
node_modules/*
2-
lib/*
1+
node_modules
2+
coverage
3+
dist
4+
lib
5+
types
6+
flow-typed

‎.eslintrc

+3-6
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
1-
{
2-
"extends": [
3-
"metalab",
4-
"metalab/react"
5-
]
6-
}
1+
extends:
2+
- metalab
3+
- metalab/react

‎.flowconfig

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[ignore]
2+
.*/node_modules/conventional-changelog-core/.*\.json$
3+
.*/node_modules/enzyme-matchers/src
4+
5+
[include]
6+
7+
[libs]
8+
<PROJECT_ROOT>/flow-typed
9+
10+
[options]
11+
emoji=true

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
node_modules
22
*.log
33
coverage
4+
lib
5+
dist

‎.npmignore

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
node_modules/
2-
build/*
1+
**/__test__/**
2+
src

‎.nvmrc

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
8

‎.travis.yml

+13-11
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
1-
sudo: false
21
language: node_js
3-
matrix:
4-
include:
5-
# Run tests in Node.js 4.x
6-
- node_js: '4'
72

8-
# Run tests in Node.js 5.x
9-
- node_js: '5'
3+
node_js:
4+
- "8"
5+
6+
sudo: false
7+
8+
cache:
9+
directories:
10+
- ".eslintcache"
11+
- "node_modules"
1012

11-
# Run tests in Node.js 6.x
12-
- node_js: '6'
13+
script:
14+
- npm run test
1315

1416
after_script:
15-
- npm install coveralls
16-
- cat ./coverage/coverage.json | ./node_modules/.bin/adana --format lcov | ./node_modules/coveralls/bin/coveralls.js
17+
- npm i coveralls
18+
- cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js

‎README.md

+15-203
Original file line numberDiff line numberDiff line change
@@ -1,221 +1,33 @@
11
# FlowTip
22

3-
*A flexible, adaptable and easy to use tooltip component for React.js*
3+
*A flexible, adaptable, and easy to use tooltip positioning library.*
44

55
![build status](http://img.shields.io/travis/metalabdesign/flowtip/master.svg?style=flat)
66
![coverage](http://img.shields.io/coveralls/metalabdesign/flowtip/master.svg?style=flat)
77
![license](http://img.shields.io/npm/l/flowtip.svg?style=flat)
88
![version](http://img.shields.io/npm/v/flowtip.svg?style=flat)
99
![downloads](http://img.shields.io/npm/dm/flowtip.svg?style=flat)
1010

11-
Looking for the non-React.js version? It's in the [legacy](https://github.com/qiushihe/flowtip/tree/legacy) branch.
11+
## Packages
1212

13-
At its core, `FlowTip` is a set of calculations that ensure.
13+
FlowTip is managed as a monorepo that is composed of several npm packages.
1414

15-
## Demo
15+
| Package | Version |
16+
|---------|---------|
17+
| [`flowtip-core`] | [![npm](https://img.shields.io/npm/v/flowtip-core.svg?maxAge=2592000)](https://www.npmjs.com/package/flowtip-core) |
18+
| [`flowtip-react-dom`] | [![npm](https://img.shields.io/npm/v/flowtip-react-dom.svg?maxAge=2592000)](https://www.npmjs.com/package/flowtip-react-dom) |
1619

17-
See the [demo from the legacy branch](http://qiushihe.github.io/flowtip/demo.html). The code sample on the side doesn't apply to the current React version but the behaviour is basically the same.
20+
#### [`flowtip-core`]
1821

19-
## Peer Dependencies
22+
This package contains the layout resolver algorithm.
2023

21-
* `react >= 0.14`
22-
* `react-dom >= 0.14`
24+
The resolver algorithm has no binding to React or to the DOM. It is simply a pure function that calculates the current layout state for a set of provided measurements.
2325

24-
## Glossaries
26+
#### [`flowtip-react-dom`]
2527

26-
The documentation and source of this library refers to several terms that may require
27-
clarification:
28+
A FlowTip Component for [React DOM] using [`flowtip-core`] internally.
2829

29-
**Parent**: The element bounding the tooltip.
30+
[`flowtip-core`]: /packages/flowtip-core
31+
[`flowtip-react-dom`]: /packages/flowtip-react-dom
3032

31-
**Content**: The container element for the tooltip's content.
32-
33-
**Tail**: The tail of the tooltip. It's usually visualized as a pointy "nub" of sort.
34-
35-
**Target**: The target is the thing the tooltip points to.
36-
37-
**Region**: There are four different regions a tooltip could be in at any given time. The four regions are "top", "bottom", "left" and "right". Region is described relative to the target of the tooltip. For example, region "top" means the tooltip would appear above the target, and region "right" means the tooltip would appear to the right side of the target.
38-
39-
**Pivot**: The pivot is a imaginary line that is aligned to the target and the tooltip's root is then in term aligned to the pivot.
40-
41-
**Anchor**: The element from which the tooltips position is referenced.
42-
43-
## Basic Usage
44-
45-
To include an instance of FlowTip in your component:
46-
47-
```javascript
48-
import flowtip from 'flowtip/lib/dom';
49-
50-
// Define the FlowTip content component
51-
const ContentComponent = ({style, region, children}) => (
52-
<div className={`flowtip-root flowtip-root-${region}`} style={style}>
53-
{children}
54-
</div>
55-
);
56-
57-
// Define the FlowTip tail component
58-
const TailComponent = ({style, region}) => (
59-
<div className={`flowtip-tail flowtip-tail-${region}`} style={style} />
60-
);
61-
62-
// Generate a FlowTip™ component with the content and tail components.
63-
const MyFlowTip = flowtip(ContentComponent, TailComponent);
64-
65-
// Render the FlowTip™ component.
66-
const target = {
67-
top: 5,
68-
left: 5,
69-
width: 100,
70-
height: 100,
71-
};
72-
73-
<MyFlowTip target={target}>
74-
<b>Holy Shit!</b>
75-
<br />
76-
FlowTip as React Component
77-
</FlowTip>
78-
```
79-
80-
The `target` property specifies the position and dimension of the tooltip's target as calculated by `getBoundingClientRect()`.
81-
82-
83-
## Advanced Usage
84-
85-
The primary FlowTip component is essentially a stateless function that computes where the tooltip _should be_ displayed (based on the bounding boxes you pass to it) and then passes that information down to its children. It's quite possible to build tooltips for platforms other than just the browser.
86-
87-
The DOM implementation takes care of computing all the values except `target` for you.
88-
89-
```javascript
90-
import FlowTip from 'flowtip';
91-
92-
<FlowTip
93-
tail={...}
94-
content={...}
95-
target={...}
96-
parent={...}
97-
anchor={...}
98-
children={({content, tail}) => (
99-
<div style={{
100-
position: "absolute",
101-
left: content.left,
102-
top: content.top,
103-
}}>
104-
Hello.
105-
<div style={{
106-
position: "absolute",
107-
left: tail.left,
108-
top: tail.top,
109-
}}/>
110-
</div>
111-
)}
112-
/>
113-
```
114-
115-
## FlowTip Properties
116-
117-
### `region`: **String**
118-
119-
_Default value: top_
120-
121-
The preferred region in which the tooltip will appear at first relative to its target. Possibly values are: `top`, `bottom`, `left` and `right`.
122-
123-
### `topDisabled`, `bottomDisabled`, `leftDisabled` and `rightDisabled`: **Boolean**
124-
125-
_Default value: false_
126-
127-
When set to `true`, the specified region will become unavailable for the various edge detection algorithms.
128-
129-
### `hideInDisabledRegions`: **Boolean**
130-
131-
_Default value: false_
132-
133-
When set to `true`, and when the only suitable regions for the tooltip are disabled, the tooltip will be hidden. When set to `false`, and when the only suitable regions for the tooltip are disabled, the tooltip will be placed in its original region.
134-
135-
### `targetOffset`: **Integer**
136-
137-
_Default value: 10_
138-
139-
The distance between the tooltip's root (or tip of the tail, see `targetOffsetFrom` below) and the target's edge.
140-
141-
### `targetOffsetFrom`: **String**
142-
143-
_Default value: root_
144-
145-
Possible values are `root` and `tail`. When set to `root`, `targetOffset` will be calculated against the edge of the tooltip's root; When set to `tail`, `targetOffset` will be calculated against the tip of the tail.
146-
147-
### `edgeOffset`: **Integer**
148-
149-
_Default value: 30_
150-
151-
The distance between the tooltip's root's edge and the edge of the boundary representative the tooltip's `appendTo` element. When this distance is smaller than `edgeOffset`, edge detection will place the tooltip in an opposite region (i.e. flipping the tooltip).
152-
153-
### `rotationOffset`: **Integer**
154-
155-
_Default value: 30_
156-
157-
The distance between the target's edge and the edge of the boundary representative the tooltip's `appendTo` element. When this distance is smaller than `rotationOffset`, edge detection will place the tooltip in an adjacent region (i.e. rotating the tooltip).
158-
159-
### `targetAlign`: **String**
160-
161-
_Default value: center_
162-
163-
Possible values are `center` and `edge`. When set to `center`, the pivot will be center aligned against the target. When set to `edge`, one of the pivot's edge will be aligned against the pivot. See `targetAlignOffset` for the exact mechanics of the two values. This value can also be specified on a per-region basis via `[top|bottom|left|right]TargetAlign`, and if a region's specific value is absence, the value from `targetAlign` will be used.
164-
165-
### `targetAlignOffset`: **Integer**
166-
167-
_Default value: 0_
168-
169-
If `targetAlign` is set to `center`, this value controls the clockwise distance from the center of the target the pivot will shift. When this value is positive, the pivot will shift clockwise, and counter-clockwise when this value is negative.
170-
171-
If `targetAlign` is set to `edge`, the pivot will shift away from one of the target's edges. When this value is positive, the clockwise edge will be used, and the counter-clockwise edge will be used when this value is negative. The absolute value of this value controls the amount of shifting.
172-
173-
### `rootAlign`: **String**
174-
175-
_Default value: center_
176-
177-
Possible values are `center` and `edge`. When set to `center`, the tooltip's root will be center aligned against the pivot. When set to `edge`, one of the tooltip's root's edge will be aligned against the pivot. See `rootAlignOffset` for the exact mechanics of the two values. This value can also be specified on a per-region basis via `[top|bottom|left|right]RootAlign`, and if a region's specific value is absence, the value from `rootAlign` will be used.
178-
179-
### `rootAlignOffset`: **Integer**
180-
181-
_Default value: 0_
182-
183-
If `rootAlign` is set to `center`, this value controls the clockwise distance from the pivot the tooltip's root will shift. When this value is positive, the root will shift clockwise, and counter-clockwise when this value is negative.
184-
185-
If `rootAlign` is set to `edge`, one of the tooltip's root's edge will be aligned against the pivot. When this value is positive, the clockwise edge will be used, and the counter-clockwise edge will be used when this value is negative. The absolute value of this value controls the amount of shifting.
186-
187-
## Edge Detection
188-
189-
There are three strategies for detection: **flip**, **rotate** and **squeeze**.
190-
191-
### Flip
192-
193-
The tooltip will be flipped when the root of the tooltip gets too close to the edge of the boundary. Adjust `edgeOffset` to control the amount of space allowed. The tooltip will be flipped horizontally when in the left and right regions, and vertically when in the top and bottom regions.
194-
195-
### Rotate
196-
197-
The tooltip will be rotated to an adjacent region if the target gets too close to the edge of the boundary. Adjust `rotationOffset` to control the amount of space allowed. For example, the tooltip will be rotated to the top region if the tooltip is currently in the left or right region, and the target gets too close to the bottom edge of the boundary.
198-
199-
### Squeeze
200-
201-
The tooltip will be squeezed to an adjacent region if the root of the tooltip gets too close to the edge of the boundary on both sides. For example, if the tooltip is in left or right region, and neither region has enough space, the tooltip will be squeezed to the top region.
202-
203-
## Alignments
204-
205-
Tooltip's alignments are divided into **root alignment** and **target alignment**, each with a corresponding **offset** attribute that controls the direction of the alignment and offset amount.
206-
207-
### Target Alignment
208-
209-
Target alignment refers to the alignment of the pivot relative to the target of the tooltip. See `targetAlign` and `targetAlignOffset`.
210-
211-
### Root Alignment
212-
213-
Root alignment refers to the alignment of the tooltip's root relative to the pivot. See `rootAlign` and `rootAlignOffset`.
214-
215-
## Clamping
216-
217-
By default the tooltip is "clamped" to its parent. Meaning even if the target leaves the viewport, the tooltip would never leave the viewport. The clamping behaviour can be controlled via the `clamp` property.
218-
219-
When `clamp` is `true`, the flyout will always remains in the parent even if the target is out of the parent.
220-
221-
When `clamp` is `false`, the flyout will always attatch itself to the target, even if it’s outside the parent, but it will make a best effort to be in the parent.
33+
[React DOM]: https://facebook.github.io/react/docs/react-dom.html

‎demo/.DS_Store

-6 KB
Binary file not shown.

0 commit comments

Comments
 (0)