doc: add useUser example

Author: rrd108

docs/user-guide/components.md

@@ -181,9 +181,14 @@ const handleEdit = (user) => {
   editingUser.value = user
 }
 
-const handleUserUpdated = () => {
+const handleUserUpdated = (updatedUser) => {
   editingUser.value = null
-  userList.value?.refresh()
+  // Update the user in the list for immediate UI update
+  userList.value?.updateUser(updatedUser)
+}
+
+const handleEdit = (user) => {
+  editingUser.value = user
 }
 </script>
 
@@ -281,17 +286,71 @@ const handleUserUpdated = () => {
 | `user` | `{ user: User, index: number }` | Custom user item display |
 | `pagination` | `{ pagination, fetchUsers, loading }` | Custom pagination controls |
 
-**Methods**
+**Events**
 
-| Method | Description |
-|--------|-------------|
-| `refresh()` | Manually refresh the user list |
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `editClick` | `User` | Fired when edit button is clicked |
+| `delete` | `User` | Fired after successful user deletion |
 
 ### NUsersUserCard
 
 Displays individual user information with edit and delete actions. Used internally by `NUsersList` but can be used standalone.
 The `edit` and `delete` events are emitted when the edit or delete button is clicked. The `delete` event is calling the API to delete the user, while the `edit` event is just emitting the user object and let the parent component handle the edit action.
 
+### Automatic UI Updates
+
+The `NUsersList` component follows an event-driven pattern for handling user updates. When a user is edited, the component emits events that the parent can handle to update the local state.
+
+**Event Flow:**
+1. User clicks edit → `NUsersUserCard` emits `editClick`
+2. `NUsersList` forwards the event to parent → Parent receives `editClick`
+3. Parent shows edit form → User submits changes
+4. Parent updates local state → UI automatically reflects changes
+
+**Example with event-driven updates:**
+```vue
+<script setup>
+import { ref } from 'vue'
+import { useUsers } from 'nuxt-users/composables'
+
+const { users, updateUser } = useUsers()
+const editingUser = ref(null)
+
+const handleEdit = (user) => {
+  editingUser.value = user
+}
+
+const handleUserUpdated = (userData) => {
+  editingUser.value = null
+  // Update the local state using the composable
+  if (userData.id) {
+    updateUser(userData)
+  }
+}
+</script>
+
+<template>
+  <div>
+    <NUsersUserForm 
+      v-if="editingUser" 
+      :user="editingUser" 
+      @submit="handleUserUpdated" 
+    />
+    <NUsersList 
+      @edit-click="handleEdit" 
+    />
+  </div>
+</template>
+```
+
+**Benefits of this approach:**
+- **Loose coupling** - Components don't need to know about each other's internal methods
+- **Event-driven** - Clean separation of concerns
+- **Reusable** - Parent can handle events however it wants
+- **Testable** - Easy to test event handling
+- **Flexible** - Parent can implement any update strategy
+
 #### Basic Usage
 
 ```vue

playground/pages/users.vue

@@ -1,32 +1,34 @@
 <script setup lang="ts">
 import { ref } from 'vue'
+import { useUsers } from '../../src/runtime/composables/useUsers'
 import type { User } from '../../src/types'
 
-const usersListRef = ref()
-
-const refreshUserList = () => {
-  console.log('refreshUserList')
-  if (usersListRef.value) {
-    usersListRef.value.refresh()
-  }
-}
+const { updateUser } = useUsers()
 
 const selectedUser = ref<User | null>(null)
 const handleEditClick = (user: User) => {
   selectedUser.value = user
 }
+
+const handleUserUpdated = (userData: Partial<User>) => {
+  console.log('User updated:', userData)
+  selectedUser.value = null
+  // Update the user in the local state using the composable
+  if (userData.id) {
+    updateUser(userData as User)
+  }
+}
 </script>
 
 <template>
   <div>
     <NUsersUserForm
       :user="selectedUser"
-      @submit="refreshUserList"
+      @submit="handleUserUpdated"
     />
     <NUsersList
-      ref="usersListRef"
       @edit-click="handleEditClick"
-      @delete="refreshUserList"
+      @delete="() => {}"
     />
   </div>
 </template>

src/runtime/components/NUsersUserCard.vue

@@ -71,6 +71,7 @@ const canDelete = computed(() => {
 })
 
 const editUser = async (user: User) => {
+  console.info('The edit event is emitted. Nuxt-users does not automatically calls the API to update the user, you should do it at the upper component.')
   emit('editClick', user)
 }