react-global-state-hooks 3.0.8 → 3.1.0

package/README.md

@@ -503,6 +503,120 @@ const useContacts = createGlobalState(
 
 That means your data will automatically be synchronized with the local storage, and you don't need to worry about losing the type of your Maps/Sets/Dates - the store takes care of it for you.
 
+**The ultimate blend of flexibility and control in React state management!** You can now create an isolated global state within a React context, giving each consumer of the context provider a unique state instance. But that’s not all...
+
+**Stateful Context with Actions** extends the powerful features of global hooks into the realm of React Context. By integrating global hooks within a context, you bring all the benefits of global state management—such as modularity, selectors, derived states, and actions—into a context-specific environment. This means each consumer of the context not only gets a unique state instance but also inherits all the advanced capabilities of global hooks.
+
+## Creating a Stateful Context
+
+Forget about the boilerplate of creating a context... with **createStatefulContext** it's straightforward and powerful. You can create a context and provider with one line of code.
+
+```tsx
+export const [useCounterContext, CounterProvider] = createStatefulContext(2);
+```
+
+Then just wrap the components you need with the provider:
+
+```tsx
+<CounterProvider>
+  <MyComponent />
+</CounterProvider>
+```
+
+And finally, access the context value with the generated custom hook:
+
+```tsx
+const MyComponent = () => {
+  const [useCounter] = useCounterContext();
+
+  // If the component needs to react to state changes, simply use the hook
+  const [count, setCount] = useCounter();
+
+  return <>{count}</>;
+};
+```
+
+What’s the advantage of this, you might ask? Well, now you have all the capabilities of the global hooks within the isolated scope of the context. For example, you can choose whether or not to listen to changes in the state:
+
+```tsx
+const MyComponent = () => {
+  const [, , setCount] = useCounterContext();
+
+  // This component can access only the setter of the state,
+  // and won't re-render if the counter changes
+  return (
+    <button onClick={() => setCount((count) => count + 1)}>Increase</button>
+  );
+};
+```
+
+Now you have selectors—if the state changes, the component will only re-render if the selected portion of the state changes.
+
+```tsx
+const MyComponent = () => {
+  const [useCounter] = useCounterContext();
+
+  // Notice that we can select and derive values from the state
+  const [isEven, setCount] = useCounter((count) => count % 2 === 0);
+
+  useEffect(() => {
+    // Since the counter initially was 2 and now is 4, it’s still an even number.
+    // Because of this, the component will not re-render.
+    setCount(4);
+  }, []);
+
+  return <>{isEven ? 'is even' : 'is odd'}</>;
+};
+```
+
+**createStatefulContext** also allows you to add custom actions to control the manipulation of the state.
+
+```tsx
+import { createStatefulContext, StoreTools } from 'react-global-state-hooks';
+
+type CounterState = {
+  count: number;
+};
+
+const initialState: CounterState = {
+  count: 0,
+};
+
+export const [useCounterContext, CounterProvider] = createStatefulContext(
+  initialState,
+  {
+    actions: {
+      increase: (value: number = 1) => {
+        return ({ setState }: StoreTools<CounterState>) => {
+          setState((state) => ({
+            ...state,
+            count: state.count + value,
+          }));
+        };
+      },
+      decrease: (value: number = 1) => {
+        return ({ setState }: StoreTools<CounterState>) => {
+          setState((state) => ({
+            ...state,
+            count: state.count - value,
+          }));
+        };
+      },
+    } as const,
+  }
+);
+```
+
+And just like with regular global hooks, now instead of a setter, the hook will return the collection of actions:
+
+```tsx
+const MyComponent = () => {
+  const [, , actions] = useCounterContext();
+
+  return <button onClick={() => actions.increase(1)}>Increase</button>;
+};
+```
+
 # Extending Global Hooks
 
 Creating a custom builder for your **global hook** is made incredibly easy with the **createCustomGlobalState** function.

package/lib/src/GlobalStore.context.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+import { ActionCollectionConfig, createStateConfig, StateHook, StateSetter, ActionCollectionResult, StateGetter } from 'react-hooks-global-states';
+export declare const createStatefulContext: <TState, TMetadata = null, TActions extends ActionCollectionConfig<TState, TMetadata> = null>(initialValue: TState, parameters?: createStateConfig<TState, TMetadata, TActions>) => readonly [() => [hook: StateHook<TState, keyof TActions extends never ? StateSetter<TState> : ActionCollectionResult<TState, TMetadata, TActions>, TMetadata>, getter: StateGetter<TState>, setter: keyof TActions extends never ? StateSetter<TState> : ActionCollectionResult<TState, TMetadata, TActions>], React.FC<React.PropsWithChildren<{
+    initialValue?: Partial<TState>;
+}>>];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-global-state-hooks",
-  "version": "3.0.8",
+  "version": "3.1.0",
   "description": "This is a package to easily handling global-state across your react components No-redux, No-context.",
   "main": "lib/bundle.js",
   "types": "lib/src/index.d.ts",