@cocreate/position 1.16.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/FUNDING.yml +1 -1
- package/.github/workflows/automated.yml +18 -7
- package/CHANGELOG.md +316 -275
- package/CONTRIBUTING.md +6 -6
- package/README.md +210 -85
- package/demo/index.html +474 -46
- package/docs/index.html +7 -7
- package/package.json +23 -18
- package/src/autoScroll.js +213 -0
- package/src/draggable/engine.js +698 -0
- package/src/draggable.js +64 -0
- package/src/eventOperator.js +15 -0
- package/src/helpers/events.js +34 -0
- package/src/index.css +19 -0
- package/src/index.js +222 -71
- package/src/position.js +443 -482
- package/src/snappable.js +572 -0
- package/test/auto-scroll.browser.cjs +307 -0
- package/webpack.config.js +1 -0
package/CONTRIBUTING.md
CHANGED
|
@@ -1,19 +1,19 @@
|
|
|
1
1
|
# Contributing to CoCreate-position
|
|
2
2
|
|
|
3
|
-
This project is work of [many contributors](https://github.com/
|
|
4
|
-
You're encouraged to submit [pull requests](https://github.com/
|
|
5
|
-
[propose features and discuss issues](https://github.com/
|
|
3
|
+
This project is work of [many contributors](https://github.com/CoCreateJS/position/graphs/contributors).
|
|
4
|
+
You're encouraged to submit [pull requests](https://github.com/CoCreateJS/position/pulls),
|
|
5
|
+
[propose features and discuss issues](https://github.com/CoCreateJS/position/issues).
|
|
6
6
|
|
|
7
7
|
In the examples below, substitute your Github username for `contributor` in URLs.
|
|
8
8
|
|
|
9
9
|
## Fork the Project
|
|
10
10
|
|
|
11
|
-
Fork the [project on Github](https://github.com/
|
|
11
|
+
Fork the [project on Github](https://github.com/CoCreateJS/position) and check out your copy.
|
|
12
12
|
|
|
13
13
|
```
|
|
14
14
|
git position https://github.com/contributor/CoCreate-position.git
|
|
15
15
|
cd CoCreate-position
|
|
16
|
-
git remote add upstream https://
|
|
16
|
+
git remote add upstream https://github.com/CoCreateJS/position.git
|
|
17
17
|
```
|
|
18
18
|
|
|
19
19
|
## Create a Topic Branch
|
|
@@ -75,7 +75,7 @@ git push origin my-feature-branch
|
|
|
75
75
|
|
|
76
76
|
## Make a Pull Request
|
|
77
77
|
|
|
78
|
-
Go to [https://github.com/
|
|
78
|
+
Go to [https://github.com/CoCreateJS/position](https://github.com/CoCreateJS/position) and select your feature branch.
|
|
79
79
|
Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
|
|
80
80
|
|
|
81
81
|
## Rebase
|
package/README.md
CHANGED
|
@@ -1,85 +1,210 @@
|
|
|
1
|
-
# CoCreate
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
 ·
|
|
9
|
+
[GitHub repository](https://github.com/CoCreateJS/position)
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
### CDN
|
|
21
|
+
|
|
22
|
+
```html
|
|
23
|
+
<link rel="stylesheet" href="https://cdn.CoCreateJS.com/position/latest/CoCreate-position.min.css">
|
|
24
|
+
<script src="https://cdn.CoCreateJS.com/position/latest/CoCreate-position.min.js"></script>
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### npm
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
npm install @cocreate/position
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
### Yarn
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
yarn add @cocreate/position
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The JavaScript entry imports Position's stylesheet. If your bundler extracts
|
|
40
|
+
CSS, make sure the generated stylesheet is included in your page.
|
|
41
|
+
|
|
42
|
+
## Overlay a box on a target
|
|
43
|
+
|
|
44
|
+
Use `position-query` to select the target and `position-element` to select the
|
|
45
|
+
overlay box. `position-events` lists the events that update the box; listeners
|
|
46
|
+
are attached directly to the element carrying these attributes:
|
|
47
|
+
|
|
48
|
+
```html
|
|
49
|
+
<button
|
|
50
|
+
position-events="click"
|
|
51
|
+
position-query="$this"
|
|
52
|
+
position-element="$top #target-box">
|
|
53
|
+
Show target box
|
|
54
|
+
</button>
|
|
55
|
+
|
|
56
|
+
<div id="target-box" class="target-box" hidden></div>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Position sets the box's `left`, `top`, `width`, and `height` to match the
|
|
60
|
+
queried target. It includes the target's margins. The box is shown and hidden
|
|
61
|
+
with the native `hidden` attribute; Position does not set `display`. Style the
|
|
62
|
+
box with CSS and give it `position: fixed` or `position: absolute` so its
|
|
63
|
+
coordinates apply.
|
|
64
|
+
|
|
65
|
+
By default, the box matches the target element. Set `position-box="text"` to
|
|
66
|
+
size it to the target's complete rendered text, including wrapped lines:
|
|
67
|
+
|
|
68
|
+
```html
|
|
69
|
+
<div
|
|
70
|
+
position-events="mouseover, mousemove, mouseout"
|
|
71
|
+
position-query="*:hover[]"
|
|
72
|
+
position-element="$top #text-box"
|
|
73
|
+
position-box="text">
|
|
74
|
+
<h2>A heading to inspect</h2>
|
|
75
|
+
<p>The text box follows all rendered lines.</p>
|
|
76
|
+
</div>
|
|
77
|
+
|
|
78
|
+
<div id="text-box" class="target-box" hidden></div>
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Set `box-sizing: border-box` when the overlay's outside edges should match the
|
|
82
|
+
measured box. Other CSS, including borders, padding, and child controls, can
|
|
83
|
+
style or extend the overlay.
|
|
84
|
+
|
|
85
|
+
When the box is shown, its `position` object exposes the active trigger, event,
|
|
86
|
+
query matches, target, and measured box. Relayed iframe events keep both the
|
|
87
|
+
inner event target and the iframe relay target available:
|
|
88
|
+
|
|
89
|
+
```js
|
|
90
|
+
toolbar.position.trigger; // element with position-query and position-events
|
|
91
|
+
toolbar.position.event.target; // original target, including inside an iframe
|
|
92
|
+
toolbar.position.event.relayTarget; // iframe element, when relayed
|
|
93
|
+
toolbar.position.element; // active matched element or selection range
|
|
94
|
+
toolbar.position.queryElements; // all query matches
|
|
95
|
+
toolbar.position.box.rect; // { top, right, bottom, left, width, height, x, y }
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Events relay from same-origin iframe documents through the iframe element, so a
|
|
99
|
+
position query element that contains the iframe can listen on its own event
|
|
100
|
+
path just as it would for content in the same document. Cross-origin iframe
|
|
101
|
+
contents remain subject to browser security boundaries.
|
|
102
|
+
|
|
103
|
+
For a text selection inside a same-origin iframe, listen to the relayed native
|
|
104
|
+
`selectionchange` event and query `$selection`:
|
|
105
|
+
|
|
106
|
+
```html
|
|
107
|
+
<div
|
|
108
|
+
position-events="selectionchange"
|
|
109
|
+
position-query="iframe $selection"
|
|
110
|
+
position-element="$top #selection-box"
|
|
111
|
+
position-box="text"></div>
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
The target box also receives a JavaScript `position` API when initialized:
|
|
115
|
+
|
|
116
|
+
```js
|
|
117
|
+
box.position.place(anchor, { box: "text" });
|
|
118
|
+
box.position.unplace();
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Drag elements
|
|
122
|
+
|
|
123
|
+
Add `draggable` to let a user move an element directly:
|
|
124
|
+
|
|
125
|
+
```html
|
|
126
|
+
<div draggable>Drag me</div>
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
For scoped move or clone operations, put the source query and drop query on a
|
|
130
|
+
shared container. A `clonable-query` takes precedence if both source queries
|
|
131
|
+
match:
|
|
132
|
+
|
|
133
|
+
```html
|
|
134
|
+
<section
|
|
135
|
+
draggable-query=".card[]"
|
|
136
|
+
clonable-query=".copy-card[]"
|
|
137
|
+
droppable-query=".board[]"
|
|
138
|
+
>
|
|
139
|
+
<div class="board">Drop zone</div>
|
|
140
|
+
<article class="card">Move this card</article>
|
|
141
|
+
<article class="copy-card">Clone this card</article>
|
|
142
|
+
</section>
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`draggable-query` moves the matching source; `clonable-query` leaves the source
|
|
146
|
+
in place and inserts a deep clone. If the pointer is not over a matching drop
|
|
147
|
+
target, the operation is canceled. Drop targets can be selected across
|
|
148
|
+
same-origin iframe documents using CoCreate query operators.
|
|
149
|
+
|
|
150
|
+
`draggable-value` and `clonable-value` let a source provide a custom drop value.
|
|
151
|
+
Position inserts an element value as an element and a string value as HTML. A
|
|
152
|
+
custom `draggable-value` is removed from its source after a successful drop;
|
|
153
|
+
`clonable-value` leaves its source in place.
|
|
154
|
+
|
|
155
|
+
## Auto-scroll while dragging
|
|
156
|
+
|
|
157
|
+
Active drags automatically scroll when the pointer enters the visible top or
|
|
158
|
+
bottom edge of a scrollable container. No additional attributes are required.
|
|
159
|
+
The auto-scroll module loads on the first confirmed drag, and continues
|
|
160
|
+
scrolling while the pointer stays at the edge, even without further movement.
|
|
161
|
+
|
|
162
|
+
The edge zone is up to 48 pixels deep. Speed increases toward the edge, up to
|
|
163
|
+
800 CSS pixels per second. Nested containers scroll from the inside outward;
|
|
164
|
+
an outer container takes over at an inner container's limit when the pointer
|
|
165
|
+
is also near its edge. Viewport scrolling and same-origin iframe drop
|
|
166
|
+
containers use the same behavior.
|
|
167
|
+
|
|
168
|
+
Drop references, insertion markers, and drag previews refresh after scrolling.
|
|
169
|
+
Scrolling stops when the pointer leaves the edge, the drag ends or is canceled,
|
|
170
|
+
the window loses focus, or the dragged element is removed.
|
|
171
|
+
|
|
172
|
+
## Snap to containers and inspect insertion points
|
|
173
|
+
|
|
174
|
+
Use `snappable-query` to select snap destinations independently of
|
|
175
|
+
`droppable-query`:
|
|
176
|
+
|
|
177
|
+
```html
|
|
178
|
+
<div draggable snappable-query="$top .snap-area[]">Drag into a snap area</div>
|
|
179
|
+
<div class="snap-area"></div>
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
After a successful snap, the moved element receives the `snapped` attribute.
|
|
183
|
+
For drag-and-drop insertion feedback, add `position-reference` to the source
|
|
184
|
+
scope. Position emits `element-position-reference` with a `detail.reference`
|
|
185
|
+
object containing the hovered element, container, insertion position, pointer
|
|
186
|
+
coordinates, and owning document. The active drop container temporarily
|
|
187
|
+
receives `droppable`; a `position-marker` preview shows the insertion point.
|
|
188
|
+
|
|
189
|
+
During dragging, Position applies `position-moving` to a moved element or
|
|
190
|
+
`position-cloning` to a clone source. The pointer-following preview uses
|
|
191
|
+
`position-moving-preview`. These classes and the marker can be styled by the
|
|
192
|
+
application; default styles are included in the package CSS.
|
|
193
|
+
|
|
194
|
+
The current hovered node is also exposed as `document.hoveredElement` and
|
|
195
|
+
`document.documentElement.hoveredElement`. For same-origin iframe targets, the
|
|
196
|
+
frame document exposes its inner hovered node, while the parent document
|
|
197
|
+
continues to expose the iframe element.
|
|
198
|
+
|
|
199
|
+
## Links
|
|
200
|
+
|
|
201
|
+
- [Documentation and demo](https://CoCreateJS.com/docs/position)
|
|
202
|
+
- [Changelog](https://github.com/CoCreateJS/position/blob/main/CHANGELOG.md)
|
|
203
|
+
- [Issues](https://github.com/CoCreateJS/position/issues)
|
|
204
|
+
- [Contributing](https://github.com/CoCreateJS/position/blob/main/CONTRIBUTING.md)
|
|
205
|
+
- [MIT license](https://github.com/CoCreateJS/position/blob/main/LICENSE)
|
|
206
|
+
|
|
207
|
+
## About
|
|
208
|
+
|
|
209
|
+
CoCreate Position is maintained by [CoCreate](https://CoCreateJS.com). Questions
|
|
210
|
+
can be sent to [develop@CoCreateJS.com](mailto:develop@CoCreateJS.com).
|