ForesightJS v4.0 - Official Framework Packages

[spaansba]

The goal of v4.0 is to make ForesightJS a lot easier to use with popular frameworks. Until now, the docs handed you premade hooks, composables and directives to copy into your own project. v4 replaces all of that with two official wrapper packages: @foresightjs/react and @foresightjs/vue. Install one, delete your copied files, and you're done.

To make reactive bindings possible, the core element data model was reworked into immutable state snapshots with a subscription model. The same primitives the wrapper packages are built on, and the same ones you can use to build a binding for your own framework (Angular, Svelte, Solid, …).

Upgrading from v3.5? Follow the migration guide. The v3.5 docs stay available via the version dropdown.

js.foresight v4.0.0

• Immutable element state. ForesightElementData is now ForesightElementState: a flat, immutable snapshot whose reference is replaced (never mutated) on every change, so it plugs straight into any reactivity system.
• New register() return value. Besides the element state it now returns unregister, subscribe and getSnapshot
• isTouchDevice is gone from the result; touch devices are handled internally by the touchDeviceStrategy global setting.
• New updateElementOptions(). Change the options of an already-registered element in place. See registration options.
• New enabled element option. Keep an element registered but excluded from prediction.
• Detached elements are parked, not unregistered. Removing an element from the DOM no longer
  unregisters it; it's parked (isParked: true) and resumes automatically when it reconnects.
• Leaner event system. The elementDataUpdated, elementOptionsUpdated and elementReactivated events are removed in favor of the subscriber pattern; the remaining events carry the snapshot in a state field.
• Removed deprecated APIs. The debug global setting (use
  js.foresight-devtools) and unregisterOnCallback (use reactivateAfter) are gone.
• Performance. Pre-allocated trajectory event objects, faster trajectory calculations, error handling around subscriber listeners and extra isConnected guards.

Devtools — js.foresight-devtools v2.0.0

• Updated for the v4 core state model and event system.
• New nested show options to toggle each visualization individually: controlPanel, nameTags, elementOverlays, mouseTrajectory and scrollTrajectory.
• Better Elements tab. Elements are grouped into Active/Inactive with collapsible sections, and
  inactive elements carry reason badges (disabled, parked, limited, fired) explaining why.
• Full docs: Development Tools.

New — @foresightjs/react

Official React (18+) bindings, with dedicated React docs including Next.js and [React Router (https://foresightjs.com/docs/react/react-router) guides.

• useForesight — register a single element and get
  its live state plus a callback ref to bind it.
• useForesights — register a dynamic list of
  elements from one hook call.
• useForesightEvent — subscribe to a
  ForesightManager event for the lifetime of the component.
• Options like hitSlop and enabled are reactive — change a prop and the registration updates.

New — @foresightjs/vue

Official Vue 3 (3.5+) bindings, with [dedicated Vue docs (https://foresightjs.com/docs/vue/installation).

• v-foresight — directive to register an element with a callback or full options object.
• useForesight — register a single element and get reactive refs for its state.
• useForesights — register a dynamic list of elements from a single composable.
• useForesightEvent — subscribe to a ForesightManager event for the lifetime of the calling scope.

Docs

• The docs are now framework-aware: pick React or Vue from the dropdown at the top of the sidebar to get the entire documentation tailored to your framework.
• New Other Frameworks page showing how to build your own thin binding with the subscribe/getSnapshot pattern (Angular, Svelte, Solid examples). If you build one, sharing it is highly appreciated!
• Migration guides for core, React and Vue.

---

This discussion was created from the release ForesightJS v4.0 - Official Framework Packages.