Skip to content

Commit d31c08b

Browse files
matcmdmatcmd
committed
Initial commit
0 parents  commit d31c08b

13 files changed

+15997
-0
lines changed

‎.editorconfig

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
root = true
2+
3+
[*.{js,jsx,ts,tsx,vue,html,json,css,scss}]
4+
indent_style = space
5+
indent_size = 2
6+
end_of_line = lf
7+
trim_trailing_whitespace = true
8+
insert_final_newline = true
9+
max_line_length = 100

‎.gitignore

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.DS_Store
2+
node_modules
3+
/dist
4+
5+
# local env files
6+
.env.local
7+
.env.*.local
8+
9+
# Log files
10+
npm-debug.log*
11+
yarn-debug.log*
12+
yarn-error.log*
13+
14+
# Editor directories and files
15+
.idea
16+
.vscode
17+
*.suo
18+
*.ntvs*
19+
*.njsproj
20+
*.sln
21+
*.sw?

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2018-present Mattia Uggè and other contributors.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Vue Dropdown Directive
2+
3+
## Table of contents
4+
5+
1. [Installation](#installation)
6+
2. [Basic usage](#basic-usage)
7+
3. [Modifiers](#modifiers)
8+
4. [Parameters](#parameters)
9+
5. [Behaviour](#behaviour)
10+
6. [Methods](#methods)
11+
12+
## Installation
13+
14+
```bash
15+
$ npm install @teamwork/vue-dropdown-directive
16+
```
17+
18+
## Basic usage
19+
20+
```html
21+
<button v-dropdown-directive="{ id: 'unique-dropdown-id' }">Show list</button>
22+
<custom-dropdown dropdown-id="unique-dropdown-id">
23+
<!-- CONTENT -->
24+
</custom-dropdown>
25+
```
26+
27+
```js
28+
import DropdownDirective from '@teamwork/vue-dropdown-directive';
29+
30+
const directives = {
31+
DropdownDirective,
32+
};
33+
34+
const ExamplePage = {
35+
props,
36+
directives,
37+
computed,
38+
methods,
39+
...,
40+
};
41+
42+
export default ExamplePage;
43+
```
44+
45+
## Modifiers
46+
47+
``.bottom`` and ``.center`` are applied by default. If only one modifier is specified, ``.center`` is applied by default.
48+
49+
The first modifier refers to the position where the dropdown is placed:
50+
51+
- ``.bottom``
52+
- ``.left``
53+
- ``.right``
54+
- ``.top``
55+
56+
The second modifier refers to the alignment of the dropdown with the trigger element:
57+
58+
- ``.bottom`` and ``.top`` positions can have ``.left`` | ``.center`` | ``.right``
59+
- ``.right`` and ``.left`` positions can have ``.top`` | ``.center`` | ``.bottom``
60+
61+
```html
62+
<button v-dropdown-directive.top.left="{ id: 'unique-dropdown-id' }">Show list</button>
63+
<custom-dropdown dropdown-id="unique-dropdown-id">
64+
<!-- CONTENT -->
65+
</custom-dropdown>
66+
```
67+
68+
## Parameters
69+
70+
- ``id`` (__required__) is the *unique id* that *must* be assigned to the trigger element which links it to the dropdown element.
71+
- ``modifiers`` contains the *position* and *alignment*, it is generally used to programmatically override the native modifiers.
72+
73+
```js
74+
{
75+
right: true,
76+
center: true,
77+
}
78+
```
79+
80+
- ``scrollableContentClassName`` (__suggested__) is the class assigned to the wrapper element containing the main content within the dropdown, read [here](#behaviour) for more info on how it is used and why it would be better to set this.
81+
82+
```html
83+
<button v-dropdown-directive.top.left="{
84+
id: 'unique-dropdown-id',
85+
scrollableContentClassName: 'dropdown-list',
86+
}">
87+
Show list
88+
</button>
89+
<custom-dropdown dropdown-id="unique-dropdown-id">
90+
<ul
91+
class=".dropdown-list"
92+
slot="dropdown-content"
93+
>
94+
<li>User 1</li>
95+
<li>User 2</li>
96+
<li>User 3</li>
97+
</ul>
98+
</custom-dropdown>
99+
```
100+
101+
- ``otherScrollableContentClassNames`` is the list of class names within the dropdown that are allowed to scroll.
102+
- ``isReady`` is a *boolean* used to hold the directive hook *inserted* until the consumer is ready, the default is set to ``true``.
103+
- ``arrow`` is a *boolean* used to show/hide the arrow between the trigger and the dropdown, the default is set to ``false``.
104+
- ``arrowColor`` contains an *hexadecimal* used to set the color of the arrow next to the dropdown, the default is set to ``#fff``.
105+
- ``zIndex`` is a *number* that specifies that stack order of the dropdown and its arrow, the default is set to ``9999``.
106+
- ``offsetFromTrigger`` is a *number* that specifies the distance in pixels from where the dropdown is going to be rendered, the default is set to ``0``.
107+
- ``onOpen`` is a *function* that runs at the opening of the dropdown.
108+
- ``onClose`` is a *function* that runs on closing of the dropdown.
109+
- ``keepOtherDropdownsOpen`` is a *boolean* that keeps the other dropdowns within the viewport opened when the trigger element action happens, the default is set ``false``.
110+
- ``keepDropdownsOpenOnUIEvent`` is a *boolean* that keeps every dropdown within the viewport opened if a scroll or resize event has been triggered, the default is set ``true``.
111+
- ``openOnlyProgrammatically`` is a *boolean* used to disable the trigger element action that opens the dropdown. If set to ``true``, the dropdown can be opened only [programmatically](#methods).
112+
- ``allowTopCollocation`` is a *boolean* used to enable/disable the top position, the default is set to ``true``.
113+
- ``allowBottomCollocation`` is a *boolean* used to enable/disable the bottom position, the default is set to ``true``.
114+
- ``allowLeftCollocation`` is a *boolean* used to enable/disable the left position, the default is set to ``true``.
115+
- ``allowRightCollocation`` is a *boolean* used to enable/disable the right position, the default is set to ``true``.
116+
- ``hasTouchSupport`` is a *boolean* used to block the action that hides the dropdown when a resize event has been triggered, the default is set to ``false``.
117+
118+
## Behaviour
119+
120+
Most of the time the dropdown is opened at the position set. However, there might be some scenarios where the space available within the viewport is simply not enough. So, the directive runs automatically a simulation, either to find the area within the viewport with the most available space or if an overflow to the content of the dropdown could be applied.
121+
In order to prioritize the overflow of the content, the ``scrollableContentClassName`` parameter must be set. Instead, ``allowTopCollocation``, ``allowBottomCollocation``, ``allowLeftCollocation`` or ``allowRightCollocation`` parameters are used to restrict the positions to look for finding the areas with the most available space.
122+
In order to ensure the dropdown is always placed next to the trigger element, the directive hides and re-paints it every time a scroll or a resize of the viewport happens.
123+
124+
## Methods
125+
126+
- ``open()`` is used to open the dropdown.
127+
- ``close()`` is used to close the dropdown.
128+
- ``closeOthers()`` is used to close every dropdown within the viewport except the current one.
129+
- ``closeAll()`` is used to close every dropdown within the viewport.
130+
- ``recalculatePosition()`` is used to re-calculate the position of the dropdown within the viewport.
131+
- ``isOpen()`` is used to check if the current dropdown is showing.
132+
133+
This is an example of how the methods above can be executed:
134+
135+
```js
136+
updateDropdownPosition() {
137+
this.$refs.customDropdown.recalculatePosition();
138+
},
139+
```
140+
141+
```html
142+
<button v-dropdown-directive="{ id: 'unique-dropdown-id' }">Show list</button>
143+
<custom-dropdown
144+
ref="customDropdown"
145+
dropdown-id="unique-dropdown-id"
146+
>
147+
<!-- CONTENT -->
148+
</custom-dropdown>
149+
```

‎babel.config.js

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
module.exports = {
2+
presets: [
3+
'@vue/cli-plugin-babel/preset',
4+
],
5+
};

‎jest.config.js

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
preset: '@vue/cli-plugin-unit-jest',
3+
};

0 commit comments

Comments
 (0)