feat: 🚀 useControlledState

Author: NelsonYong

docs/.vitepress/config/en.ts

@@ -197,7 +197,7 @@ export function sidebarHooks(): DefaultTheme.SidebarItem[] {
       text: 'State',
       items: [
         { text: 'useBoolean', link: 'useBoolean' },
-        // { text: "useControlledState", link: "useControlledState" },
+        { text: "useControlledState", link: "useControlledState" },
         { text: 'useImmer', link: 'useImmer' },
         { text: 'useUrlState', link: 'useUrlState' },
         { text: 'useFormatResult', link: 'useFormatResult' },

docs/demo/useControlledState/demo.vue

@@ -0,0 +1,15 @@
+<template>
+  <div>
+    <div>Show default value: {{ count }}</div>
+    <div>Show form value: {{ countFormValue }}</div>
+    <vhp-button @click="() => (value = 10)">Set value</vhp-button>
+  </div>
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import { useControlledState } from 'vue-hooks-plus'
+  const value = ref<number | undefined>(undefined)
+  const [count] = useControlledState(undefined, 10)
+  const [countFormValue] = useControlledState(value, 0)
+</script>

docs/demo/useControlledState/demo1.vue

@@ -0,0 +1,21 @@
+<template>
+  <div>
+    <vhp-button
+      :style="{ backgroundColor: color }"
+      @click="
+        () => {
+          setColor(randomColor())
+        }
+      "
+      >Uncontrolled color</vhp-button
+    >
+  </div>
+</template>
+
+<script lang="ts" setup>
+  import { useControlledState } from 'vue-hooks-plus'
+  const [color, setColor] = useControlledState(undefined, 'red')
+  const randomColor = () => {
+    return '#' + Math.floor(Math.random() * 16777215).toString(16)
+  }
+</script>

docs/demo/useControlledState/demo2.vue

@@ -0,0 +1,41 @@
+<template>
+  <div>
+    <vhp-button
+      style="margin-right: 10px"
+      :style="{ backgroundColor: color1 }"
+      @click="
+        () => {
+          setColor1(randomColor())
+        }
+      "
+      >Controlled unvalid value</vhp-button
+    >
+
+    <vhp-button
+      :style="{ backgroundColor: color }"
+      @click="
+        () => {
+          setColor(randomColor())
+        }
+      "
+      >Controlled color</vhp-button
+    >
+  </div>
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import { useControlledState } from 'vue-hooks-plus'
+
+  const value = ref<string | undefined>('red')
+
+  const value2 = ref<string | undefined>('red')
+
+  const [color1, setColor1] = useControlledState(value2, undefined)
+  const [color, setColor] = useControlledState(value, undefined, v => {
+    value.value = v
+  })
+  const randomColor = () => {
+    return '#' + Math.floor(Math.random() * 16777215).toString(16)
+  }
+</script>

docs/en/hooks/useControlledState.md

@@ -1 +1,72 @@
-# useControlledState `^2.3.0`
+---
+map:
+  # Path mapped to docs
+  path: /useControlledState
+---
+
+# useControlledState `^2.4.0`
+
+A hook for managing controlled and uncontrolled state, similar to React's controlled/uncontrolled pattern.
+
+<!-- [[toc]] -->
+
+## Default Value Mode
+
+When the state is empty, the default value will be used.
+
+<demo src="useControlledState/demo.vue"
+language="vue"
+title="Basic usage"
+desc="Switch between controlled and uncontrolled state."> </demo>
+
+## Uncontrolled Mode
+
+If the first argument does not pass a reactive value, useControlledState will maintain an internally managed value that is not controlled externally.
+
+<demo src="useControlledState/demo1.vue"
+language="vue"
+title="Uncontrolled state"
+desc=""> </demo>
+
+## Controlled Mode
+
+If the first argument passes a reactive value, the state inside useControlledState will be fully controlled by the outside. 
+
+You need to update the reactive value of the first argument in the onChange callback for the change to take effect.
+
+<demo src="useControlledState/demo2.vue"
+language="vue"
+title="Controlled state"
+desc=""></demo>
+
+## API
+
+```typescript
+function useControlledState<T, C = T>(
+  value?: Ref<T | undefined>,
+  defaultValue: T,
+  onChange?: (v: C, ...args: any[]) => void
+): [ComputedRef<T>, (value: T | ((prev: T) => T), ...args: any[]) => void]
+```
+
+## Params
+
+| Property     | Description                                                                 | Type                        | Default   |
+| ------------ | --------------------------------------------------------------------------- | --------------------------- | --------- |
+| value        | Controlled value, if `undefined` will use internal state                    | `Ref<T | undefined>`       | -         |
+| defaultValue | Default value when uncontrolled                                             | `T`                         | -         |
+| onChange     | Callback when value changes (called for both controlled and uncontrolled)   | `(v: C, ...args: any[]) => void` | `undefined` |
+
+## Result
+
+| Property   | Description                                   | Type                                      |
+| ---------- | --------------------------------------------- | ----------------------------------------- |
+| state      | Current value (computed, always in sync)      | `ComputedRef<T>`                          |
+| setState   | Update value (will call onChange if changed)  | `(value: T | ((prev: T) => T), ...args: any[]) => void` |
+
+## Remarks
+
+- If `value` is provided (not `undefined`), the state is controlled by the parent, and `setState` will only trigger `onChange` but not update the value directly.
+- If `value` is `undefined`, the state is uncontrolled and managed internally.
+- If you use a function as the argument to `setState`, a warning will be shown (for compatibility with React API, but not recommended in Vue).
+- The hook will warn if you switch between controlled and uncontrolled mode during the component lifecycle.

docs/zh/hooks/useControlledState.md

@@ -0,0 +1,72 @@
+---
+map:
+  # Path mapped to docs
+  path: /useControlledState
+---
+
+# useControlledState `^2.4.0`
+
+一个用于管理受控和非受控状态的 Hook，类似于 React 的受控/非受控模式。
+
+<!-- [[toc]] -->
+
+## 默认值模式
+
+当状态为空的时候，将使用默认值。
+
+<demo src="useControlledState/demo.vue"
+language="vue"
+title="基本用法"
+desc="默认值会在值为非法的时候应用"> </demo>
+
+## 非受控模式
+
+如果第一个参数不传递响应式值，useControlledState 将在内部维护一个不受外部控制的值。
+
+<demo src="useControlledState/demo1.vue"
+language="vue"
+title="非受控模式"
+desc=""> </demo>
+
+## 受控模式
+
+如果第一个参数传递响应式值，useControlledState 内的状态将完全由外部控制。
+
+需要在第三个参数 onChange 时将第一个参数的响应式值变更才会生效。
+
+<demo src="useControlledState/demo2.vue"
+language="vue"
+title="受控模式"
+desc=""></demo>
+
+## API
+
+```typescript
+function useControlledState<T, C = T>(
+  value?: Ref<T | undefined>,
+  defaultValue: T,
+  onChange?: (v: C, ...args: any[]) => void
+): [ComputedRef<T>, (value: T | ((prev: T) => T), ...args: any[]) => void]
+```
+
+## 参数说明
+
+| 参数         | 说明                                                                 | 类型                        | 默认值   |
+| ------------ | ---------------------------------------------------------------------- | --------------------------- | -------- |
+| value        | 受控值，如果为 `undefined` 则使用内部状态                              | `Ref<T | undefined>`       | -        |
+| defaultValue | 非受控时的默认值                                                      | `T`                         | -        |
+| onChange     | 值变化时的回调（受控和非受控都会调用）                                 | `(v: C, ...args: any[]) => void` | `undefined` |
+
+## 返回结果
+
+| 属性       | 说明                                         | 类型                                      |
+| ---------- | -------------------------------------------- | ----------------------------------------- |
+| state      | 当前值（computed，始终保持同步）             | `ComputedRef<T>`                          |
+| setState   | 更新值（变更时会调用 onChange）              | `(value: T | ((prev: T) => T), ...args: any[]) => void` |
+
+## 备注
+
+- 如果传入了 `value`（不是 `undefined`），则状态由父组件控制，`setState` 只会触发 `onChange`，不会直接更新值。
+- 如果 `value` 为 `undefined`，则状态为非受控，由内部管理。
+- 如果 `setState` 的参数为函数，会有警告（为兼容 React API，不推荐在 Vue 中使用）。
+- 如果在组件生命周期内切换了受控和非受控模式，会有警告。

packages/hooks/src/useControlledState/index.ts

@@ -1,19 +1,23 @@
-import { ref, computed, watch, type Ref, type ComputedRef } from 'vue';
+import { ref, computed, watch, type Ref, type ComputedRef, watchEffect } from 'vue';
 
 export function useControlledState<T, C = T>(
-  value: Ref<T | undefined>,
-  defaultValue: T,
+  value?: Ref<T | undefined>,
+  defaultValue?: T,
   onChange?: (v: C, ...args: any[]) => void
-): [ComputedRef<T>, (value: T | ((prev: T) => T), ...args: any[]) => void] {
-  const isControlled = computed(() => value.value !== undefined);
-  const initialValue = value.value ?? defaultValue;
+): [ComputedRef<T | undefined>, (value: T | ((prev: T) => T), ...args: any[]) => void] {
+  const isControlled = computed(() => value?.value !== undefined);
+  const initialValue = value?.value ?? defaultValue;
   const internalState = ref(initialValue) as Ref<T>;
   const wasControlled = ref(isControlled.value);
 
   const currentValue = computed(() =>
-    isControlled.value ? value.value! : internalState.value
+    isControlled.value ? value?.value : internalState.value
   );
 
+  watchEffect(() => {
+    console.log("isControlled", isControlled.value);
+  })
+
   watch(isControlled, (newVal, oldVal) => {
     if (newVal !== oldVal) {
       console.warn(
@@ -24,13 +28,14 @@ export function useControlledState<T, C = T>(
     }
   });
 
+
   function setValue(newValue: T | ((prev: T) => T), ...args: any[]) {
     if (typeof newValue === 'function') {
       console.warn(
-        'Function callbacks are not supported. See: https://github.com/adobe/react-spectrum/issues/2320'
+        'Function callbacks are not supported.'
       );
       const prev = currentValue.value;
-      const updatedValue = (newValue as (prev: T) => T)(prev);
+      const updatedValue = (newValue as (prev?: T) => T)(prev);
 
       if (!isControlled.value) {
         internalState.value = updatedValue;
@@ -41,7 +46,6 @@ export function useControlledState<T, C = T>(
       }
     } else {
       const shouldUpdate = !Object.is(currentValue.value, newValue);
-
       if (!isControlled.value) {
         internalState.value = newValue;
       }