diff --git a/CHANGELOG.md b/CHANGELOG.md index 17632497..2ced8e6f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,20 @@ # Changelog +## v1.46.0 + +_22 jan 2026_ + +- Improved Announcer on Comcast devices +- Added new `afterEach` router hook +- Added router option to dynamically disable `back`-key handling by the router +- Added `this.$debounce`-method +- Added automatic inspector data items (`$componentType`, `$hasFocus` and `$isTransitioning`) +- Added functionality to auto size the holder node of a Component when the wrapper Element has dimensions +- Bumped Lightning renderer to v2.20.4 with correct handling of failed textures + ## v1.45.2 -_29 dec 2026_ +_13 jan 2026_ - Updated renderer to v2.20.2 diff --git a/docs/components/utility_methods.md b/docs/components/utility_methods.md index bc5e21ce..cef9d4a8 100644 --- a/docs/components/utility_methods.md +++ b/docs/components/utility_methods.md @@ -428,3 +428,73 @@ export default Blits.Component('MyComponent', { } }) ``` + +## Debounce + +Debouncing is a technique to limit the rate at which a function executes. This is particularly useful when navigating through lists or handling rapid user input, where you want to execute a method only after the user has stopped the action for a specified delay. + +Similar to timeouts and intervals, debounced functions can cause memory leaks if not properly cleaned up. Blits provides built-in debounce methods that automatically handle cleanup when a component is destroyed. + +### $debounce + +The `this.$debounce()`-method creates a debounced function that delays execution until after a specified delay has passed since the last invocation. If the same name is debounced again before the delay completes, the previous debounce is cancelled and a new one is created. + +The first argument is a `name` (string) that uniquely identifies this debounce instance within the component. The second argument is the `callback` function to execute. The third argument is the `delay` in milliseconds. Additional arguments can be passed and will be forwarded to the callback function. + +The method returns a `debounce id`, which can be used to manually clear the debounce. + +**Key Features:** +- **Name-based**: Each debounce is identified by a unique name (unique per component instance) +- **Automatic replacement**: Calling `$debounce` with the same name replaces the previous debounce +- **Memory efficient**: Only stores debounce IDs internally, function is captured in closure +- **Automatic cleanup**: All debounces are cleared when component is destroyed + +### $clearDebounce + +The `this.$clearDebounce()`-method clears a specific debounce by its name. This prevents the debounced function from executing. + +### $clearDebounces + +The `this.$clearDebounces()`-method clears all debounces registered on the component in one go. This method is automatically called when destroying a Component, preventing memory leaks due to dangling debounce timers. + +```js +export default Blits.Component('ListComponent', { + state() { + return { + items: [], + currentIndex: 0 + } + }, + input: { + down() { + // Debounce navigation - only load data after 300ms of no navigation + this.$debounce('navigate', () => { + this.loadCurrentItem() + }, 300) + }, + up() { + // Different debounce for different operation + this.$debounce('update', () => { + this.updateUI() + }, 200) + } + }, + methods: { + loadCurrentItem() { + // This will only execute after 300ms of no navigation + const item = this.items[this.currentIndex] + // ... load item data + }, + updateUI() { + // This will only execute after 200ms of no update calls + // ... update UI + } + }, + hooks: { + unfocus() { + // Optionally clear all debounces when component loses focus + this.$clearDebounces() + } + } +}) +``` \ No newline at end of file diff --git a/docs/essentials/element_attributes.md b/docs/essentials/element_attributes.md index d5108f9c..58b0a6cf 100644 --- a/docs/essentials/element_attributes.md +++ b/docs/essentials/element_attributes.md @@ -193,3 +193,21 @@ By default contents inside an Element (i.e. child Elements) will overflow the bo In order to contain / cut off the content inside an Element's `w` and `h`, you can add the `clipping="true"`-attribute. Setting `clipping` to `false` restores the default behaviour of content overflowing. Alternatively you can also use the `overflow`-attribute (and pass it `true` or `false`), which works similar to clipping just mapped inversly (i.e. `overflow="false"` ensures content that surpasses the parent dimensions is clipped-off). + +## Inspector Data + +The `inspector-data` attribute allows you to attach custom metadata to elements and components for debugging and automated testing. This data is visible in the Lightning inspector tool when enabled. + +```xml + +