From f69446981da4f0fe3bd6136bd00a7d9c7b2bd231 Mon Sep 17 00:00:00 2001 From: Ismail9k Date: Thu, 26 Dec 2024 15:39:30 +0300 Subject: [PATCH] docs: restructure documentation by adding Components section and removing Addons section --- docs/.vitepress/config.js | 12 ++- docs/addons.md | 52 ----------- docs/components/navigation.md | 76 +++++++++++++++ docs/components/pagination.md | 50 ++++++++++ docs/components/slide.md | 93 +++++++++++++++++++ docs/index.md | 2 +- .../Features.vue | 0 7 files changed, 228 insertions(+), 57 deletions(-) delete mode 100644 docs/addons.md create mode 100644 docs/components/navigation.md create mode 100644 docs/components/pagination.md create mode 100644 docs/components/slide.md rename docs/{components => vue-components}/Features.vue (100%) diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index d02f6f7..1fbfb00 100644 --- 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 deleted file mode 100644 index de279cf..0000000 --- a/docs/addons.md +++ /dev/null @@ -1,52 +0,0 @@ -# Addons - -Enhance the functionality of the carousel by adding more features to it/ - -## Navigation - -The **Navigation** addon provides **Next** and **Previous** buttons for navigating through the carousel. - -### How to Use It - -```vue {2,9} - - - - -``` - -## Pagination - -The **Pagination** addon adds pagination indicators to the carousel. - -```vue {2,9} - - - - -``` - -### Config - -| Prop | Default | Description | -|-------------------------| ------- |-------------------------------------------------------------------------------------------------------------------------------------| -| `disableOnClick` | false | Disables navigation on click | -| `paginateByItemsToShow` | false | Enables grouping of slides into pages (calculated based on the current itemsToShow) where each page gets a single navigation button | diff --git a/docs/components/navigation.md b/docs/components/navigation.md new file mode 100644 index 0000000..3db9a55 --- /dev/null +++ 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} + + + +``` + +## 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 + +``` + +## 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 new file mode 100644 index 0000000..03262e4 --- /dev/null +++ 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} + + + +``` + +## 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 new file mode 100644 index 0000000..3803a98 --- /dev/null +++ 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 + +``` + +## 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 + +``` + +### Custom Slide with State + +```vue + +``` + +## 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 index 5b75732..61d3211 100644 --- a/docs/index.md +++ b/docs/index.md @@ -36,5 +36,5 @@ meta: \ No newline at end of file diff --git a/docs/components/Features.vue b/docs/vue-components/Features.vue similarity index 100% rename from docs/components/Features.vue rename to docs/vue-components/Features.vue