From 8e1aa2f1b68b00fd9871474e015448d0ad707e35 Mon Sep 17 00:00:00 2001
From: KeJun <kejun1997@gmail.com>
Date: Sun, 30 Jul 2023 22:12:41 +0800
Subject: [PATCH] docs(VerticalNavigation): add slots examples (#456)

Co-authored-by: Benjamin Canac <canacb1@gmail.com>
---
 .../VerticalNavigationExampleAvatarSlot.vue   |  25 +++
 .../VerticalNavigationExampleBadgeSlot.vue    |  35 +++
 .../VerticalNavigationExampleDefaultSlot.vue  |  31 +++
 .../VerticalNavigationExampleIconSlot.vue     |  41 ++++
 .../5.navigation/1.vertical-navigation.md     | 202 +++++++++++++++++-
 .../navigation/VerticalNavigation.vue         |   4 +-
 6 files changed, 331 insertions(+), 7 deletions(-)
 create mode 100644 docs/components/content/examples/VerticalNavigationExampleAvatarSlot.vue
 create mode 100644 docs/components/content/examples/VerticalNavigationExampleBadgeSlot.vue
 create mode 100644 docs/components/content/examples/VerticalNavigationExampleDefaultSlot.vue
 create mode 100644 docs/components/content/examples/VerticalNavigationExampleIconSlot.vue

diff --git a/docs/components/content/examples/VerticalNavigationExampleAvatarSlot.vue b/docs/components/content/examples/VerticalNavigationExampleAvatarSlot.vue
new file mode 100644
index 00000000..f16ec53c
--- /dev/null
+++ b/docs/components/content/examples/VerticalNavigationExampleAvatarSlot.vue
@@ -0,0 +1,25 @@
+<script setup>
+const links = [{
+  avatar: {
+    src: 'https://avatars.githubusercontent.com/u/739984?v=4'
+  },
+  label: 'Benjamin Canac'
+}, {
+  label: 'KeJun'
+}]
+
+const { ui } = useAppConfig()
+</script>
+
+<template>
+  <UVerticalNavigation :links="links">
+    <template #avatar="{ link }">
+      <UAvatar
+        v-if="link.avatar"
+        v-bind="{ size: ui.verticalNavigation.avatar.size, ...link.avatar }"
+        :class="[ui.verticalNavigation.avatar.base]"
+      />
+      <UIcon v-else name="i-heroicons-user-circle-20-solid" class="text-lg" />
+    </template>
+  </UVerticalNavigation>
+</template>
diff --git a/docs/components/content/examples/VerticalNavigationExampleBadgeSlot.vue b/docs/components/content/examples/VerticalNavigationExampleBadgeSlot.vue
new file mode 100644
index 00000000..701a2330
--- /dev/null
+++ b/docs/components/content/examples/VerticalNavigationExampleBadgeSlot.vue
@@ -0,0 +1,35 @@
+<script setup>
+const links = [{
+  label: '.github',
+  icon: 'i-heroicons-folder-20-solid',
+  badge: 'chore(github): use pnpm 8',
+  time: 'last month'
+}, {
+  label: '.editorconfig',
+  icon: 'i-heroicons-document-solid',
+  badge: 'Initial commit',
+  time: '2 years ago'
+}, {
+  label: '.package.json',
+  icon: 'i-heroicons-document-solid',
+  badge: 'chore(deps): bump',
+  time: '16 hours ago'
+}]
+</script>
+
+<template>
+  <UVerticalNavigation
+    :links="links"
+    class="w-full"
+    :ui="{
+      label: 'truncate relative text-gray-900 dark:text-white flex-initial w-32 text-left'
+    }"
+  >
+    <template #badge="{ link }">
+      <div class="flex-1 flex justify-between relative truncate">
+        <div>{{ link.badge }}</div>
+        <div>{{ link.time }}</div>
+      </div>
+    </template>
+  </UVerticalNavigation>
+</template>
diff --git a/docs/components/content/examples/VerticalNavigationExampleDefaultSlot.vue b/docs/components/content/examples/VerticalNavigationExampleDefaultSlot.vue
new file mode 100644
index 00000000..e2dd5b99
--- /dev/null
+++ b/docs/components/content/examples/VerticalNavigationExampleDefaultSlot.vue
@@ -0,0 +1,31 @@
+<script setup>
+const links = [{
+  label: 'Navigation',
+  children: [{
+    label: 'Vertical Navigation',
+    to: '/navigation/vertical-navigation'
+  }, {
+    label: 'Command Palette',
+    to: '/navigation/command-palette'
+  }]
+}, {
+  label: 'Data',
+  children: [{
+    label: 'Table',
+    to: '/data/table'
+  }]
+}]
+</script>
+
+<template>
+  <UVerticalNavigation :links="links">
+    <template #default="{ link }">
+      <div class="relative text-left w-full">
+        <div class="mb-2">
+          {{ link.label }}
+        </div>
+        <UVerticalNavigation v-if="link.children" :links="link.children" />
+      </div>
+    </template>
+  </UVerticalNavigation>
+</template>
diff --git a/docs/components/content/examples/VerticalNavigationExampleIconSlot.vue b/docs/components/content/examples/VerticalNavigationExampleIconSlot.vue
new file mode 100644
index 00000000..05bda21a
--- /dev/null
+++ b/docs/components/content/examples/VerticalNavigationExampleIconSlot.vue
@@ -0,0 +1,41 @@
+<script setup>
+const types = {
+  bug: {
+    icon: 'i-heroicons-bug-ant-20-solid',
+    color: 'text-red-500'
+  },
+  docs: {
+    icon: 'i-heroicons-document-text-20-solid',
+    color: 'text-blue-500'
+  },
+  lock: {
+    icon: 'i-heroicons-lock-closed-20-solid',
+    color: 'text-gray dark:text-white'
+  },
+  default: {
+    icon: 'i-heroicons-question-mark-circle-20-solid',
+    color: 'text-green-500'
+  }
+}
+const links = [{
+  label: 'UDropdown and UPopover dropdown menu, dropdown will be obscured',
+  type: 'bug'
+}, {
+  label: 'Uncaught (in promise) ReferenceError: ref is not defined',
+  type: 'lock'
+}, {
+  label: 'Fully styled and customizable components for Nuxt.',
+  type: 'docs'
+}, {
+  label: 'Can I pass a tailwind color to UNotifications with `toast.add()` ?'
+}]
+</script>
+
+<template>
+  <UVerticalNavigation :links="links">
+    <template #icon="{ link }">
+      <UIcon v-if="link.type" :name="types[link.type].icon" :class="types[link.type].color" class="text-base" />
+      <UIcon v-else :name="types.default.icon" :class="types.default.color" class="text-base" />
+    </template>
+  </UVerticalNavigation>
+</template>
diff --git a/docs/content/5.navigation/1.vertical-navigation.md b/docs/content/5.navigation/1.vertical-navigation.md
index 2483462e..4dd78ebd 100644
--- a/docs/content/5.navigation/1.vertical-navigation.md
+++ b/docs/content/5.navigation/1.vertical-navigation.md
@@ -10,12 +10,12 @@ links:
 
 Pass an array to the `links` prop of the VerticalNavigation component. Each link can have the following properties:
 
