@cocreate/events 1.34.0 → 2.0.0
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 +317 -274
- package/CONTRIBUTING.md +6 -6
- package/README.md +485 -46
- package/demo/click.html +1 -1
- package/demo/hover.html +1 -1
- package/demo/index.html +1 -1
- package/demo/observer.html +1 -1
- package/demo/selected.html +2 -2
- package/demo/set-value.html +1 -1
- package/docs/index.html +7 -7
- package/package.json +8 -8
- package/src/index.js +355 -61
- package/test/method-invocation.test.cjs +465 -0
package/CONTRIBUTING.md
CHANGED
|
@@ -1,19 +1,19 @@
|
|
|
1
1
|
# Contributing to CoCreate-toggle
|
|
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/toggle/graphs/contributors).
|
|
4
|
+
You're encouraged to submit [pull requests](https://github.com/CoCreateJS/toggle/pulls),
|
|
5
|
+
[propose features and discuss issues](https://github.com/CoCreateJS/toggle/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/toggle) and check out your copy.
|
|
12
12
|
|
|
13
13
|
```
|
|
14
14
|
git toggle https://github.com/contributor/CoCreate-toggle.git
|
|
15
15
|
cd CoCreate-toggle
|
|
16
|
-
git remote add upstream https://github.com/
|
|
16
|
+
git remote add upstream https://github.com/CoCreateJS/toggle.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/toggle](https://github.com/CoCreateJS/toggle) 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,91 +1,530 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @cocreate/events
|
|
2
|
+
|
|
3
|
+
A declarative, event-driven DOM engine configured entirely through HTML5 attributes. Bind any DOM event, observer, or custom event to one or many target elements, then assign values to their properties, attributes, styles, classes, or markup without writing JavaScript. Every binding follows a single, predictable grammar: an **event prefix** declares when to run, **dash options** declare how and where to run, and **dot assignments** declare what to change.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Documentation
|
|
8
|
+
|
|
9
|
+
For a complete guide, live playground, and working demos refer to the [documentation](https://CoCreateJS.com/docs/events).
|
|
10
|
+
|
|
11
|
+
## Table of Contents
|
|
12
|
+
|
|
13
|
+
* [Features](#features)
|
|
14
|
+
* [Installation](#installation)
|
|
15
|
+
* [Usage](#usage)
|
|
16
|
+
* [How it Works](#how-it-works)
|
|
17
|
+
* [Anatomy of a Binding](#anatomy-of-a-binding)
|
|
18
|
+
* [Event Prefixes](#event-prefixes)
|
|
19
|
+
* [Assignment Targets](#assignment-targets)
|
|
20
|
+
* [Value Semantics](#value-semantics)
|
|
21
|
+
* [Targeting Elements](#targeting-elements)
|
|
22
|
+
* [Options Reference](#options-reference)
|
|
23
|
+
* [Observers](#observers)
|
|
24
|
+
* [Groups](#groups)
|
|
25
|
+
* [Custom Events](#custom-events)
|
|
26
|
+
* [Actions Integration](#actions-integration)
|
|
27
|
+
* [Behavior Notes](#behavior-notes)
|
|
28
|
+
* [Announcements](#announcements)
|
|
29
|
+
* [Roadmap](#roadmap)
|
|
30
|
+
* [How to Contribute](#how-to-contribute)
|
|
31
|
+
* [About](#about)
|
|
32
|
+
* [License](#license)
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Features
|
|
37
|
+
|
|
38
|
+
* **Attribute-Driven Bindings:** Wire clicks, hovers, inputs, focus, mutations, resizes, and intersections without writing JavaScript.
|
|
39
|
+
* **Universal Assignment:** Set any DOM property, HTML attribute, style declaration, class, or adjacent markup on a target element.
|
|
40
|
+
* **Multi-Target Dispatch:** A single event can update many elements resolved through relational selectors such as `$parent`, `$next`, `$closest`, and `$document`.
|
|
41
|
+
* **Value Rotation:** Comma separated values cycle on each trigger, producing toggles, tri-states, and round-robin behavior from a single attribute.
|
|
42
|
+
* **Grouped Selection:** `-group` links elements so that activating one deactivates its peers, giving tabs, accordions, and radio behavior for free.
|
|
43
|
+
* **Observer Support:** Mutation, intersection, and resize observers are declared with the same grammar as ordinary DOM events.
|
|
44
|
+
* **Custom Events:** Register application-specific event names and drive them from markup or from the Actions pipeline.
|
|
45
|
+
* **Timing Controls:** Debounce, delay, repeat, gate, and one-shot behavior via `-set-timeout`, `-set-interval`, `-on`, and `-once`.
|
|
46
|
+
* **Actions Integration:** Every prefix is registered as an action, so bindings can be chained and sequenced with other CoCreate modules.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Installation
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npm install @cocreate/events
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
yarn add @cocreate/events
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### CDN
|
|
61
|
+
|
|
62
|
+
```html
|
|
63
|
+
<script src="https://cdn.CoCreateJS.com/events/latest/CoCreate-events.min.js"></script>
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Usage
|
|
69
|
+
|
|
70
|
+
### Toggle an Attribute
|
|
71
|
+
|
|
72
|
+
```html
|
|
73
|
+
<button toggle-query="#panel" toggle.hidden="true,false">Toggle panel</button>
|
|
74
|
+
|
|
75
|
+
<div id="panel">Panel content</div>
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Set a Property on Click
|
|
79
|
+
|
|
80
|
+
```html
|
|
81
|
+
<button click-query="$next" click.readonly="">Enable editing</button>
|
|
82
|
+
<textarea readonly></textarea>
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Copy a Value Between Elements
|
|
86
|
+
|
|
87
|
+
```html
|
|
88
|
+
<input input-query="$document #preview" input.value="$value" />
|
|
89
|
+
<span id="preview"></span>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Apply Styles and Classes
|
|
93
|
+
|
|
94
|
+
```html
|
|
95
|
+
<button
|
|
96
|
+
click-query="#card"
|
|
97
|
+
click.style="background:tomato,background:seagreen"
|
|
98
|
+
click.class="is-active"></button>
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Reveal on Hover
|
|
102
|
+
|
|
103
|
+
```html
|
|
104
|
+
<div hover-query=".tools" hover.hidden="">
|
|
105
|
+
<div class="tools" hidden>Tools</div>
|
|
106
|
+
</div>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### Insert Markup
|
|
110
|
+
|
|
111
|
+
```html
|
|
112
|
+
<textarea click-query="#output" click.insertAdjacentHTML="beforeend"></textarea>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
The inserted content is read from the source element's value.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## How it Works
|
|
120
|
+
|
|
121
|
+
1. On load the module registers a set of built-in event prefixes and scans the document for matching elements.
|
|
122
|
+
2. An element is initialized when it declares the bare prefix, a `-query`, or a `-group` attribute.
|
|
123
|
+
3. Listeners are attached for the DOM events mapped to that prefix, or for the events named in `-events`.
|
|
124
|
+
4. When the event fires, source elements are resolved: the element itself, or every member of its `-group`.
|
|
125
|
+
5. Timing options such as `-on`, `-set-timeout`, `-set-interval`, and `-once` are evaluated.
|
|
126
|
+
6. Target elements are resolved from `-query` using relational selectors.
|
|
127
|
+
7. Every `prefix.target` assignment on the source element is applied to each target element.
|
|
128
|
+
8. A `prefixEnd` event is dispatched on the element so that action chains can continue.
|
|
129
|
+
9. A `MutationObserver` initializes elements added to the DOM later, so dynamically rendered markup is bound automatically.
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## Anatomy of a Binding
|
|
134
|
+
|
|
135
|
+
Every binding is composed of three parts. The separator character determines the role of the attribute.
|
|
136
|
+
|
|
137
|
+
```html
|
|
138
|
+
<button
|
|
139
|
+
click-query="$document #chat-body"
|
|
140
|
+
click-once
|
|
141
|
+
click.scroll-to="bottom"></button>
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
| Part | Separator | Purpose | Example |
|
|
145
|
+
| ---- | --------- | ------- | ------- |
|
|
146
|
+
| Prefix | none | Declares the event that triggers the binding | `click` |
|
|
147
|
+
| Option | dash `-` | Configures how and where the binding runs | `click-query`, `click-once` |
|
|
148
|
+
| Assignment | dot `.` | Declares what is written to the target | `click.value`, `click.hidden` |
|
|
149
|
+
|
|
150
|
+
> Dash attributes are always configuration. Dot attributes are always assignments. Any attribute using a dash is ignored by the assignment engine, and vice versa.
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Event Prefixes
|
|
155
|
+
|
|
156
|
+
Each prefix listens to one or more native DOM events.
|
|
157
|
+
|
|
158
|
+
| Prefix | DOM Events | Typical Use |
|
|
159
|
+
| ------ | ---------- | ----------- |
|
|
160
|
+
| `click` | `click` | Buttons, links, menu items |
|
|
161
|
+
| `toggle` | `click` | Show/hide, on/off, rotating states |
|
|
162
|
+
| `selected` | `click` | Tabs and selection lists, usually with `-group` |
|
|
163
|
+
| `hover` | `mouseover`, `mouseout` | Reveal on hover, auto-reverting |
|
|
164
|
+
| `mouseover` | `mouseover` | Enter-only behavior |
|
|
165
|
+
| `mouseout` | `mouseout` | Leave-only behavior |
|
|
166
|
+
| `input` | `input` | Live binding as the user types |
|
|
167
|
+
| `change` | `change` | Commit on change, selects and checkboxes |
|
|
168
|
+
| `focus` | `focus` | Focus styling and hints |
|
|
169
|
+
| `blur` | `blur` | Validation and cleanup |
|
|
170
|
+
| `onload` | runs immediately | Initialization on parse or insertion |
|
|
171
|
+
| `observe` | `MutationObserver` | React to DOM changes |
|
|
172
|
+
| `intersection` | `IntersectionObserver` | Scroll reveals, lazy loading |
|
|
173
|
+
| `resize` | `ResizeObserver`, load | Responsive behavior |
|
|
174
|
+
| `localstorage` | runs immediately | Hydrate from stored state |
|
|
175
|
+
|
|
176
|
+
Override the events for any prefix with `-events`:
|
|
177
|
+
|
|
178
|
+
```html
|
|
179
|
+
<div click-events="dblclick, keyup" click-query="#panel" click.hidden=""></div>
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## Prefix Objects
|
|
185
|
+
|
|
186
|
+
The standalone prefix accepts a JSON object of assignments. Keys name the same
|
|
187
|
+
targets as dot bindings; use `$` for explicit JavaScript properties and methods:
|
|
188
|
+
|
|
189
|
+
```html
|
|
190
|
+
<input
|
|
191
|
+
input-query="$document #preview"
|
|
192
|
+
input='{"$textContent": "$value"}' />
|
|
193
|
+
<span id="preview"></span>
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
The object is read from the raw attribute value. Its keys are not executed as
|
|
197
|
+
AST operators on the source element. Each value is evaluated through AST when
|
|
198
|
+
its assignment executes, using the source element as `$this` and the value
|
|
199
|
+
source for `$value`.
|
|
200
|
+
|
|
201
|
+
Assignments execute in DOM attribute order. Object entries expand at the
|
|
202
|
+
position of the prefix attribute, in JavaScript object enumeration order.
|
|
203
|
+
Earlier dotted attributes run before them; later dotted attributes run after
|
|
204
|
+
them. Repeated targets are preserved and run sequentially. For example:
|
|
205
|
+
|
|
206
|
+
```html
|
|
207
|
+
<button
|
|
208
|
+
click-query="$document #preview"
|
|
209
|
+
click.$record="before"
|
|
210
|
+
click='{"$record": "inside", "$finish": "next"}'
|
|
211
|
+
click.$record="after">Run</button>
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Both forms use the existing assignment handlers, including value rotation.
|
|
215
|
+
Arrays retain their existing rotation behavior. An empty prefix remains an
|
|
216
|
+
initialization marker. Object keys retain their casing. Prefix JSON must be
|
|
217
|
+
valid JSON; malformed object JSON throws during parsing.
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## Assignment Targets
|
|
222
|
+
|
|
223
|
+
The name after the dot determines what is written.
|
|
224
|
+
|
|
225
|
+
| Assignment | Behavior |
|
|
226
|
+
| ---------- | -------- |
|
|
227
|
+
| `prefix.value` | Uses `setValue()` when available so bound modules receive an `input` event, otherwise sets `.value` |
|
|
228
|
+
| `prefix.style` | Applies `property:value` declarations, removing the previous declaration when rotating |
|
|
229
|
+
| `prefix.class` | Adds and removes class names, supporting multiple classes per value |
|
|
230
|
+
| `prefix.insertAdjacentHTML` | Inserts the source value at the given position, integrating with CoCreate rich text when inside `[contenteditable]` |
|
|
231
|
+
| `prefix.insertAdjacentText` | Same as above, as plain text |
|
|
232
|
+
| `prefix.<property>` | Any existing DOM property, for example `hidden`, `readonly`, `disabled`, `checked`, `textContent` |
|
|
233
|
+
| `prefix.$<member>` | Always targets a JavaScript property: invokes an existing function or assigns the resolved value, creating the property if needed; use `focus.$focus="$undefined"` for an optional argument |
|
|
234
|
+
| `prefix.<attribute>` | Any attribute when no matching property exists, for example `click.data-state` or `click.aria-expanded` |
|
|
235
|
+
|
|
236
|
+
Property and method names in dot bindings are matched without case sensitivity,
|
|
237
|
+
including inherited members: `click.textcontent` resolves to `textContent`, and
|
|
238
|
+
`click.$custommethod` resolves to `customMethod`. Members must have unique names
|
|
239
|
+
ignoring case; ambiguous bindings throw a `TypeError`. A leading `$` always
|
|
240
|
+
selects a JavaScript property: existing functions are called, other members are
|
|
241
|
+
assigned, and missing members are created using the name after `$`. Ordinary
|
|
242
|
+
bindings with no matching property continue to write an HTML attribute.
|
|
243
|
+
|
|
244
|
+
Valid positions for the insert assignments are `beforebegin`, `afterbegin`, `beforeend`, and `afterend`.
|
|
245
|
+
|
|
246
|
+
```html
|
|
247
|
+
<button click-query="#box" click.aria-expanded="true,false">Expand</button>
|
|
248
|
+
```
|
|
2
249
|
|
|
3
|
-
|
|
250
|
+
---
|
|
4
251
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
252
|
+
## Value Semantics
|
|
11
253
|
|
|
12
|
-
|
|
254
|
+
### Static values
|
|
13
255
|
|
|
14
|
-
|
|
256
|
+
```html
|
|
257
|
+
<button click-query="#status" click.textContent="Saved">Save</button>
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
### Dynamic values
|
|
261
|
+
|
|
262
|
+
`$value` resolves to the source element's current value at trigger time.
|
|
263
|
+
|
|
264
|
+
```html
|
|
265
|
+
<select change-query="#preview" change.textContent="$value">
|
|
266
|
+
<option>One</option>
|
|
267
|
+
<option>Two</option>
|
|
268
|
+
</select>
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
### Rotation
|
|
272
|
+
|
|
273
|
+
Comma separated values rotate on each trigger. The engine reads the target's current value, finds its position in the list, and applies the next entry, wrapping at the end.
|
|
274
|
+
|
|
275
|
+
```html
|
|
276
|
+
<button click-query="#panel" click.data-state="open,half,closed"></button>
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
Sequence: `open` → `half` → `closed` → `open`.
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
## Targeting Elements
|
|
284
|
+
|
|
285
|
+
`-query` accepts standard CSS selectors, comma separated selector lists, and relational operators. When omitted, the source element is its own target.
|
|
286
|
+
|
|
287
|
+
| Operator | Resolves To |
|
|
288
|
+
| -------- | ----------- |
|
|
289
|
+
| `$document` | The owning document |
|
|
290
|
+
| `$parent` | The parent element |
|
|
291
|
+
| `$next` | The next element sibling |
|
|
292
|
+
| `$previous` | The previous element sibling |
|
|
293
|
+
| `$closest <selector>` | Nearest matching ancestor |
|
|
294
|
+
| `$frame` | The frame element of the current document |
|
|
295
|
+
| `$top` | The top-level document |
|
|
296
|
+
|
|
297
|
+
Operators compose with ordinary selectors, and a trailing `[]` selects **all** matches instead of the first.
|
|
298
|
+
|
|
299
|
+
```html
|
|
300
|
+
<span click-query="$closest .card .title[]" click.contentEditable="true"></span>
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
Selectors also support media suffixes, so a binding can be limited to a viewport range:
|
|
304
|
+
|
|
305
|
+
```html
|
|
306
|
+
<div click-query="#menu@xs@sm" click.hidden=""></div>
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
Available ranges are `xs`, `sm`, `md`, `lg`, and `xl`.
|
|
310
|
+
|
|
311
|
+
---
|
|
312
|
+
|
|
313
|
+
## Options Reference
|
|
314
|
+
|
|
315
|
+
| Option | Description |
|
|
316
|
+
| ------ | ----------- |
|
|
317
|
+
| `prefix-query` | Selector resolving the target elements |
|
|
318
|
+
| `prefix-element` | Selector resolving the element to move, or the value source for HTML/text insertion |
|
|
319
|
+
| `prefix-value` | Evaluated content for HTML/text insertion; takes precedence over `prefix-element` |
|
|
320
|
+
| `prefix-selector` | Selector observed by `observe`, keeping `-query` free for targets |
|
|
321
|
+
| `prefix-group` | Links elements so activating one deactivates its peers |
|
|
322
|
+
| `prefix-events` | Comma separated DOM events replacing the prefix defaults |
|
|
323
|
+
| `prefix-once` | Runs the binding a single time |
|
|
324
|
+
| `prefix-set-timeout` | Delay in milliseconds before running |
|
|
325
|
+
| `prefix-set-interval` | Repeat interval in milliseconds, `0` clears it |
|
|
326
|
+
| `prefix-on` | Waits for the named document event before running |
|
|
327
|
+
| `prefix-prevent-default` | Calls `preventDefault()` |
|
|
328
|
+
| `prefix-stop-propagation` | Calls `stopPropagation()` |
|
|
329
|
+
| `prefix-stop-immediate-propagation` | Calls `stopImmediatePropagation()` |
|
|
330
|
+
| `prefix-types` | Mutation types observed by `observe` |
|
|
331
|
+
| `prefix-attribute-filter` | Attribute names observed by `observe` |
|
|
332
|
+
| `prefix-root` | Root element selector for `intersection` |
|
|
333
|
+
| `prefix-root-margin` | Root margin for `intersection` |
|
|
334
|
+
| `prefix-threshold` | JSON array of thresholds for `intersection` |
|
|
335
|
+
| `prefix-trigger` | `visible`, `not-visible`, or `both` for `intersection` |
|
|
336
|
+
| `<event>-bubbles` | Listener option, named after the DOM event |
|
|
337
|
+
| `<event>-cancelable` | Listener option, named after the DOM event |
|
|
338
|
+
| `<event>-composed` | Listener option, named after the DOM event |
|
|
339
|
+
|
|
340
|
+
The module also writes status attributes you can bind against: `prefix-is-visible` during intersection changes and `prefix-if-value` carrying the observed width during resizes.
|
|
341
|
+
|
|
342
|
+
HTML/text insertion reads `prefix-value` when present (including an empty string), otherwise the first `prefix-element` match's `getValue()`, otherwise the event source's `getValue()`. A missing explicit source inserts nothing. These options do not change the separate `prefix.value` action.
|
|
343
|
+
|
|
344
|
+
```html
|
|
345
|
+
<input
|
|
346
|
+
type="checkbox"
|
|
347
|
+
input-query="$this:checked $closest form #selected-skills"
|
|
348
|
+
input-value="$query($this:checked $parent $next).getValue()"
|
|
349
|
+
input.insertAdjacentHTML="beforeend" />
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
`prefix.insertAdjacentElement` moves the first element matched by `prefix-element` to the requested position on the `prefix-query` target. Unlike the HTML/text variants, it passes the element itself rather than reading its value:
|
|
353
|
+
|
|
354
|
+
```html
|
|
355
|
+
<button
|
|
356
|
+
click-query="$document #preview-container"
|
|
357
|
+
click.insertAdjacentElement="beforeend"
|
|
358
|
+
click-element="$document #preview">
|
|
359
|
+
Show preview
|
|
360
|
+
</button>
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
---
|
|
364
|
+
|
|
365
|
+
## Observers
|
|
366
|
+
|
|
367
|
+
### Mutation
|
|
368
|
+
|
|
369
|
+
Use `-selector` for what to watch and `-query` for what to update.
|
|
370
|
+
|
|
371
|
+
```html
|
|
372
|
+
<div
|
|
373
|
+
observe-selector=".message"
|
|
374
|
+
observe.scroll-to="bottom"></div>
|
|
375
|
+
```
|
|
15
376
|
|
|
16
|
-
|
|
377
|
+
Watch attributes instead of insertions:
|
|
17
378
|
|
|
18
|
-
|
|
379
|
+
```html
|
|
380
|
+
<div
|
|
381
|
+
observe-selector="#editor"
|
|
382
|
+
observe-attribute-filter="data-state"
|
|
383
|
+
observe-query="#indicator"
|
|
384
|
+
observe.textContent="changed"></div>
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
### Intersection
|
|
19
388
|
|
|
20
389
|
```html
|
|
21
|
-
<
|
|
390
|
+
<img
|
|
391
|
+
intersection
|
|
392
|
+
intersection-threshold="[0.25]"
|
|
393
|
+
intersection-trigger="visible"
|
|
394
|
+
intersection-once
|
|
395
|
+
intersection.class="fade-in" />
|
|
22
396
|
```
|
|
23
397
|
|
|
398
|
+
### Resize
|
|
399
|
+
|
|
400
|
+
```html
|
|
401
|
+
<div resize resize-query="$parent" resize.data-width="$width"></div>
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
The observed width, including its `px` unit, is available as `$width` and can
|
|
405
|
+
be embedded in assignments:
|
|
406
|
+
|
|
407
|
+
```html
|
|
408
|
+
<aside
|
|
409
|
+
resize
|
|
410
|
+
resize-query="#page-topbar, .main-content"
|
|
411
|
+
resize.style="margin-right:$width"></aside>
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
---
|
|
415
|
+
|
|
416
|
+
## Groups
|
|
417
|
+
|
|
418
|
+
Elements sharing a `-group` value act as a single unit. When one is triggered it applies its assignments, while every other member is deactivated and has its assignments cleared. This produces tab bars, accordions, and radio groups without JavaScript.
|
|
419
|
+
|
|
24
420
|
```html
|
|
25
|
-
<
|
|
421
|
+
<nav>
|
|
422
|
+
<button selected-group="tabs" selected-query="#tab-1" selected.hidden="false" class="tab">One</button>
|
|
423
|
+
<button selected-group="tabs" selected-query="#tab-2" selected.hidden="false" class="tab">Two</button>
|
|
424
|
+
</nav>
|
|
425
|
+
|
|
426
|
+
<section id="tab-1">First</section>
|
|
427
|
+
<section id="tab-2" hidden>Second</section>
|
|
26
428
|
```
|
|
27
429
|
|
|
28
|
-
|
|
430
|
+
---
|
|
431
|
+
|
|
432
|
+
## Custom Events
|
|
29
433
|
|
|
30
|
-
|
|
31
|
-
|
|
434
|
+
Declare an application specific prefix with `event-name`. Multiple names are comma separated, and the prefix becomes available to markup and to the Actions pipeline.
|
|
435
|
+
|
|
436
|
+
```html
|
|
437
|
+
<div event-name="publish, archive"></div>
|
|
438
|
+
|
|
439
|
+
<button publish-query="#doc" publish.data-status="published">Publish</button>
|
|
32
440
|
```
|
|
33
441
|
|
|
34
|
-
|
|
442
|
+
Dispatch it from JavaScript or from an action chain:
|
|
443
|
+
|
|
444
|
+
```javascript
|
|
445
|
+
import events from "@cocreate/events";
|
|
35
446
|
|
|
36
|
-
|
|
37
|
-
$ yarn install @cocreate/toggle
|
|
447
|
+
events.init("publish", ["click"]);
|
|
38
448
|
```
|
|
39
449
|
|
|
40
|
-
|
|
450
|
+
---
|
|
41
451
|
|
|
42
|
-
|
|
43
|
-
- [Announcements](#announcements)
|
|
44
|
-
- [Roadmap](#roadmap)
|
|
45
|
-
- [How to Contribute](#how-to-contribute)
|
|
46
|
-
- [About](#about)
|
|
47
|
-
- [License](#license)
|
|
452
|
+
## Actions Integration
|
|
48
453
|
|
|
49
|
-
|
|
454
|
+
Every prefix is registered with `@cocreate/actions`, so bindings participate in sequenced action chains and can be invoked by name.
|
|
50
455
|
|
|
51
|
-
|
|
456
|
+
```html
|
|
457
|
+
<button actions="save, click">Save and continue</button>
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
When an element's `actions` attribute already includes the prefix, the direct DOM listener stands down and the action chain drives the binding, preventing duplicate execution.
|
|
461
|
+
|
|
462
|
+
Each run dispatches a `prefixEnd` event on the element, which is how the action pipeline knows the binding has completed and the next action may start.
|
|
463
|
+
|
|
464
|
+
Actions may also pass a selector as a parameter, which is used when the element has no `-query`:
|
|
465
|
+
|
|
466
|
+
```html
|
|
467
|
+
<button actions="click(#panel)"></button>
|
|
468
|
+
```
|
|
52
469
|
|
|
53
|
-
|
|
470
|
+
---
|
|
54
471
|
|
|
55
|
-
|
|
472
|
+
## Behavior Notes
|
|
56
473
|
|
|
57
|
-
|
|
474
|
+
* An element is only initialized if it declares the bare prefix, `-query`, or `-group`. An element carrying assignments alone is not bound.
|
|
475
|
+
* Rotation compares the target's current value as a string. Boolean DOM properties such as `hidden` and `readonly` report real booleans, so prefer explicit two-value rotations or attribute assignments when precise toggling matters.
|
|
476
|
+
* `hover` defers its revert until the pointer actually leaves the target, so bindings do not flicker while the cursor remains over the element.
|
|
477
|
+
* Assignments are applied in attribute order, allowing a single event to compose several changes on the same target.
|
|
478
|
+
* Dynamically inserted markup is initialized automatically, so templates and rendered lists behave the same as static markup.
|
|
58
479
|
|
|
59
|
-
|
|
480
|
+
---
|
|
60
481
|
|
|
61
|
-
|
|
482
|
+
## Announcements
|
|
62
483
|
|
|
63
|
-
|
|
484
|
+
All updates to this library are documented in our [CHANGELOG](https://github.com/CoCreateJS/events/blob/master/CHANGELOG.md) and [releases](https://github.com/CoCreateJS/events/releases). You may also subscribe to email for releases and breaking changes.
|
|
64
485
|
|
|
65
|
-
|
|
486
|
+
---
|
|
66
487
|
|
|
67
|
-
|
|
488
|
+
## Roadmap
|
|
68
489
|
|
|
69
|
-
|
|
490
|
+
Upcoming enhancements include:
|
|
70
491
|
|
|
71
|
-
|
|
492
|
+
* Development mode diagnostics for unrecognized and legacy attributes
|
|
493
|
+
* Typed value coercion for boolean properties
|
|
494
|
+
* Value source queries for assignments sourced from other elements
|
|
495
|
+
* Expanded observer configuration
|
|
496
|
+
* Devtools inspection of bindings attached to an element
|
|
72
497
|
|
|
73
|
-
|
|
498
|
+
If you are interested in the future direction of this project, please take a look at our open [issues](https://github.com/CoCreateJS/events/issues) and [pull requests](https://github.com/CoCreateJS/events/pulls). We would love to hear your feedback.
|
|
74
499
|
|
|
75
|
-
|
|
500
|
+
---
|
|
76
501
|
|
|
77
|
-
|
|
502
|
+
## How to Contribute
|
|
503
|
+
|
|
504
|
+
We encourage contribution to our libraries (you might even score some nifty swag), please see our [CONTRIBUTING](https://github.com/CoCreateJS/events/blob/master/CONTRIBUTING.md) guide for details.
|
|
505
|
+
|
|
506
|
+
We want this library to be community-driven, and CoCreate led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create [issues](https://github.com/CoCreateJS/events/issues) and [pull requests](https://github.com/CoCreateJS/events/pulls) or merely upvote or comment on existing issues or pull requests.
|
|
78
507
|
|
|
79
508
|
We appreciate your continued support, thank you!
|
|
80
509
|
|
|
81
|
-
|
|
510
|
+
---
|
|
511
|
+
|
|
512
|
+
## About
|
|
513
|
+
|
|
514
|
+
CoCreate-events is guided and supported by the CoCreate Developer Experience Team.
|
|
515
|
+
|
|
516
|
+
Please Email the Developer Experience Team [here](mailto:develop@CoCreateJS.com) in case of any queries.
|
|
517
|
+
|
|
518
|
+
CoCreate-events is maintained and funded by CoCreate. The names and logos for CoCreate are trademarks of CoCreate, LLC.
|
|
519
|
+
|
|
520
|
+
---
|
|
82
521
|
|
|
83
|
-
|
|
522
|
+
## License
|
|
84
523
|
|
|
85
524
|
This software is dual-licensed under the GNU Affero General Public License version 3 (AGPLv3) and a commercial license.
|
|
86
525
|
|
|
87
|
-
|
|
526
|
+
* **Open Source Use**: For open-source projects and non-commercial use, this software is available under the AGPLv3. The AGPLv3 allows you to freely use, modify, and distribute this software, provided that all modifications and derivative works are also licensed under the AGPLv3. For the full license text, see the [LICENSE file](https://github.com/CoCreateJS/events/blob/master/LICENSE).
|
|
88
527
|
|
|
89
|
-
|
|
528
|
+
* **Commercial Use**: For-profit companies and individuals intending to use this software for commercial purposes must obtain a commercial license. The commercial license is available when you sign up for an API key on our [website](https://CoCreateJS.com). This license permits proprietary use and modification of the software without the copyleft requirements of the AGPLv3. It is ideal for integrating this software into proprietary commercial products and applications.
|
|
90
529
|
|
|
91
530
|
If you have not purchased a commercial license and intend to use this software for commercial purposes, you are required to sign up for an API key on our website.
|
package/demo/click.html
CHANGED
|
@@ -86,6 +86,6 @@
|
|
|
86
86
|
|
|
87
87
|
<!-- <script src="../dist/CoCreate-events.js"></script> -->
|
|
88
88
|
<!-- <script src="../../../CoCreateJS/dist/CoCreate.js"></script> -->
|
|
89
|
-
<script src="https://
|
|
89
|
+
<script src="https://CoCreateJS.com/dist/CoCreate.js"></script>
|
|
90
90
|
</body>
|
|
91
91
|
</html>
|
package/demo/hover.html
CHANGED
package/demo/index.html
CHANGED
package/demo/observer.html
CHANGED
package/demo/selected.html
CHANGED
|
@@ -83,7 +83,7 @@
|
|
|
83
83
|
</div>
|
|
84
84
|
|
|
85
85
|
<!-- <script src="../dist/CoCreate-selected.js"></script> -->
|
|
86
|
-
<script src="https://
|
|
87
|
-
<!-- <script src="https://
|
|
86
|
+
<script src="https://CoCreateJS.com/dist/CoCreate.js"></script>
|
|
87
|
+
<!-- <script src="https://CoCreateJS.com/dist/CoCreate.js"></script> -->
|
|
88
88
|
</body>
|
|
89
89
|
</html>
|
package/demo/set-value.html
CHANGED