docs: restructure documentation by adding Components section and remo…

…ving Addons section
ismail9k · Dec 26, 2024 · f694469 · f694469
1 parent 10ec570
commit f694469
Show file tree

Hide file tree

Showing 7 changed files with 228 additions and 57 deletions.
diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -28,6 +28,14 @@ module.exports = {
           { text: 'Examples', link: '/examples' },
         ],
       },
+      {
+        text: 'Components',
+        items: [
+          { text: 'Slide', link: '/components/slide' },
+          { text: 'Navigation', link: '/components/navigation' },
+          { text: 'Pagination', link: '/components/pagination' },
+        ],
+      },
       {
         text: 'API',
         items: [
@@ -36,10 +44,6 @@ module.exports = {
           { text: 'Events', link: '/api/events' },
         ],
       },
-      {
-        text: 'Addons',
-        link: '/addons',
-      },
     ],
 
     search: {

diff --git a/docs/addons.md b/docs/addons.md
diff --git a/docs/components/navigation.md b/docs/components/navigation.md
@@ -0,0 +1,76 @@
+# Navigation Component
+
+The Navigation component provides intuitive Previous and Next buttons for slide navigation, with support for custom styling and RTL layouts.
+
+## Basic Usage
+
+```vue {2,11,12,13}
+<script setup>
+import { Navigation as CarouselNavigation } from 'vue3-carousel'
+</script>
+
+<template>
+  <Carousel>
+    <Slide v-for="slide in 10" :key="slide">
+      <!-- slide content -->
+    </Slide>
+    
+    <template #addons>
+      <CarouselNavigation />
+    </template>
+  </Carousel>
+</template>
+```
+
+## Features
+
+- Automatic RTL support
+- Vertical navigation support
+- Customizable button appearance
+- Automatic disable state when reaching bounds
+- Built-in accessibility features
+
+## Custom Navigation Buttons
+
+You can customize the navigation buttons using slots:
+
+```vue 
+<template>
+  <Carousel>
+    <Slide v-for="slide in 10" :key="slide">
+      <!-- slide content -->
+    </Slide>
+    
+    <template #addons>
+      <CarouselNavigation>
+        <template #prev>
+          <span>←</span>
+        </template>
+        <template #next>
+          <span>→</span>
+        </template>
+      </CarouselNavigation>
+    </template>
+  </Carousel>
+</template>
+```
+
+## Styling
+
+### CSS Custom Properties
+
+| Variable                 | Default Value             | Description                     |
+| ------------------------ | ------------------------- | ------------------------------- |
+| `--vc-nav-width`         | `30px`                    | Navigation button width         |
+| `--vc-nav-height`        | `30px`                    | Navigation button height        |
+| `--vc-nav-border-radius` | `0`                       | Navigation button border radius |
+| `--vc-nav-color`         | `var(--vc-clr-primary)`   | Navigation button color         |
+| `--vc-nav-color-hover`   | `var(--vc-clr-secondary)` | Navigation button hover color   |
+| `--vc-nav-background`    | `transparent`             | Navigation button background    |
+
+## Accessibility
+
+- Buttons include descriptive ARIA labels
+- Automatic disable state management
+- Keyboard navigation support
+- Proper focus management
diff --git a/docs/components/pagination.md b/docs/components/pagination.md
@@ -0,0 +1,50 @@
+# Pagination Component
+
+The Pagination component provides interactive indicators that allow users to navigate directly to specific slides.
+
+## Basic Usage
+
+```vue  {2,11,12,13}
+<script setup>
+import { Pagination as CarouselPagination } from 'vue3-carousel'
+</script>
+
+<template>
+  <Carousel>
+    <Slide v-for="slide in 10" :key="slide">
+      <!-- slide content -->
+    </Slide>
+    
+    <template #addons>
+      <CarouselPagination />
+    </template>
+  </Carousel>
+</template>
+```
+
+## Props
+
+| Prop                    | Type    | Default | Description                                                     |
+| ----------------------- | ------- | ------- | --------------------------------------------------------------- |
+| `disableOnClick`        | Boolean | false   | When true, disables navigation when clicking pagination buttons |
+| `paginateByItemsToShow` | Boolean | false   | Groups slides into pages based on `itemsToShow` setting         |
+
+## Styling
+
+### CSS Custom Properties
+
+| Variable                    | Default Value             | Description                        |
+| --------------------------- | ------------------------- | ---------------------------------- |
+| `--vc-pgn-width`            | `16px`                    | Pagination button width            |
+| `--vc-pgn-height`           | `4px`                     | Pagination button height           |
+| `--vc-pgn-margin`           | `6px 5px`                 | Pagination button margin           |
+| `--vc-pgn-border-radius`    | `0`                       | Pagination button border radius    |
+| `--vc-pgn-background-color` | `var(--vc-clr-secondary)` | Pagination button background color |
+| `--vc-pgn-active-color`     | `var(--vc-clr-primary)`   | Active pagination button color     |
+
+
+## Accessibility
+
+- Pagination buttons are properly labeled for screen readers
+- Active state is communicated through ARIA attributes
+- Buttons include descriptive titles for better UX
diff --git a/docs/components/slide.md b/docs/components/slide.md
@@ -0,0 +1,93 @@
+# Slide Component
+
+The Slide component is a fundamental building block of the carousel that represents individual slides. It manages slide visibility, positioning, and state transitions.
+
+## Basic Usage
+
+```vue
+<template>
+  <Carousel>
+    <Slide v-for="slide in 10" :key="slide">
+      <div class="carousel__item">
+        {{ slide }}
+      </div>
+    </Slide>
+  </Carousel>
+</template>
+```
+
+## Props
+
+| Name  | Type   | Default | Description                                                |
+| ----- | ------ | ------- | ---------------------------------------------------------- |
+| index | Number | -       | Zero-based index position of the slide within the carousel |
+
+## Slot Props
+
+The default slot exposes these reactive properties for custom slide content:
+
+| Name         | Type    | Description                                               |
+| ------------ | ------- | --------------------------------------------------------- |
+| currentIndex | Number  | Current index position of the slide                       |
+| isActive     | Boolean | True when this slide is the current active slide          |
+| isClone      | Boolean | True if this is a clone slide (used for infinite scroll)  |
+| isPrev       | Boolean | True if this slide is immediately before the active slide |
+| isNext       | Boolean | True if this slide is immediately after the active slide  |
+| isSliding    | Boolean | True during slide transition animations                   |
+| isVisible    | Boolean | True when the slide is within the visible viewport        |
+
+## Examples
+
+### Basic Slide
+
+```vue
+<template>
+  <Carousel>
+    <Slide v-for="slide in 10" :key="slide">
+      <div class="carousel__item">{{ slide }}</div>
+    </Slide>
+  </Carousel>
+</template>
+```
+
+### Custom Slide with State
+
+```vue
+<template>
+  <Carousel>
+    <Slide v-for="slide in 10" :key="slide">
+      <template #default="{ isActive, isVisible }">
+        <div 
+          class="carousel__item"
+          :class="{
+            'is-active': isActive,
+            'is-visible': isVisible
+          }"
+        >
+          <h3>Slide {{ slide }}</h3>
+          <p>{{ isActive ? 'Current Slide' : 'Other Slide' }}</p>
+        </div>
+      </template>
+    </Slide>
+  </Carousel>
+</template>
+```
+
+## Styling
+
+The component provides these CSS classes for styling:
+
+| CSS Class                   | Description               |
+| --------------------------- | ------------------------- |
+| `.carousel__slide`          | Base slide styles         |
+| `.carousel__slide--clone`   | Cloned slide styles       |
+| `.carousel__slide--visible` | Visible slide styles      |
+| `.carousel__slide--active`  | Active slide styles       |
+| `.carousel__slide--prev`    | Previous slide styles     |
+| `.carousel__slide--next`    | Next slide styles         |
+| `.carousel__slide--sliding` | Styles during transitions |
+
+## Best Practices
+
+1. Always provide a unique `:key` when using v-for with Slides
+2. If you have a dynamic slides which changes its position consider use `index` prop
diff --git a/docs/index.md b/docs/index.md
@@ -36,5 +36,5 @@ meta:
 <Features />
 
 <script setup>
-import Features from './components/Features.vue'
+import Features from './vue-components/Features.vue'
 </script>
diff --git a/docs/components/Features.vue → docs/vue-components/Features.vue b/docs/components/Features.vue → docs/vue-components/Features.vue