Add timing modifiers (#795)

CHANGELOG.md

@@ -4,31 +4,9 @@ Each tagged version of Datastar is accompanied by a release note. Read the [rele
 
 # WIP Release Notes
 
-## v1.0.0-beta.10
+## v1.0.0-beta.11
 
 ### Added
 
-- Added a `retries-failed` event type that is dispatched when the SSE plugin fails after retrying ([#785](https://github.com/starfederation/datastar/issues/785)).
-
-### Changed
-
-- Updated Idiomorph to version [0.7.3](https://github.com/bigskysoftware/idiomorph/releases/tag/v0.7.3).
-- Renamed the `data-intersects` attribute to `data-on-intersect`.
-- Renamed the `data-on-signals-change` attribute to `data-on-signal-change`.
-- Classes used in `data-class-*` attributes now default to kebab-case ([#761](https://github.com/starfederation/datastar/issues/761)).
-- Events used in `data-on-*` attributes now default to kebab-case ([#761](https://github.com/starfederation/datastar/issues/761)).
-- The `datastar-sse` event is now dispatched on the element itself ([#761](https://github.com/starfederation/datastar/issues/761)).
-- The NPM package now also exports all plugins and bundles ([#742](https://github.com/starfederation/datastar/issues/742)).
-- Data attributes with plugin names in their prefix are no longer processed ([#771](https://github.com/starfederation/datastar/issues/771)).
-- The alias used in the aliased bundle has been renamed to `star` (`data-star-*`) ([#772](https://github.com/starfederation/datastar/issues/772)).
-
-### Fixed
-
-- Fixed the applying of plugins to give custom plugins a chance to load ([#740](https://github.com/starfederation/datastar/issues/740)).
-- Fixed a bug in which the indicator signal was not being reset when the element it was on was removed from the DOM ([#749](https://github.com/starfederation/datastar/issues/749)).
-- Fixed a bug in which merging multiple targets was not working correctly ([#780](https://github.com/starfederation/datastar/issues/780)).
-
-### Removed
-
-- Removed the ability to use a key with the `data-persist` attribute.
-- Removed settling from SSE events, which has become redundant ([#764](https://github.com/starfederation/datastar/issues/764)).
+- Added the `__debounce` and `__throttle` modifiers to `data-on-intersect`.
+- Added the `__debounce` and `__throttle` modifiers to `data-on-signal-change`.

library/src/plugins/official/browser/attributes/onIntersect.ts

@@ -8,6 +8,7 @@ import {
   PluginType,
   Requirement,
 } from '../../../../engine/types'
+import { modifyTiming } from '../../../../utils/timing'
 
 const ONCE = 'once'
 const HALF = 'half'
@@ -19,7 +20,8 @@ export const OnIntersect: AttributePlugin = {
   keyReq: Requirement.Denied,
   mods: new Set([ONCE, HALF, FULL]),
   onLoad: ({ el, rawKey, mods, genRX }) => {
-    const callback = genRX()
+    const callback = modifyTiming(genRX(), mods)
+
     const options = { threshold: 0 }
     if (mods.has(FULL)) {
       options.threshold = 1

library/src/plugins/official/browser/attributes/onSignalChange.ts

@@ -11,6 +11,7 @@ import {
   Requirement,
 } from '../../../../engine/types'
 import { modifyCasing } from '../../../../utils/text'
+import { modifyTiming } from '../../../../utils/timing'
 import { effect, type Signal } from '../../../../vendored/preact-core'
 
 export const OnSignalChange: AttributePlugin = {
@@ -18,7 +19,7 @@ export const OnSignalChange: AttributePlugin = {
   name: 'onSignalChange',
   valReq: Requirement.Must,
   onLoad: ({ key, mods, signals, genRX }) => {
-    const callback = genRX()
+    const callback = modifyTiming(genRX(), mods)
 
     if (key === '') {
       const signalFn = (event: CustomEvent<DatastarSignalEvent>) =>

sdk/go/consts.go

@@ -7,8 +7,8 @@ import "time"
 const (
     DatastarKey = "datastar"
     Version                   = "1.0.0-beta.10"
-    VersionClientByteSize     = 39853
-    VersionClientByteSizeGzip = 14855
+    VersionClientByteSize     = 39865
+    VersionClientByteSizeGzip = 14861
 
     //region Default durations
 

site/static/md/reference/attribute_plugins.md

@@ -527,20 +527,29 @@ Runs an expression when the element intersects with the viewport.
 
 #### Modifiers
 
-Modifiers allow you to modify the element intersection behavior.
+Modifiers allow you to modify the element intersection behavior and the timing of the event listener.
 
 - `__once` - Only triggers the event once.
 - `__half` - Triggers when half of the element is visible.
 - `__full` - Triggers when the full element is visible.
+- `__debounce` - Debounce the event listener.
+- `.500ms` - Debounce for 500 milliseconds.
+- `.1s` - Debounce for 1 second.
+- `.leading` - Debounce with leading edge.
+- `.notrail` - Debounce without trailing edge.
+- `__throttle` - Throttle the event listener.
+- `.500ms` - Throttle for 500 milliseconds.
+- `.1s` - Throttle for 1 second.
+- `.noleading` - Throttle without leading edge.
+- `.trail` - Throttle with trailing edge.
 
 ```html
-<div data-on-intersect__once="$intersected = true"></div>
+<div data-on-intersect__once__full="$fullyIntersected = true"></div>
 ```
 
 ### `data-on-interval`
 
-Runs an expression at a regular interval. The interval duration defaults to 1 second and can be modified using the
-`__duration` modifier.
+Runs an expression at a regular interval. The interval duration defaults to 1 second and can be modified using the `__duration` modifier.
 
 ```html
 <div data-on-interval="$count++"></div>
@@ -620,6 +629,25 @@ A key can be provided to only trigger the event when a specific signal changes.
 <div data-on-signal-change-foo="$fooCount++"></div>
 ```
 
+#### Modifiers
+
+Modifiers allow you to modify the timing of the event listener.
+
+- `__debounce` - Debounce the event listener.
+- `.500ms` - Debounce for 500 milliseconds.
+- `.1s` - Debounce for 1 second.
+- `.leading` - Debounce with leading edge.
+- `.notrail` - Debounce without trailing edge.
+- `__throttle` - Throttle the event listener.
+- `.500ms` - Throttle for 500 milliseconds.
+- `.1s` - Throttle for 1 second.
+- `.noleading` - Throttle without leading edge.
+- `.trail` - Throttle with trailing edge.
+
+```html
+<div data-on-signal-change__debounce.100ms="$count++"></div>
+```
+
 ### `data-persist`
 
 Persists signals in Local Storage. This is useful for storing values between page loads.