docs: improve useState docs and add example (#1961)

Co-authored-by: pooya parsa <pyapar@gmail.com>

docs/content/3.docs/1.usage/2.state.md

@@ -31,9 +31,7 @@ const state = useState<T>(key: string, init?: () => T): Ref<T>
 
 Using [auto-imported composables](/docs/directory-structure/composables) we can define global type-safe states.
 
-```ts [composables/states.ts]
-export const useColor = () => useState<string>('color', () => 'pink')
-```
+::code-group
 
 ```vue [app.vue]
 <script setup>
@@ -43,11 +41,30 @@ const color = useColor() // Same as useState('color')
 <template>
   Current color: {{ color }}
 </template>
+
 ```
 
+```ts [composables/states.ts]
+export const useColor = () => useState<string>('color', () => 'pink')
+```
+
+::
+
 ## Example
 
-In this example, we use a server-only plugin to find about request locale.
+In this example, we use a [server-only plugin](/docs/directory-structure/plugins) to find about request locale.
+
+::code-group
+
+```vue [app.vue]
+<script setup>
+const locale = useLocale()
+</script>
+
+<template>
+  Current locale: {{ locale }}
+</template>
+```
 
 ```ts [composables/states.ts]
 export const useLocale = () => useState<string>('locale', () => 'en')
@@ -56,16 +73,10 @@ export const useLocale = () => useState<string>('locale', () => 'en')
 ```ts [plugins/locale.server.ts]
 export default defineNuxtPlugin((nuxtApp) => {
   const locale = useLocale()
-  locale.value = nuxtApp.ssrContext?.req.headers['accept-language']?.split(',')[0]
+  locale.value = locale.value ?? nuxtApp.ssrContext?.req.headers['accept-language']?.split(',')[0]
 })
 ```
 
-```vue [app.vue]
-<script setup>
-const locale = useLocale() // Same as useState('locale')
-</script>
+::
 
-<template>
-  Current locale: {{ locale }}
-</template>
-```
+:button-link[Full example on StackBlitz]{href="https://stackblitz.com/github/nuxt/framework/tree/main/examples/use-state?terminal=dev" blank}

examples/use-state/app.vue

@@ -1,15 +1,31 @@
+<script setup>
+const locale = useLocale()
+const locales = [
+  'en-US',
+  'en-GB',
+  'ko-KR',
+  'ar-EG',
+  'fa-IR',
+  'ja-JP-u-ca-japanese'
+]
+if (!locales.includes(locale.value)) {
+  locales.unshift(locale.value)
+}
+
+// Using Intl.DateTimeFormat for language-sensitive date and time formatting
+// Learn more: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat
+const NUXT_BIRTHDAY = new Date('2016-10-26')
+const date = computed(() => new Intl.DateTimeFormat(locale.value).format(NUXT_BIRTHDAY))
+</script>
+
 <template>
   <div>
-    Locale: {{ locale }}
-    <button @click="updateLocale">
-      Set to Klington
-    </button>
+    <h2>Nuxt birthday: {{ date }}</h2>
+    <label for="locale-chooser">Locale: </label>
+    <select id="locale-chooser" v-model="locale">
+      <option v-for="l of locales" :key="l" :value="l">
+        {{ l }}
+      </option>
+    </select>
   </div>
 </template>
-
-<script setup>
-// Defined in composables/stats.ts
-// same as useState('locale')
-const locale = useLocale()
-const updateLocale = () => { locale.value = 'tlh-klingon' }
-</script>

examples/use-state/plugins/locale.server.ts

@@ -1,4 +1,13 @@
+/**
+ * Nuxt will automatically read the files in your plugins directory and load them.
+ * You can use .server or .client in the file name to load a plugin just on server- or client-side.
+ * https://v3.nuxtjs.org/docs/directory-structure/plugins
+ */
 export default defineNuxtPlugin((nuxtApp) => {
   const locale = useLocale()
-  locale.value = nuxtApp.ssrContext?.req.headers['accept-language']?.split(',')[0]
+  // Learn more about the nuxtApp interface on https://v3.nuxtjs.org/docs/usage/nuxt-app#nuxtapp-interface-advanced
+  const req = nuxtApp.ssrContext?.req
+
+  // Set default locale based request headers (browser locale)
+  locale.value = locale.value ?? req.headers['accept-language']?.split(',')[0]
 })