better-preact-use-state 1.0.1 → 1.0.3

package/README.md

@@ -1,10 +1,10 @@
-# better-preact-use-state
+## better-preact-use-state
 
-A utility that improves Preact's `useState` to be safer and more convenient.
+A utility that improves Preact's `useState` to be safer and more convenient. Provides both `useState` (enhanced) and a dedicated `useBoolState` hook.
 
 ## Overview
 
-Preact's `useState` can cause unintended behavior when you want to keep a function as a state. `better-preact-use-state` solves this problem and is a utility designed for safer state management in Preact. It's designed to be a drop-in replacement for Preact's `useState` hook.
+Preact's `useState` can cause unintended behavior when you want to hold a function as a state. `better-preact-use-state` solves this problem and is a utility designed for safer state management. It is designed as a drop-in replacement for Preact's `useState` hook, with added functionality. `better-preact-use-state` also provides a simplified hook, `useBoolState`, specifically for boolean state.
 
 ## Installation
 
@@ -24,29 +24,56 @@ pnpm add better-preact-use-state
 
 ## Usage
 
-`better-preact-use-state` can be used the same way as Preact's `useState`.
+### `useState`
+
+`better-preact-use-state`'s `useState` can be used the same way as Preact's `useState`.
 
 ```tsx
 import { useState } from 'better-preact-use-state';
 
 const MyComponent: FunctionalComponent = () => {
-    const [count, setCount] = useState(0);
     const [name, setName] = useState('John Doe');
 
-    const incrementCount = () => setCount(count + 1);
-    const updateName = (newName: string) => setName(newName);
+    const [count, setCount, { updateState: updateCount }] = useState(0);
+
+    const onNameChange = useCallback((event) => {
+        setName(event.target.value);
+    }, []);
+
+    const incrementCount = useCallback(() => {
+        updateCount((x) => x + 1);
+    }, []);
+
+    return (
+        <div>
+            <p>{`Count: ${count}`}</p>
+            <button onClick={incrementCount}>{'Increment'}</button>
+
+            <p>{`Name: ${name}`}</p>
+            <input type='text' value={name} onChange={onNameChange} />
+        </div>
+    );
+};
+```
+
+### `useBoolState`
+
+`useBoolState` simplifies managing boolean state.
+
+```tsx
+import { useBoolState } from 'better-preact-use-state';
+
+const MyComponent = () => {
+    const [isOpen, { setTrue: open, setFalse: close, toggleState }] =
+        useBoolState(false);
 
     return (
         <div>
-            <p>Count: {count}</p>
-            <button onClick={incrementCount}>Increment</button>
-
-            <p>Name: {name}</p>
-            <input
-                type='text'
-                value={name}
-                onChange={(e) => updateName(e.target.value)}
-            />
+            <p>{`Is Open: ${isOpen ? 'Yes' : 'No'}`}</p>
+            <button onClick={open}>{'Open'}</button>
+            <button onClick={close}>{'Close'}</button>
+            <button onClick={toggleState}>{'Toggle'}</button>
+            {/* Toggles the boolean value */}
         </div>
     );
 };
@@ -54,6 +81,8 @@ const MyComponent: FunctionalComponent = () => {
 
 ## API Reference
 
+### `useState`
+
 ```typescript
 const [state, setState, { updateState, resetState }] = useState<T>(initialState: T);
 ```
@@ -63,7 +92,7 @@ const [state, setState, { updateState, resetState }] = useState<T>(initialState:
 -   `updateState`: Function to update the state based on the current state.
 -   `resetState`: Function to reset the state to the initial value.
 
-### `updateState`
+#### `updateState`
 
 ```typescript
 updateState(updateFn: (v: T) => T): void;
@@ -71,7 +100,53 @@ updateState(updateFn: (v: T) => T): void;
 
 Updates the state by passing a function `updateFn` that takes the current state as an argument and returns the new state.
 
-### `resetState`
+#### `resetState`
+
+```typescript
+resetState(): void;
+```
+
+Resets the state to the initial value.
+
+### `useBoolState`
+
+```typescript
+const [state, { setState, setTrue, setFalse, resetState, toggleState, updateState }] = useBoolState(initialState: boolean);
+```
+
+-   `state`: The current boolean value.
+-   `setState`: Function to update the boolean value directly.
+-   `setTrue`: Function to set the state to `true`.
+-   `setFalse`: Function to set the state to `false`.
+-   `resetState`: Function to reset the state to the initial value.
+-   `toggleState`: Function to toggle the boolean value (true to false, false to true).
+-   `updateState`: Function to update the state based on the current state.
+
+#### `setState`
+
+```typescript
+setState(next: boolean): void;
+```
+
+Sets the state to the provided boolean value.
+
+#### `setTrue`
+
+```typescript
+setTrue(): void;
+```
+
+Sets the state to `true`.
+
+#### `setFalse`
+
+```typescript
+setFalse(): void;
+```
+
+Sets the state to `false`.
+
+#### `resetState`
 
 ```typescript
 resetState(): void;
@@ -79,21 +154,37 @@ resetState(): void;
 
 Resets the state to the initial value.
 
+#### `toggleState`
+
+```typescript
+toggleState(): void;
+```
+
+Toggles the current boolean value.
+
+#### `updateState`
+
+```typescript
+updateState(updateFn: (v: boolean) => boolean): void;
+```
+
+Updates the state by passing a function `updateFn` that takes the current state as an argument and returns the new state. This is useful for updates that depend on the current state.
+
 ## Benefits of this library
 
-With Preact's standard `useState`, attempting to store a function as state can lead to unexpected behavior (the function being interpreted as an updater function). `better-preact-use-state` solves this issue and, by providing `updateState`, allows functions to be safely held as state. Also, `resetState` lets you easily return the state to its initial value.
+With Preact's standard `useState`, attempting to store a function as state can lead to unexpected behavior (the function being interpreted as an updater function). `better-preact-use-state` solves this issue and, by providing `updateState`, allows functions to be safely held as state. Also, `resetState` lets you easily return the state to its initial value. `useBoolState` simplifies boolean state management in Preact, offering several advantages over directly using useState for booleans.
 
-## Example Use Case
+### Example Use Case
 
 Useful when you want to hold a function as state.
 
 ```typescript
-const [fn, setFn] = useState(initialFn); // Holds a function as state
+const [fn, setFn, { updateState: updateFn }] = useState(initialFn); // Holds a function as state
 
-// With Preact's standard useState, setFn(nextFn) will interpret nextFn as an updater function.
+// In Preact's standard useState, `setFn(nextFn)` interprets nextFn as an update function.
 
-// With better-preact-use-state, you can use updateState to update the function.
-updateState((currentFn) => nextFn);
+// If you want to update the state with an update function, you can use updateState instead.
+updateFn((currentFn) => nextFn);
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-preact-use-state",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "private": false,
   "license": "MIT",
   "author": "noshiro-pf <noshiro.pf@gmail.com>",