v0.1.5 - May the force be with you!

Happy Halloween! 👻 🧟 🕷️ 🦸 🎃

Change Summary

• Prefix any attribute with a lightsaber !, or wrap a value with force(), to force updates, bypassing equality checks. by @trusktr in #3
• Fix example in readme by @floriangosse in #2

New Contributors

• @floriangosse made their first contribution in #2

Full Changelog: v0.1.4...v0.1.5

---

🎯 New Feature: Force Update Control

v0.1.5 adds control over when DOM updates happen. You can now force updates
even when values haven't changed using either the ! prefix syntax or the new
force() function. This is especially useful for performance optimization with
large arrays or triggering side effects.

Recommendation: For most use cases, stick with nimble-html's default
equality checking. Use force updates sparingly and only when you have a specific
need.

Two Ways to Force Updates

1. Lightsaber Syntax (!) — Recommended

Prefix any attribute binding with ! to force updates. This new syntax is not
compatible with Lit tooling (f.e. type checkers), see the force() function
below for an alternative that works with Lit tooling.

import {html} from 'nimble-html'

const template = () => html`
  <!-- Regular attribute -->
  <div !class=${value}></div>

  <!-- Boolean attribute -->
  <input !?disabled=${true} />

  <!-- JS property -->
  <input !.value=${value} />

  <!-- Event handler -->
  <button !@click=${handler}>Click</button>
`

2. The force() Function

Wrap any interpolated value with the new force() export:

import {html, force} from 'nimble-html'

const template = () => html`
  <div class=${force(value)}></div>
  <div>${force('text content')}</div>
  <input .value=${force(value)} />
`

Note: Only force() works with text content interpolations like <p>${force(value)}</p>. The ! syntax only applies to element attributes, properties, and events.

When to Use Force Updates

This feature is valuable for:

• Performance-sensitive updates: Mutate arrays in place and force re-processing instead of creating new array references with copied primitive values
• Stateful components: Trigger side effects every time a value is set, even if unchanged (e.g., playing a sound on each button press)
• Forcing DOM updates: Trigger MutationObserver callbacks or reset externally modified state
• Third-party integration: When external libraries require explicit updates

Important Behaviors

• Isolation: Force behavior is isolated to specific attributes—it doesn't affect other attributes in the same template
• Consistency enforcement: Once you use force() at a specific interpolation site, you must continue using it. Mixing forced and non-forced values at the same site throws an error
• Performance warning: Overuse can hurt performance since it bypasses the built-in optimization. Use only when necessary

🔄 Breaking Changes

None — This release is fully backward compatible.