@open-pioneer/reactivity 4.8.0 → 4.9.0-dev.20261002130116

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/CHANGELOG.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # @open-pioneer/reactivity
2
2
 
3
+ ## 4.9.0-dev.20261002130116
4
+
3
5
  ## 4.8.0
4
6
 
5
7
  ### Minor Changes
@@ -30,7 +32,7 @@
30
32
  - 4e76893: Update Chakra UI to 3.34.0
31
33
  - 19b26dc: Allow configuration of dispatch timing in `useReactiveSnapshot` and `useReactive`.
32
34
 
33
- This is intended as a fix for https://github.com/open-pioneer/trails-core-packages/issues/125.
35
+ This is intended as a fix for https://github.com/open-pioneer/trails-core-packages/issues/125.
34
36
 
35
37
  ## 4.4.0
36
38
 
@@ -85,13 +87,13 @@
85
87
  ### Major Changes
86
88
 
87
89
  - 9477e54: Update dependencies
88
- - React 19
89
- - Vite 6
90
- - FormatJS 3
91
- - Open Pioneer Build Tools
92
- - ...
90
+ - React 19
91
+ - Vite 6
92
+ - FormatJS 3
93
+ - Open Pioneer Build Tools
94
+ - ...
93
95
 
94
- For more details, see https://github.com/open-pioneer/trails-core-packages/pull/81
96
+ For more details, see https://github.com/open-pioneer/trails-core-packages/pull/81
95
97
 
96
98
  ## 2.4.0
97
99
 
@@ -118,20 +120,20 @@
118
120
 
119
121
  - 5d3aafd: Initial release.
120
122
 