-- `label` - The label of the item.
-- `icon` - The icon of the item.
-- `iconClass` - The class of the icon of the item.
-- `avatar` - The avatar of the item. You can pass all the props of the [Avatar](/elements/avatar) component.
+- `label` - The label of the link.
+- `icon` - The icon of the link.
+- `iconClass` - The class of the icon of the link.
+- `avatar` - The avatar of the link. You can pass all the props of the [Avatar](/elements/avatar) component.
 - `badge` - A badge to display next to the label.
-- `click` - The click handler of the item.
+- `click` - The click handler of the link.
 
 You can also pass any property from the [NuxtLink](https://nuxt.com/docs/api/components/nuxt-link#props) component such as `to`, `exact`, etc.
 
@@ -53,6 +53,198 @@ const links = [{
 ```
 ::
 
+::callout{icon="i-heroicons-light-bulb"}
+Learn how to build a Tailwind like vertical navigation in the [Examples](/getting-started/examples#verticalnavigation) page.
+::
+
+## Slots
+
+You can use slots to customize links display.
+
+### `default`
+
+Use the `#default` slot to customize the link label. You will have access to the `link` and `isActive` properties in the slot scope.
+
+::component-example
+#default
+:vertical-navigation-example-default-slot
+
+#code
+```vue
+<script setup>
+const links = [{
+  label: 'Navigation',
+  children: [{
+    label: 'Vertical Navigation',
+    to: '/navigation/vertical-navigation'
+  }, {
+    label: 'Command Palette',
+    to: '/navigation/command-palette'
+  }]
+}, {
+  label: 'Data',
+  children: [{
+    label: 'Table',
+    to: '/data/table'
+  }]
+}]
+</script>
+
+<template>
+  <UVerticalNavigation :links="links">
+    <template #default="{ link }">
+      <div class="relative text-left w-full">
+        <div class="mb-2">
+          {{ link.label }}
+        </div>
+        <UVerticalNavigation v-if="link.children" :links="link.children" />
+      </div>
+    </template>
+  </UVerticalNavigation>
+</template>
+```
+::
+
+### `avatar`
+
+Use the `#avatar` slot to customize the link avatar. You will have access to the `link` and `isActive` properties in the slot scope.
+
+::component-example
+#default
+:vertical-navigation-example-avatar-slot
+
+#code
+```vue
+<script setup>
+const links = [{
+  avatar: {
+    src: 'https://avatars.githubusercontent.com/u/739984?v=4'
+  },
+  label: 'Benjamin Canac'
+}, {
+  label: 'KeJun'
+}]
+
+const { ui } = useAppConfig()
+</script>
+
+<template>
+  <UVerticalNavigation :links="links">
+    <template #avatar="{ link }">
+      <UAvatar
+        v-if="link.avatar"
+        v-bind="{ size: ui.verticalNavigation.avatar.size, ...link.avatar }"
+        :class="[ui.verticalNavigation.avatar.base]"
+      />
+      <UIcon v-else name="i-heroicons-user-circle-20-solid" class="text-lg" />
+    </template>
+  </UVerticalNavigation>
+</template>
+```
+::
+
+### `icon`
+
+Use the `#icon` slot to customize the link icon. You will have access to the `link` and `isActive` properties in the slot scope.
+
+::component-example
+#default
+:vertical-navigation-example-icon-slot
+
+#code
+```vue
+<script setup>
+const types = {
+  bug: {
+    icon: 'i-heroicons-bug-ant-20-solid',
+    color: 'text-red-500'
+  },
+  docs: {
+    icon: 'i-heroicons-document-text-20-solid',
+    color: 'text-blue-500'
+  },
+  lock: {
+    icon: 'i-heroicons-lock-closed-20-solid',
+    color: 'text-gray dark:text-white'
+  },
+  default: {
+    icon: 'i-heroicons-question-mark-circle-20-solid',
+    color: 'text-green-500'
+  }
+}
+const links = [{
+  label: 'UDropdown and UPopover dropdown menu, dropdown will be obscured',
+  type: 'bug'
+}, {
+  label: 'Uncaught (in promise) ReferenceError: ref is not defined',
+  type: 'lock'
+}, {
+  label: 'Fully styled and customizable components for Nuxt.',
+  type: 'docs'
+}, {
+  label: 'Can I pass a tailwind color to UNotifications with `toast.add()` ?'
+}]
+</script>
+
+<template>
+  <UVerticalNavigation :links="links">
+    <template #icon="{ link }">
+      <UIcon v-if="link.type" :name="types[link.type].icon" :class="types[link.type].color" class="text-base" />
+      <UIcon v-else :name="types.default.icon" :class="types.default.color" class="text-base" />
+    </template>
+  </UVerticalNavigation>
+</template>
+```
+::
+
+### `badge`
+
+Use the `#badge` slot to customize the link badge. You will have access to the `link` and `isActive` properties in the slot scope.
+
+::component-example
+#default
+:vertical-navigation-example-badge-slot
+
+#code
+```vue
+<script setup>
+const links = [{
+  label: '.github',
+  icon: 'i-heroicons-folder-20-solid',
+  badge: 'chore(github): use pnpm 8',
+  time: 'last month'
+}, {
+  label: '.editorconfig',
+  icon: 'i-heroicons-document-solid',
+  badge: 'Initial commit',
+  time: '2 years ago'
+}, {
+  label: '.package.json',
+  icon: 'i-heroicons-document-solid',
+  badge: 'chore(deps): bump',
+  time: '16 hours ago'
+}]
+</script>
+
+<template>
+  <UVerticalNavigation
+    :links="links"
+    class="w-full"
+    :ui="{
+      label: 'truncate relative text-gray-900 dark:text-white flex-initial w-32 text-left'
+    }"
+  >
+    <template #badge="{ link }">
+      <div class="flex-1 flex justify-between relative truncate">
+        <div>{{ link.badge }}</div>
+        <div>{{ link.time }}</div>
+      </div>
+    </template>
+  </UVerticalNavigation>
+</template>
+```
+::
+
 ## Props
 
 :component-props
diff --git a/src/runtime/components/navigation/VerticalNavigation.vue b/src/runtime/components/navigation/VerticalNavigation.vue
index 1726a2c0..c3f7d38d 100644
--- a/src/runtime/components/navigation/VerticalNavigation.vue
+++ b/src/runtime/components/navigation/VerticalNavigation.vue
@@ -11,7 +11,7 @@
       @click="link.click"
       @keyup.enter="$event.target.blur()"
     >
-      <slot name="avatar" :link="link">
+      <slot name="avatar" :link="link" :is-active="isActive">
         <UAvatar
           v-if="link.avatar"
           v-bind="{ size: ui.avatar.size, ...link.avatar }"
@@ -25,7 +25,7 @@
           :class="[ui.icon.base, isActive ? ui.icon.active : ui.icon.inactive, link.iconClass]"
         />
       </slot>
-      <slot :link="link">
+      <slot :link="link" :is-active="isActive">
         <span v-if="link.label" :class="ui.label">{{ link.label }}</span>
       </slot>
       <slot name="badge" :link="link" :is-active="isActive">