feat(Timeline): new component (#4215)

Co-authored-by: Benjamin Canac <canacb1@gmail.com>
Co-authored-by: Jakub <jakub.michalek@freelo.io>

docs/app/components/content/examples/timeline/TimelineAlternatingLayoutExample.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import type { TimelineItem } from '@nuxt/ui'
+
+const items: TimelineItem[] = [{
+  date: 'Mar 15, 2025',
+  title: 'Project Kickoff',
+  icon: 'i-lucide-rocket',
+  value: 'kickoff'
+}, {
+  date: 'Mar 22, 2025',
+  title: 'Design Phase',
+  icon: 'i-lucide-palette',
+  value: 'design'
+}, {
+  date: 'Mar 29, 2025',
+  title: 'Development Sprint',
+  icon: 'i-lucide-code',
+  value: 'development'
+}, {
+  date: 'Apr 5, 2025',
+  title: 'Testing & Deployment',
+  icon: 'i-lucide-check-circle',
+  value: 'deployment'
+}]
+</script>
+
+<template>
+  <UTimeline
+    :items="items"
+    :ui="{ item: 'even:flex-row-reverse even:-translate-x-[calc(100%-2rem)] even:text-right' }"
+    :default-value="2"
+    class="w-full translate-x-[calc(50%-2rem)]"
+  />
+</template>

docs/app/components/content/examples/timeline/TimelineCustomSlotExample.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import type { TimelineItem } from '@nuxt/ui'
+
+const items = [{
+  date: 'Mar 15, 2025',
+  title: 'Project Kickoff',
+  subtitle: 'Project Initiation',
+  description: 'Kicked off the project with team alignment. Set up project milestones and allocated resources.',
+  icon: 'i-lucide-rocket',
+  value: 'kickoff'
+}, {
+  date: 'Mar 22, 2025',
+  title: 'Design Phase',
+  description: 'User research and design workshops. Created wireframes and prototypes for user testing.',
+  icon: 'i-lucide-palette',
+  value: 'design'
+}, {
+  date: 'Mar 29, 2025',
+  title: 'Development Sprint',
+  description: 'Frontend and backend development. Implemented core features and integrated with APIs.',
+  icon: 'i-lucide-code',
+  value: 'development',
+  slot: 'development' as const,
+  developers: [
+    {
+      src: 'https://github.com/J-Michalek.png'
+    }, {
+      src: 'https://github.com/benjamincanac.png'
+    }
+  ]
+}, {
+  date: 'Apr 5, 2025',
+  title: 'Testing & Deployment',
+  description: 'QA testing and performance optimization. Deployed the application to production.',
+  icon: 'i-lucide-check-circle',
+  value: 'deployment'
+}] satisfies TimelineItem[]
+</script>
+
+<template>
+  <UTimeline :items="items" :default-value="2" class="w-96">
+    <template #development-title="{ item }">
+      <div class="flex items-center gap-1">
+        <span>{{ item.title }}</span>
+
+        <UAvatarGroup size="2xs">
+          <UAvatar v-for="(developer, index) of item.developers" :key="index" v-bind="developer" />
+        </UAvatarGroup>
+      </div>
+    </template>
+  </UTimeline>
+</template>

docs/app/components/content/examples/timeline/TimelineModelValueExample.vue

@@ -0,0 +1,42 @@
+<script setup lang="ts">
+import type { TimelineItem } from '@nuxt/ui'
+
+const items: TimelineItem[] = [{
+  date: 'Mar 15, 2025',
+  title: 'Project Kickoff',
+  description: 'Kicked off the project with team alignment. Set up project milestones and allocated resources.',
+  icon: 'i-lucide-rocket',
+  value: 'kickoff'
+}, {
+  date: 'Mar 22, 2025',
+  title: 'Design Phase',
+  description: 'User research and design workshops. Created wireframes and prototypes for user testing.',
+  icon: 'i-lucide-palette',
+  value: 'design'
+}, {
+  date: 'Mar 29, 2025',
+  title: 'Development Sprint',
+  description: 'Frontend and backend development. Implemented core features and integrated with APIs.',
+  icon: 'i-lucide-code',
+  value: 'development'
+}, {
+  date: 'Apr 5, 2025',
+  title: 'Testing & Deployment',
+  description: 'QA testing and performance optimization. Deployed the application to production.',
+  icon: 'i-lucide-check-circle',
+  value: 'deployment'
+}]
+
+const active = ref(0)
+
+// Note: This is for demonstration purposes only. Don't do this at home.
+onMounted(() => {
+  setInterval(() => {
+    active.value = (active.value + 1) % items.length
+  }, 2000)
+})
+</script>
+
+<template>
+  <UTimeline v-model="active" :items="items" class="w-96" />
+</template>

docs/app/components/content/examples/timeline/TimelineSlotsExample.vue

@@ -0,0 +1,60 @@
+<script lang="ts" setup>
+import type { TimelineItem } from '@nuxt/ui'
+import { useTimeAgo } from '@vueuse/core'
+
+const items = [{
+  username: 'J-Michalek',
+  date: '2025-05-24T14:58:55Z',
+  action: 'opened this',
+  avatar: {
+    src: 'https://github.com/J-Michalek.png'
+  }
+}, {
+  username: 'J-Michalek',
+  date: '2025-05-26T19:30:14+02:00',
+  action: 'marked this pull request as ready for review',
+  icon: 'i-lucide-check-circle'
+}, {
+  username: 'benjamincanac',
+  date: '2025-05-27T11:01:20Z',
+  action: 'commented on this',
+  description: 'I\'ve made a few changes, let me know what you think! Basically I updated the design, removed unnecessary divs, used Avatar component for the indicator since it supports icon already.',
+  avatar: {
+    src: 'https://github.com/benjamincanac.png'
+  }
+}, {
+  username: 'J-Michalek',
+  date: '2025-05-27T11:01:20Z',
+  action: 'commented on this',
+  description: 'Looks great! Good job on cleaning it up.',
+  avatar: {
+    src: 'https://github.com/J-Michalek.png'
+  }
+}, {
+  username: 'benjamincanac',
+  date: '2025-05-27T11:01:20Z',
+  action: 'merged this',
+  icon: 'i-lucide-git-merge'
+}] satisfies TimelineItem[]
+</script>
+
+<template>
+  <UTimeline
+    :items="items"
+    size="xs"
+    class="w-96"
+    :ui="{
+      date: 'float-end ms-1',
+      description: 'px-3 py-2 ring ring-default mt-2 rounded-md text-default'
+    }"
+  >
+    <template #title="{ item }">
+      <span>{{ item.username }}</span>
+      <span class="font-normal text-muted">&nbsp;{{ item.action }}</span>
+    </template>
+
+    <template #date="{ item }">
+      {{ useTimeAgo(new Date(item.date)) }}
+    </template>
+  </UTimeline>
+</template>

