feat: new hook useBoolean

src/index.ts

@@ -8,6 +8,7 @@ export * from './use-async-update-effect'
 export * from './use-battery'
 export * from './use-before-unload'
 export * from './use-bluetooth'
+export * from './use-boolean'
 export * from './use-breakpoints'
 export * from './use-browser-memory'
 export * from './use-circular-list'

src/use-boolean/demo.tsx

@@ -0,0 +1,23 @@
+import { Button, Card, KeyValue, Zone } from '@/components'
+import { useBoolean, useCircularList } from '@shined/react-use'
+
+export function App() {
+  const [bool, actions] = useBoolean(true)
+  const [value, listActions] = useCircularList(['A', 'B', 'C', 'D', 'F', 'G'])
+
+  return (
+    <Card>
+      <Zone>
+        <KeyValue label="bool" value={bool} />
+        <KeyValue label="value" value={value} />
+      </Zone>
+      <Zone>
+        <Button onClick={actions.toggle}>Toggle bool</Button>
+        <Button onClick={actions.setTrue}>Set true</Button>
+        <Button onClick={actions.setFalse}>Set false</Button>
+        <Button onClick={() => listActions.prev()}>Prev value</Button>
+        <Button onClick={() => listActions.next()}>Next value</Button>
+      </Zone>
+    </Card>
+  )
+}

src/use-boolean/index.mdx

@@ -0,0 +1,67 @@
+# useBoolean
+
+import { HooksType } from '@/components'
+
+<HooksType category="State" />
+
+A React Hook that helps to manage a `boolean` state.
+
+:::tip
+
+If you need to manage a state that alternates among several values, consider utilizing [useCircularList](/reference/use-circular-list) as an alternative.
+
+:::
+
+## Demo
+
+import { App } from './demo'
+
+<App />
+
+## Usage
+
+import { RawCode } from '@/components'
+import source from '!!raw-loader!./demo'
+
+<RawCode>{source}</RawCode>
+
+## Source
+
+import { Source } from '@/components'
+
+<Source />
+
+## API
+
+```tsx
+const [bool, actions] = useBoolean(initialBool)
+```
+
+### InitialBool \{#initial-bool}
+
+A `boolean` value that represents the initial state.
+
+### Returns
+
+```tsx
+export type UseBooleanActions = {
+  /**
+   * Set the boolean state to `true`.
+   */
+  setTrue: () => void
+  /**
+   * Set the boolean state to `false`.
+   */
+  setFalse: () => void
+  /**
+   * Set the boolean state to the given value.
+   */
+  setState: ReactSetState<boolean>
+  /**
+   * Toggle the boolean state.
+   */
+  toggle: () => void
+}
+
+export type UseBooleanReturns = readonly [value: boolean, UseBooleanActions]
+```

src/use-boolean/index.ts

@@ -0,0 +1,44 @@
+import { useCreation } from '../use-creation'
+import { useToggle } from '../use-toggle'
+
+import type { ReactSetState } from '../use-safe-state'
+
+export type UseBooleanActions = {
+  /**
+   * Set the boolean state to `true`.
+   */
+  setTrue: () => void
+  /**
+   * Set the boolean state to `false`.
+   */
+  setFalse: () => void
+  /**
+   * Set the boolean state to the given value.
+   */
+  setState: ReactSetState<boolean>
+  /**
+   * Toggle the boolean state.
+   */
+  toggle: () => void
+}
+
+export type UseBooleanReturns = readonly [value: boolean, UseBooleanActions]
+
+/**
+ * A hook to manage a boolean state.
+ *
+ * @param {boolean} [initialValue=true] The initial value of the boolean state.
+ *
+ */
+export function useBoolean(initialValue: boolean = true): UseBooleanReturns {
+  const [value, toggle, _actions] = useToggle(initialValue)
+
+  const actions = useCreation(() => ({
+    setTrue: () => _actions.setState(true),
+    setFalse: () => _actions.setState(false),
+    setState: _actions.setState,
+    toggle,
+  }))
+
+  return [value, actions] as const
+}

src/use-boolean/index_zh-cn.mdx

@@ -0,0 +1,67 @@
+# useBoolean
+
+import { HooksType } from '@/components'
+
+<HooksType category="State" />
+
+一个用于帮助管理 `boolean` 状态的 React Hook。
+
+:::tip
+
+如果你需要管理在几个值之间交替的状态，请考虑使用 [useCircularList](/reference/use-circular-list) 作为替代方案。
+
+:::
+
+## 演示 Demo \{#demo}
+
+import { App } from './demo'
+
+<App />
+
+## 用法 Usage \{#usage}
+
+import { RawCode } from '@/components'
+import source from '!!raw-loader!./demo'
+
+<RawCode>{source}</RawCode>
+
+## 源码 Source \{#source}
+
+import { Source } from '@/components'
+
+<Source />
+
+## API \{#api}
+
+```tsx
+const [bool, actions] = useBoolean(initialBool)
+```
+
+### 初始布尔值 InitialBool \{#initial-bool}
+
+表示初始状态的 `boolean` 值。
+
+### 返回值 Returns \{#returns}
+
+```tsx
+export type UseBooleanActions = {
+  /**
+   * 将布尔状态设置为 `true`。
+   */
+  setTrue: () => void
+  /**
+   * 将布尔状态设置为 `false`。
+   */
+  setFalse: () => void
+  /**
+   * 将布尔状态设置为给定的值。
+   */
+  setState: ReactSetState<boolean>
+  /**
+   * 切换布尔状态。
+   */
+  toggle: () => void
+}
+
+export type UseBooleanReturns = readonly [value: boolean, UseBooleanActions]
+```

src/use-toggle/demo.tsx

@@ -2,20 +2,19 @@ import { Button, Card, KeyValue, Zone } from '@/components'
 import { useCircularList, useToggle } from '@shined/react-use'
 
 export function App() {
-  const [bool, toggleBool] = useToggle(true)
-  const [mode, toggleMode] = useToggle(['light', 'dark'] as const)
+  const [mode, toggleMode, actions] = useToggle(['light', 'dark'] as const)
   const [value, listActions] = useCircularList(['A', 'B', 'C', 'D', 'F', 'G'])
 
   return (
     <Card>
       <Zone>
-        <KeyValue label="bool" value={bool} />
         <KeyValue label="mode" value={mode} />
         <KeyValue label="value" value={value} />
       </Zone>
       <Zone>
-        <Button onClick={toggleBool}>Toggle bool</Button>
         <Button onClick={toggleMode}>Toggle mode</Button>
+        <Button onClick={actions.setLeft}>Set left</Button>
+        <Button onClick={actions.setRight}>Set right</Button>
         <Button onClick={() => listActions.prev()}>Prev value</Button>
         <Button onClick={() => listActions.next()}>Next value</Button>
       </Zone>