121
- You can use the hook `useReactiveSnapshot` to write React components that make use of the reactivity API of [@conterra/reactivity-core](https://www.npmjs.com/package/@conterra/reactivity-core).
122
- Quick example:
123
+ You can use the hook `useReactiveSnapshot` to write React components that make use of the reactivity API of [@conterra/reactivity-core](https://www.npmjs.com/package/@conterra/reactivity-core).
124
+ Quick example:
123
125
 
124
- ```tsx
125
- export function YourComponent({ model }) {
126
- // model is implemented using the reactivity API
127
- const fullName = useReactiveSnapshot(() => {
128
- return `${model.firstName} ${model.lastName}`;
129
- }, [model]);
126
+ ```tsx
127
+ export function YourComponent({ model }) {
128
+ // model is implemented using the reactivity API
129
+ const fullName = useReactiveSnapshot(() => {
130
+ return `${model.firstName} ${model.lastName}`;
131
+ }, [model]);
130
132
 
131
- // Name is automatically kept up-to-date.
132
- return <div>Hello {fullName}</div>;
133
- }
134
- ```
133
+ // Name is automatically kept up-to-date.
134
+ return <div>Hello {fullName}</div>;
135
+ }
136
+ ```
135
137
 
136
- The reactivity API is not directly used in any trails packages at this time.
137
- However, moving forward, most packages will use the reactivity API as _the_ common reactivity system.
138
+ The reactivity API is not directly used in any trails packages at this time.
139
+ However, moving forward, most packages will use the reactivity API as _the_ common reactivity system.
package/index.d.ts CHANGED
@@ -62,7 +62,7 @@ export declare function useComputed<T>(compute: () => T, deps: DependencyList):
62
62
  /**
63
63
  * Advanced options for `useReactiveSnapshot`.
64
64
  *
65
- * Note that objects should either be memoized (`useMemo` etc.) or constants (see {@link DISPATCH_SYNC})).
65
+ * Note that objects should either be memoized (`useMemo` etc.) or constants (see {@link DISPATCH_SYNC}).
66
66
  */
67
67
  export interface ReactiveHookOptions {
68
68
  dispatch?: DispatchType;
package/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sources":["index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\n\nimport {\n DispatchType,\n Reactive,\n ReadonlyReactive,\n computed,\n reactive,\n watchValue\n} from \"@conterra/reactivity-core\";\nimport {\n DependencyList,\n useCallback,\n useDebugValue,\n useMemo,\n useRef,\n useSyncExternalStore\n} from \"react\";\n\n/**\n * Creates a new signal with the initial value `undefined`.\n *\n * The initial value will only be applied on the very first call to this hook.\n * The same signal instance will be returned when this hook is called on the next render.\n * This is very similar (in concept) to React's builtin `useState` hook.\n *\n * @example\n *\n * ```jsx\n * function YourComponent() {\n * const mySignal = useReactive();\n * const someEventHandler = () => {\n * // Update the value after some event\n * mySignal.value = \"new value\";\n * };\n *\n * // Always returns the current value, re-renders if necessary.\n * const currentValue = useReactiveValue(mySignal);\n * }\n * ```\n */\nexport function useReactive<T>(): Reactive<T | undefined>;\n\n/**\n * Creates a new signal with the given initial value.\n *\n * @see {@link useReactive()}.\n */\nexport function useReactive<T>(initialValue: T): Reactive<T>;\n\nexport function useReactive<T>(initialValue?: T): Reactive<T | undefined> {\n // oxlint-disable-next-line react-hooks/exhaustive-deps\n return useMemo(() => reactive(initialValue), []);\n}\n\n/**\n * Creates a new computed signal that evaluates the given `compute` function.\n *\n * The hook returns the same signal for as long as `deps` remains the same.\n * When `deps` change, a new signal will be created.\n *\n * @example\n *\n * Defining a simple computed value in your react component:\n *\n * ```jsx\n * function MyComponent(props) {\n * // Creates a computed value based on the given function.\n * // The computed value will be re-created whenever one of the listed dependencies changes.\n * // While the computed value can track all its _reactive_ dependencies automatically (`.value` reads etc.)\n * // the reactive value itself used here might change (different props) - this cannot be detected automatically.\n * const computed = useComputed(() => props.someReactive.value * 2, [props.someReactive]);\n *\n * // Watches on `computed` and returns its current value.\n * const currentValue = useReactiveValue(computed);\n * }\n * ```\n *\n * > If the body of your compute function depends on non-reactive values (such as react props or state),\n * > list those values in the `deps` array.\n *\n * @see {@link useReactiveValue()}\n * @see {@link useReactiveSnapshot()}\n */\nexport function useComputed<T>(compute: () => T, deps: DependencyList): ReadonlyReactive<T> {\n const computeRef = useRef(compute);\n\n // oxlint-disable-next-line react/refs\n computeRef.current = compute;\n\n return useMemo(() => {\n // not really used, but computed must be recreated when this value changes\n void deps;\n\n return computed(() => computeRef.current());\n // oxlint-disable-next-line react/use-memo react-hooks/exhaustive-deps\n }, deps);\n}\n\n/**\n * Advanced options for `useReactiveSnapshot`.\n *\n * Note that objects should either be memoized (`useMemo` etc.) or constants (see {@link DISPATCH_SYNC})).\n */\nexport interface ReactiveHookOptions {\n dispatch?: DispatchType;\n}\n\n/**\n * Switches from async dispatch (the default) to sync dispatch.\n *\n * This is helpful when using reactive values for input fields, focus management or layout behavior.\n */\nexport const DISPATCH_SYNC: ReactiveHookOptions = Object.freeze({ dispatch: \"sync\" });\n\n/**\n * Watches the given reactive object and returns its current value.\n *\n * > NOTE: The return value of this hook should be considered read-only.\n *\n * > NOTE: The `options` parameter (if used) should be memoized or constant.\n *\n * @see {@link useComputed()}\n */\nexport function useReactiveValue<T>(\n reactive: ReadonlyReactive<T>,\n options?: ReactiveHookOptions\n): T {\n const getSnapshot = useCallback(() => {\n return reactive.peek();\n }, [reactive]);\n const subscribe = useCallback(\n (cb: () => void) => {\n const handle = watchValue(() => reactive.value, cb, {\n dispatch: options?.dispatch ?? \"async\"\n });\n return () => handle.destroy();\n },\n [reactive, options?.dispatch]\n );\n const value = useSyncExternalStore(subscribe, getSnapshot);\n useDebugValue(value);\n return value;\n}\n\n/**\n * Evaluates the `compute` function and returns its result.\n *\n * The body of the compute function is tracked: it\n * will be re-evaluated whenever its reactive dependencies change.\n * The outer react component will re-render whenever `compute` returns a new value.\n *\n * > NOTE: The return value of this hook should be considered read-only.\n *\n * > NOTE: The `options` parameter (if used) should be memoized or constant.\n *\n * @example\n *\n * Simple Example:\n *\n * ```jsx\n * import { useReactiveSnapshot } from \"@open-pioneer/reactivity\";\n *\n * // A reactive signal from anywhere (global data, props, ...).\n * const name = reactive(\"User\");\n *\n * function YourComponent() {\n * const nameSnapshot = useReactiveSnapshot(() => name.value);\n * // snapshot is automatically up to date\n * }\n * ```\n *\n * @example\n *\n * Multiple values, with props:\n *\n * ```jsx\n * import { useReactiveSnapshot } from \"@open-pioneer/reactivity\";\n *\n * function YourComponent({firstName, lastName}) {\n * // You can use complex expressions in your compute function,\n * // just like in a computed signal.\n * // React-dependencies used in the callback must be listed in the second argument,\n * // just like when using `useMemo()` or `useEffect`.\n * const snapshot = useReactiveSnapshot(() => {\n * return {\n * firstName: firstName.value,\n * lastName: lastName.value,\n * fullName: `${firstName.value} ${lastName.value}`\n * };\n * }, [firstName, lastName]);\n * // snapshot.firstName, snapshot.lastName, snapshot.fullName are available and up to date\n * }\n * ```\n *\n * @example\n *\n * Changing the default timing:\n *\n * ```jsx\n * import { useReactiveSnapshot, DISPATCH_SYNC } from \"@open-pioneer/reactivity\";\n *\n * function YourComponent(props) {\n * // DISPATCH_SYNC rerenders us faster than the default timing.\n * // This is useful for values used in input fields, in layout operations or focus management.\n * // See also https://github.com/open-pioneer/trails-core-packages/issues/125\n * const nameSnapshot = useReactiveSnapshot(() => props.reactiveModel.value, [props.reactiveModel], DISPATCH_SYNC);\n * }\n * ```\n *\n * @see\n * This hook is based on {@link useComputed()} and {@link useReactiveValue()}.\n */\nexport function useReactiveSnapshot<T>(\n compute: () => T,\n deps: DependencyList,\n options?: ReactiveHookOptions\n): T {\n // We create an internal computed value that executes the compute function;\n // this way the implementation of `compute` is automatically tracked.\n // getSnapshot and subscribe simply watch the current value of that computed value.\n // oxlint-disable-next-line react-hooks/exhaustive-deps\n const computedSnapshot = useComputed(compute, deps);\n const snapshot = useReactiveValue(computedSnapshot, options);\n useDebugValue(snapshot);\n return snapshot;\n}\n"],"names":["reactive"],"mappings":";;;AAmDO,SAAS,YAAe,YAAA,EAA2C;AAEtE,EAAA,OAAO,QAAQ,MAAM,QAAA,CAAS,YAAY,CAAA,EAAG,EAAE,CAAA;AACnD;AA+BO,SAAS,WAAA,CAAe,SAAkB,IAAA,EAA2C;AACxF,EAAA,MAAM,UAAA,GAAa,OAAO,OAAO,CAAA;AAGjC,EAAA,UAAA,CAAW,OAAA,GAAU,OAAA;AAErB,EAAA,OAAO,QAAQ,MAAM;AAIjB,IAAA,OAAO,QAAA,CAAS,MAAM,UAAA,CAAW,OAAA,EAAS,CAAA;AAAA,EAE9C,GAAG,IAAI,CAAA;AACX;AAgBO,MAAM,gBAAqC,MAAA,CAAO,MAAA,CAAO,EAAE,QAAA,EAAU,QAAQ;AAW7E,SAAS,gBAAA,CACZA,WACA,OAAA,EACC;AACD,EAAA,MAAM,WAAA,GAAc,YAAY,MAAM;AAClC,IAAA,OAAOA,UAAS,IAAA,EAAK;AAAA,EACzB,CAAA,EAAG,CAACA,SAAQ,CAAC,CAAA;AACb,EAAA,MAAM,SAAA,GAAY,WAAA;AAAA,IACd,CAAC,EAAA,KAAmB;AAChB,MAAA,MAAM,MAAA,GAAS,UAAA,CAAW,MAAMA,SAAAA,CAAS,OAAO,EAAA,EAAI;AAAA,QAChD,QAAA,EAAU,SAAS,QAAA,IAAY;AAAA,OAClC,CAAA;AACD,MAAA,OAAO,MAAM,OAAO,OAAA,EAAQ;AAAA,IAChC,CAAA;AAAA,IACA,CAACA,SAAAA,EAAU,OAAA,EAAS,QAAQ;AAAA,GAChC;AACA,EAAA,MAAM,KAAA,GAAQ,oBAAA,CAAqB,SAAA,EAAW,WAAW,CAAA;AACzD,EAAA,aAAA,CAAc,KAAK,CAAA;AACnB,EAAA,OAAO,KAAA;AACX;AAsEO,SAAS,mBAAA,CACZ,OAAA,EACA,IAAA,EACA,OAAA,EACC;AAKD,EAAA,MAAM,gBAAA,GAAmB,WAAA,CAAY,OAAA,EAAS,IAAI,CAAA;AAClD,EAAA,MAAM,QAAA,GAAW,gBAAA,CAAiB,gBAAA,EAAkB,OAAO,CAAA;AAC3D,EAAA,aAAA,CAAc,QAAQ,CAAA;AACtB,EAAA,OAAO,QAAA;AACX;;"}
1
+ {"version":3,"file":"index.js","sources":["index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\n\nimport {\n DispatchType,\n Reactive,\n ReadonlyReactive,\n computed,\n reactive,\n watchValue\n} from \"@conterra/reactivity-core\";\nimport {\n DependencyList,\n useCallback,\n useDebugValue,\n useMemo,\n useRef,\n useSyncExternalStore\n} from \"react\";\n\n/**\n * Creates a new signal with the initial value `undefined`.\n *\n * The initial value will only be applied on the very first call to this hook.\n * The same signal instance will be returned when this hook is called on the next render.\n * This is very similar (in concept) to React's builtin `useState` hook.\n *\n * @example\n *\n * ```jsx\n * function YourComponent() {\n * const mySignal = useReactive();\n * const someEventHandler = () => {\n * // Update the value after some event\n * mySignal.value = \"new value\";\n * };\n *\n * // Always returns the current value, re-renders if necessary.\n * const currentValue = useReactiveValue(mySignal);\n * }\n * ```\n */\nexport function useReactive<T>(): Reactive<T | undefined>;\n\n/**\n * Creates a new signal with the given initial value.\n *\n * @see {@link useReactive()}.\n */\nexport function useReactive<T>(initialValue: T): Reactive<T>;\n\nexport function useReactive<T>(initialValue?: T): Reactive<T | undefined> {\n // oxlint-disable-next-line react-hooks/exhaustive-deps\n return useMemo(() => reactive(initialValue), []);\n}\n\n/**\n * Creates a new computed signal that evaluates the given `compute` function.\n *\n * The hook returns the same signal for as long as `deps` remains the same.\n * When `deps` change, a new signal will be created.\n *\n * @example\n *\n * Defining a simple computed value in your react component:\n *\n * ```jsx\n * function MyComponent(props) {\n * // Creates a computed value based on the given function.\n * // The computed value will be re-created whenever one of the listed dependencies changes.\n * // While the computed value can track all its _reactive_ dependencies automatically (`.value` reads etc.)\n * // the reactive value itself used here might change (different props) - this cannot be detected automatically.\n * const computed = useComputed(() => props.someReactive.value * 2, [props.someReactive]);\n *\n * // Watches on `computed` and returns its current value.\n * const currentValue = useReactiveValue(computed);\n * }\n * ```\n *\n * > If the body of your compute function depends on non-reactive values (such as react props or state),\n * > list those values in the `deps` array.\n *\n * @see {@link useReactiveValue()}\n * @see {@link useReactiveSnapshot()}\n */\nexport function useComputed<T>(compute: () => T, deps: DependencyList): ReadonlyReactive<T> {\n const computeRef = useRef(compute);\n\n // oxlint-disable-next-line react/refs\n computeRef.current = compute;\n\n return useMemo(() => {\n // not really used, but computed must be recreated when this value changes\n void deps;\n\n return computed(() => computeRef.current());\n // oxlint-disable-next-line react/use-memo react-hooks/exhaustive-deps\n }, deps);\n}\n\n/**\n * Advanced options for `useReactiveSnapshot`.\n *\n * Note that objects should either be memoized (`useMemo` etc.) or constants (see {@link DISPATCH_SYNC}).\n */\nexport interface ReactiveHookOptions {\n dispatch?: DispatchType;\n}\n\n/**\n * Switches from async dispatch (the default) to sync dispatch.\n *\n * This is helpful when using reactive values for input fields, focus management or layout behavior.\n */\nexport const DISPATCH_SYNC: ReactiveHookOptions = Object.freeze({ dispatch: \"sync\" });\n\n/**\n * Watches the given reactive object and returns its current value.\n *\n * > NOTE: The return value of this hook should be considered read-only.\n *\n * > NOTE: The `options` parameter (if used) should be memoized or constant.\n *\n * @see {@link useComputed()}\n */\nexport function useReactiveValue<T>(\n reactive: ReadonlyReactive<T>,\n options?: ReactiveHookOptions\n): T {\n const getSnapshot = useCallback(() => {\n return reactive.peek();\n }, [reactive]);\n const subscribe = useCallback(\n (cb: () => void) => {\n const handle = watchValue(() => reactive.value, cb, {\n dispatch: options?.dispatch ?? \"async\"\n });\n return () => handle.destroy();\n },\n [reactive, options?.dispatch]\n );\n const value = useSyncExternalStore(subscribe, getSnapshot);\n useDebugValue(value);\n return value;\n}\n\n/**\n * Evaluates the `compute` function and returns its result.\n *\n * The body of the compute function is tracked: it\n * will be re-evaluated whenever its reactive dependencies change.\n * The outer react component will re-render whenever `compute` returns a new value.\n *\n * > NOTE: The return value of this hook should be considered read-only.\n *\n * > NOTE: The `options` parameter (if used) should be memoized or constant.\n *\n * @example\n *\n * Simple Example:\n *\n * ```jsx\n * import { useReactiveSnapshot } from \"@open-pioneer/reactivity\";\n *\n * // A reactive signal from anywhere (global data, props, ...).\n * const name = reactive(\"User\");\n *\n * function YourComponent() {\n * const nameSnapshot = useReactiveSnapshot(() => name.value);\n * // snapshot is automatically up to date\n * }\n * ```\n *\n * @example\n *\n * Multiple values, with props:\n *\n * ```jsx\n * import { useReactiveSnapshot } from \"@open-pioneer/reactivity\";\n *\n * function YourComponent({firstName, lastName}) {\n * // You can use complex expressions in your compute function,\n * // just like in a computed signal.\n * // React-dependencies used in the callback must be listed in the second argument,\n * // just like when using `useMemo()` or `useEffect`.\n * const snapshot = useReactiveSnapshot(() => {\n * return {\n * firstName: firstName.value,\n * lastName: lastName.value,\n * fullName: `${firstName.value} ${lastName.value}`\n * };\n * }, [firstName, lastName]);\n * // snapshot.firstName, snapshot.lastName, snapshot.fullName are available and up to date\n * }\n * ```\n *\n * @example\n *\n * Changing the default timing:\n *\n * ```jsx\n * import { useReactiveSnapshot, DISPATCH_SYNC } from \"@open-pioneer/reactivity\";\n *\n * function YourComponent(props) {\n * // DISPATCH_SYNC rerenders us faster than the default timing.\n * // This is useful for values used in input fields, in layout operations or focus management.\n * // See also https://github.com/open-pioneer/trails-core-packages/issues/125\n * const nameSnapshot = useReactiveSnapshot(() => props.reactiveModel.value, [props.reactiveModel], DISPATCH_SYNC);\n * }\n * ```\n *\n * @see\n * This hook is based on {@link useComputed()} and {@link useReactiveValue()}.\n */\nexport function useReactiveSnapshot<T>(\n compute: () => T,\n deps: DependencyList,\n options?: ReactiveHookOptions\n): T {\n // We create an internal computed value that executes the compute function;\n // this way the implementation of `compute` is automatically tracked.\n // getSnapshot and subscribe simply watch the current value of that computed value.\n // oxlint-disable-next-line react-hooks/exhaustive-deps\n const computedSnapshot = useComputed(compute, deps);\n const snapshot = useReactiveValue(computedSnapshot, options);\n useDebugValue(snapshot);\n return snapshot;\n}\n"],"names":["reactive"],"mappings":";;;AAmDO,SAAS,YAAe,YAAA,EAA2C;AAEtE,EAAA,OAAO,QAAQ,MAAM,QAAA,CAAS,YAAY,CAAA,EAAG,EAAE,CAAA;AACnD;AA+BO,SAAS,WAAA,CAAe,SAAkB,IAAA,EAA2C;AACxF,EAAA,MAAM,UAAA,GAAa,OAAO,OAAO,CAAA;AAGjC,EAAA,UAAA,CAAW,OAAA,GAAU,OAAA;AAErB,EAAA,OAAO,QAAQ,MAAM;AAIjB,IAAA,OAAO,QAAA,CAAS,MAAM,UAAA,CAAW,OAAA,EAAS,CAAA;AAAA,EAE9C,GAAG,IAAI,CAAA;AACX;AAgBO,MAAM,gBAAqC,MAAA,CAAO,MAAA,CAAO,EAAE,QAAA,EAAU,QAAQ;AAW7E,SAAS,gBAAA,CACZA,WACA,OAAA,EACC;AACD,EAAA,MAAM,WAAA,GAAc,YAAY,MAAM;AAClC,IAAA,OAAOA,UAAS,IAAA,EAAK;AAAA,EACzB,CAAA,EAAG,CAACA,SAAQ,CAAC,CAAA;AACb,EAAA,MAAM,SAAA,GAAY,WAAA;AAAA,IACd,CAAC,EAAA,KAAmB;AAChB,MAAA,MAAM,MAAA,GAAS,UAAA,CAAW,MAAMA,SAAAA,CAAS,OAAO,EAAA,EAAI;AAAA,QAChD,QAAA,EAAU,SAAS,QAAA,IAAY;AAAA,OAClC,CAAA;AACD,MAAA,OAAO,MAAM,OAAO,OAAA,EAAQ;AAAA,IAChC,CAAA;AAAA,IACA,CAACA,SAAAA,EAAU,OAAA,EAAS,QAAQ;AAAA,GAChC;AACA,EAAA,MAAM,KAAA,GAAQ,oBAAA,CAAqB,SAAA,EAAW,WAAW,CAAA;AACzD,EAAA,aAAA,CAAc,KAAK,CAAA;AACnB,EAAA,OAAO,KAAA;AACX;AAsEO,SAAS,mBAAA,CACZ,OAAA,EACA,IAAA,EACA,OAAA,EACC;AAKD,EAAA,MAAM,gBAAA,GAAmB,WAAA,CAAY,OAAA,EAAS,IAAI,CAAA;AAClD,EAAA,MAAM,QAAA,GAAW,gBAAA,CAAiB,gBAAA,EAAkB,OAAO,CAAA;AAC3D,EAAA,aAAA,CAAc,QAAQ,CAAA;AACtB,EAAA,OAAO,QAAA;AACX;;"}
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "type": "module",
3
3
  "name": "@open-pioneer/reactivity",
4
- "version": "4.8.0",
4
+ "version": "4.9.0-dev.20261002130116",
5
5
  "description": "Provides integration for the reactivity API.",
6
6
  "keywords": [
7
7
  "open-pioneer-trails"