docs/content/3.components/stepper.md

@@ -200,6 +200,10 @@ Use the `#content` slot to customize the content of each item.
 
 Use the `slot` property to customize a specific item.
 
+You will have access to the following slots:
+
+- `#{{ item.slot }}`{lang="ts-type"}
+
 :component-example{name="stepper-custom-slot-example"}
 
 ## API

docs/content/3.components/tabs.md

@@ -222,6 +222,10 @@ Use the `#content` slot to customize the content of each item.
 
 Use the `slot` property to customize a specific item.
 
+You will have access to the following slots:
+
+- `#{{ item.slot }}`{lang="ts-type"}
+
 :component-example{name="tabs-custom-slot-example"}
 
 ## API

docs/content/3.components/timeline.md

@@ -0,0 +1,228 @@
+---
+title: Timeline
+description: 'A component that displays a sequence of events with dates, titles, icons or avatars.'
+category: data
+links:
+  - label: GitHub
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/ui/tree/v3/src/runtime/components/Timeline.vue
+navigation.badge: Soon
+---
+
+## Usage
+
+### Items
+
+Use the `items` prop as an array of objects with the following properties:
+
+- `date?: string`{lang="ts-type"}
+- `title?: string`{lang="ts-type"}
+- `description?: AvatarProps`{lang="ts-type"}
+- `icon?: string`{lang="ts-type"}
+- `avatar?: AvatarProps`{lang="ts-type"}
+- `value?: string | number`{lang="ts-type"}
+- [`slot?: string`{lang="ts-type"}](#with-custom-slot)
+- `class?: any`{lang="ts-type"}
+- `ui?: { item?: ClassNameValue, container?: ClassNameValue, indicator?: ClassNameValue, separator?: ClassNameValue, wrapper?: ClassNameValue, separator?: ClassNameValue, date?: ClassNameValue, title?: ClassNameValue, description?: ClassNameValue }`{lang="ts-type"}
+
+::component-code
+---
+ignore:
+  - items
+  - class
+  - defaultValue
+external:
+  - items
+externalTypes:
+  - TimelineItem[]
+props:
+  defaultValue: 2
+  items:
+    - date: 'Mar 15, 2025'
+      title: 'Project Kickoff'
+      description: 'Kicked off the project with team alignment. Set up project milestones and allocated resources.'
+      icon: 'i-lucide-rocket'
+    - date: 'Mar 22 2025'
+      title: 'Design Phase'
+      description: 'User research and design workshops. Created wireframes and prototypes for user testing.'
+      icon: 'i-lucide-palette'
+    - date: 'Mar 29 2025'
+      title: 'Development Sprint'
+      description: 'Frontend and backend development. Implemented core features and integrated with APIs.'
+      icon: 'i-lucide-code'
+    - date: 'Apr 5 2025'
+      title: 'Testing & Deployment'
+      description: 'QA testing and performance optimization. Deployed the application to production.'
+      icon: 'i-lucide-check-circle'
+  class: 'w-96'
+---
+::
+
+### Color
+
+Use the `color` prop to change the color of the active items in a Timeline.
+
+::component-code
+---
+ignore:
+  - items
+  - class
+  - defaultValue
+external:
+  - items
+externalTypes:
+  - TimelineItem[]
+props:
+  color: neutral
+  defaultValue: 2
+  items:
+    - date: 'Mar 15, 2025'
+      title: 'Project Kickoff'
+      description: 'Kicked off the project with team alignment. Set up project milestones and allocated resources.'
+      icon: 'i-lucide-rocket'
+    - date: 'Mar 22 2025'
+      title: 'Design Phase'
+      description: 'User research and design workshops. Created wireframes and prototypes for user testing.'
+      icon: 'i-lucide-palette'
+    - date: 'Mar 29 2025'
+      title: 'Development Sprint'
+      description: 'Frontend and backend development. Implemented core features and integrated with APIs.'
+      icon: 'i-lucide-code'
+    - date: 'Apr 5 2025'
+      title: 'Testing & Deployment'
+      description: 'QA testing and performance optimization. Deployed the application to production.'
+      icon: 'i-lucide-check-circle'
+  class: 'w-96'
+---
+::
+
+### Size
+
+Use the `size` prop to change the size of the Timeline.
+
+::component-code
+---
+ignore:
+  - items
+  - class
+  - defaultValue
+external:
+  - items
+externalTypes:
+  - TimelineItem[]
+props:
+  size: xs
+  defaultValue: 2
+  items:
+    - date: 'Mar 15, 2025'
+      title: 'Project Kickoff'
+      description: 'Kicked off the project with team alignment. Set up project milestones and allocated resources.'
+      icon: 'i-lucide-rocket'
+    - date: 'Mar 22 2025'
+      title: 'Design Phase'
+      description: 'User research and design workshops. Created wireframes and prototypes for user testing.'
+      icon: 'i-lucide-palette'
+    - date: 'Mar 29 2025'
+      title: 'Development Sprint'
+      description: 'Frontend and backend development. Implemented core features and integrated with APIs.'
+      icon: 'i-lucide-code'
+    - date: 'Apr 5 2025'
+      title: 'Testing & Deployment'
+      description: 'QA testing and performance optimization. Deployed the application to production.'
+      icon: 'i-lucide-check-circle'
+  class: 'w-96'
+---
+::
+
+### Orientation
+
+Use the `orientation` prop to change the orientation of the Timeline. Defaults to `vertical`.
+
+::component-code
+---
+ignore:
+  - items
+  - class
+  - defaultValue
+external:
+  - items
+externalTypes:
+  - TimelineItem[]
+props:
+  orientation: 'horizontal'
+  defaultValue: 2
+  items:
+    - date: 'Mar 15, 2025'
+      title: 'Project Kickoff'
+      description: 'Kicked off the project with team alignment.'
+      icon: 'i-lucide-rocket'
+    - date: 'Mar 22 2025'
+      title: 'Design Phase'
+      description: 'User research and design workshops.'
+      icon: 'i-lucide-palette'
+    - date: 'Mar 29 2025'
+      title: 'Development Sprint'
+      description: 'Frontend and backend development.'
+      icon: 'i-lucide-code'
+    - date: 'Apr 5 2025'
+      title: 'Testing & Deployment'
+      description: 'QA testing and performance optimization.'
+      icon: 'i-lucide-check-circle'
+  class: 'w-full'
+---
+::
+
+## Examples
+
+### Control active item
+
+You can control the active item by using the `default-value` prop or the `v-model` directive with the index of the item.
+
+:component-example{name="timeline-model-value-example" prettier}
+
+::tip
+You can also pass the `value` of one of the items if provided.
+::
+
+### With alternating layout
+
+Use the `ui` prop to create a Timeline with alternating layout.
+
+:component-example{name="timeline-alternating-layout-example" prettier}
+
+### With custom slot
+
+Use the `slot` property to customize a specific item.
+
+You will have access to the following slots:
+
+- `#{{ item.slot }}-indicator`{lang="ts-type"}
+- `#{{ item.slot }}-date`{lang="ts-type"}
+- `#{{ item.slot }}-title`{lang="ts-type"}
+- `#{{ item.slot }}-description`{lang="ts-type"}
+
+:component-example{name="timeline-custom-slot-example" prettier}
+
+### With slots
+
+Use the available slots to create a more complex Timeline.
+
+:component-example{name="timeline-slots-example" prettier}
+
+## API
+
+### Props
+
+:component-props
+
+### Slots
+
+:component-slots
+
+### Emits
+
+:component-emits
+
+## Theme
+
+:component-theme

docs/content/3.components/tree.md

@@ -407,7 +407,14 @@ This lets you select a parent item without expanding or collapsing its children.
 
 ### With custom slot
 
-Use the `item.slot` property to customize a specific item.
+Use the `slot` property to customize a specific item.
+
+You will have access to the following slots:
+
+- `#{{ item.slot }}`{lang="ts-type"}
+- `#{{ item.slot }}-leading`{lang="ts-type"}
+- `#{{ item.slot }}-label`{lang="ts-type"}
+- `#{{ item.slot }}-trailing`{lang="ts-type"}
 
 ::component-example
 ---