From 3e7fee0ba962d70027464f802eca127ae9b51858 Mon Sep 17 00:00:00 2001
From: zernonia <zernonia@gmail.com>
Date: Tue, 18 Feb 2025 10:20:56 +0800
Subject: [PATCH] docs: add controlled state

---
 docs/.vitepress/config.ts                    |   1 +
 docs/components/Callout.vue                  |   2 +-
 docs/content/docs/guides/controlled-state.md | 132 +++++++++++++++++++
 3 files changed, 134 insertions(+), 1 deletion(-)
 create mode 100644 docs/content/docs/guides/controlled-state.md

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index dd9e71e61..099c7344d 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -112,6 +112,7 @@ export default defineConfig({
           { text: 'Styling', link: '/docs/guides/styling' },
           { text: 'Animation/Transition', link: '/docs/guides/animation' },
           { text: 'Composition', link: '/docs/guides/composition' },
+          { text: `Controlled State ${BadgeHTML('New')}`, link: '/docs/guides/controlled-state' },
           {
             text: 'Server side rendering',
             link: '/docs/guides/server-side-rendering',
diff --git a/docs/components/Callout.vue b/docs/components/Callout.vue
index 0e09ff52c..b74a48a53 100644
--- a/docs/components/Callout.vue
+++ b/docs/components/Callout.vue
@@ -29,7 +29,7 @@ const activeType = computed(() => {
 
 <template>
   <div
-    class="text-sm rounded-xl border px-6 py-4 [&_p]:mb-0 my-4"
+    class="text-sm rounded-xl border px-6 py-4 last:[&>*]:mb-0 my-4"
     :class="activeType.class"
   >
     <div class="flex items-center gap-2 font-semibold mb-4">
diff --git a/docs/content/docs/guides/controlled-state.md b/docs/content/docs/guides/controlled-state.md
new file mode 100644
index 000000000..96f60f2c4
--- /dev/null
+++ b/docs/content/docs/guides/controlled-state.md
@@ -0,0 +1,132 @@
+---
+title: Controlled State
+description: How to work with controlled vs. uncontrolled state in Reka UI.
+---
+
+# Controlled State
+
+<Description>
+How to work with controlled vs. uncontrolled state in Reka UI.
+</Description>
+
+Reka UI provides flexible state management for components, allowing developers to use either **controlled** or **uncontrolled** state. Understanding when to use each approach ensures better integration with Vue's reactivity system.
+
+---
+
+## Controlled vs. Uncontrolled State
+
+### Controlled State
+A **controlled** component receives its state as a prop and requires explicit updates via event listeners. The parent component manages and synchronizes the state.
+
+#### Example: Controlled `SwitchRoot`
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { SwitchRoot, SwitchThumb } from 'reka-ui'
+
+const isActive = ref(false)
+
+function handleUpdate(value) {
+  isActive.value = value
+}
+</script>
+
+<template>
+  <SwitchRoot :model-value="isActive" @update:model-value="handleUpdate">
+    <SwitchThumb />
+  </SwitchRoot>
+</template>
+```
+
+**How it works:**
+- The `SwitchRoot` component’s state is managed by the `isActive` ref.
+- The `@update:modelValue` event ensures updates propagate correctly.
+
+<Callout type="tip" title="Use controlled state when:">
+
+- You need to sync state with Vuex, Pinia, or an API.
+- Multiple components rely on the same state.
+- You want fine-grained control over updates.
+
+</Callout>
+
+#### Using v-model with Controlled Components
+
+Vue’s `v-model` syntax provides a convenient way to bind values to controlled components in Reka UI. It automatically handles passing the value and listening for updates.
+
+Example: Using `v-model` with `SwitchRoot`
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { SwitchRoot, SwitchThumb } from 'reka-ui'
+
+const isActive = ref(false)
+</script>
+
+<template>
+  <SwitchRoot v-model="isActive">
+    <SwitchThumb />
+  </SwitchRoot>
+</template>
+```
+
+### Uncontrolled State
+An **uncontrolled** component manages its own state internally, without requiring a parent-controlled prop. Instead of `modelValue`, Reka UI components use `defaultValue` to initialize state.
+
+#### Example: Uncontrolled `SwitchRoot`
+```vue
+<template>
+  <SwitchRoot default-value="true">
+    <SwitchThumb />
+  </SwitchRoot>
+</template>
+```
+
+**How it works:**
+- The `SwitchRoot` initializes its state with `defaultValue`.
+- State changes occur internally without external control.
+
+<Callout type="tip" title="Use uncontrolled state when:">
+
+- The component does not need to sync with external logic.
+- You want a simpler setup without explicit state management.
+- The state is local and does not impact other components.
+
+</Callout>
+
+## Common Mistakes & Fixes
+
+### 1. Forgetting `@update:checked`
+
+```vue
+<!-- ❌ Incorrect: -->
+<SwitchRoot :modelValue="isActive" />
+
+<!-- ✅ Correct: -->
+<SwitchRoot :modelValue="isActive" @update:modelValue="(val) => isActive = val" />
+```
+
+### 2. Using `modelValue` Instead of `defaultValue`
+
+```vue
+<!-- ❌ Incorrect: -->
+<SwitchRoot :modelValue="true" />
+
+<!-- ✅ Correct: -->
+<SwitchRoot defaultValue="true" />
+```
+
+### 3. Not Providing a Setter for Computed Props
+
+```ts
+// ❌ Incorrect:
+const isActive = computed(() => store.state.toggleState)
+
+// ✅ Correct:
+const isActive = computed({
+  get: () => store.state.toggleState,
+  set: val => store.commit('setToggleState', val)
+})
+```