Merge pull request #44 from undone-labs/feat-tabbed-slider-docs

feat: tabbed slider docs
undone-labs · Oct 2, 2024 · 3d7b481 · 3d7b481
2 parents e9769ab + ab1b20f
commit 3d7b481
Show file tree

Hide file tree

Showing 2 changed files with 136 additions and 21 deletions.
diff --git a/packages/docs/content/zero-core/components/tabbed-slider.md b/packages/docs/content/zero-core/components/tabbed-slider.md
@@ -7,55 +7,101 @@ A slider component that is navigable through tabs corresponding to each slide.
 
 | Prop | type | description | values |
 | ---- | ---- | ----------- | ------ |
-| `id`<span>(optional)</span> | string | Specific slider ID that can be targetted with global $bus events | `small,medium,large` |
-| `slides` | object | Object keys used as slide IDs |  |
-| `defaultSlideIndex`<span>(optional)</span> | number | Set the default slide to be anything other than the first slide |  |
-| `animateHeight`<span>(optional)</span> | boolean | Choose to disable height animation |  |
+| `id`<span>(optional)</span> | string | Unique slider ID that can be targetted with global $bus events |  |
+| `slides` | object | An object whose keys are unique slide ID strings and corresponding values are slide objects containing data pertaining to its respective slide. |  |
+| `defaultSlideIndex`<span>(optional)</span> | number | Explicitly set the default slide by index. Defaults to 0, the first slide. |  |
+| `animateHeight`<span>(optional)</span> | boolean | Whether or not the slider should animate height as slides with differing heights slide into view. |  |
 | `fixedHeight`<span>(optional)</span> | boolean | A fixed-height slider's slides are set to `height: 100%`. Usually to allow for scrolling within a slide. |  |
 
+## Computed properties
+
+#### slugs()
+
+
+An array of unique slugs corresponding to each slide. Generated from the keys of the slides prop object.
+
+
+ - **returns:** `[string]`  
+
+#### count()
+
+
+Returns the number of slides.
+
+
+ - **returns:** `number`  
+
+#### currentSlideIndex()
+
+
+Returns the index of the currently selected slide.
+
+
+ - **returns:** `number`  
+
+#### currentSlide()
+
+
+Returns an object containing the slug/id of the newly selected slide and its data at the moment the slide is selected.
+
+
+ - **returns:** `{ slug: string, data: Object }`  
+
 ## Slots
 
 #### Before Track
 
 
 **name:** `before-track`  **scoped:** `true`
 
+
+Can be used to add control elements before the slides.
+
 | binding | type | description |
 | ------- | ---- | ----------- |
-| `change-slide` |  |  |
-| `current-slide` |  |  |
+| `change-slide` | `func` | Binds the [changeSlide](/zero-core/components/tabbed-slider#changeslide) method. |
+| `current-slide` | `func` | Binds the [currentSlide](/zero-core/components/tabbed-slider#currentslide) computed property. |
 
 #### Key
 
 
 **name:** `key`  **scoped:** `true`
 
+
+Content to inject into each slide. Should be generated from an array of slides.
+
 | binding | type | description |
 | ------- | ---- | ----------- |
-| `name` |  |  |
-| `data` |  |  |
-| `change-slide` |  |  |
-| `active` |  |  |
+| `name` | `string` | The name of each indiviudal slide slot. Keys from the slides prop will be used for these values. |
+| `data` | `Object` | The slide data object of each slide. |
+| `change-slide` | `func` | Binds the [changeSlide](/zero-core/components/tabbed-slider#changeslide) method. |
+| `active` | `boolean` | Whether or not this slide is currently selected. |
 
 #### After Track
 
 
 **name:** `after-track`  **scoped:** `true`
 
+
+Can be used to add control elements after the slides.
+
 | binding | type | description |
 | ------- | ---- | ----------- |
-| `change-slide` |  |  |
-| `current-slide` |  |  |
+| `change-slide` | `func` | Binds the [changeSlide](/zero-core/components/tabbed-slider#changeslide) method. |
+| `current-slide` | `func` | Binds the [currentSlide](/zero-core/components/tabbed-slider#currentslide) computed property. |
 
 ## Emitters
 
 
- - **slideChanged** - undefined
+ - **slideChanged** - returns: `{ slug: string, data: Object }` - Emits the new value returned by [currentSlide](/zero-core/components/tabbed-slider#currentslide) right after the slide is changed.
 
 ## Methods
 
 #### setPanelHeight()
 
+
+Sets the new height of the slider track if the `animateHeight` prop is enabled.
+
 #### changeSlide()
 
 
@@ -67,4 +113,20 @@ Changes the current slide.
 
 #### handleChangeSlideBusEvent()
 
+
+Calls the [changeSlide](/zero-core/components/tabbed-slider#changeslide) method when the `ZeroTabbedSlider__changeSlide` bus event is fired via [$bus](/zero-core/plugins#bus).
+
+| param | type | description |
+| ----- | ---- | ----------- |
+| `payload` | Object | Slide data. |
+| `payload.id` | string | The ID of the slider. Must match the `id` prop of this component. |
+| `payload.slug` | string | The slug/id of the slide to set to active. Must be one of the keys in the `slides` prop. |
+
 #### handleResetHeightBusEvent()
+
+
+Calls the [setPanelHeight](/zero-core/components/tabbed-slider#setpanelheight) method when the `ZeroTabbedSlider__resetHeight` bus event is fired via [$bus](/zero-core/plugins#bus).
+
+| param | type | description |
+| ----- | ---- | ----------- |
+| `id` | string | The ID of the slider. Must match the `id` prop of this component. |
diff --git a/packages/zero-core/components/tabbed-slider.vue b/packages/zero-core/components/tabbed-slider.vue
@@ -2,6 +2,11 @@
   <div :class="['tabbed-slider', { 'fixed-height': fixedHeight }]">
 
     <!-- ====================================================== before track -->
+     <!-- 
+      @slot Can be used to add control elements before the slides.
+        @binding {func} change-slide Binds the [changeSlide](/zero-core/components/tabbed-slider#changeslide) method.
+        @binding {func} current-slide Binds the [currentSlide](/zero-core/components/tabbed-slider#currentslide) computed property.
+    -->
     <slot
       name="before-track"
       :change-slide="changeSlide"
@@ -29,6 +34,13 @@
           ref="slideRefs"
           class="slide">
           <!-- slide content -->
+          <!--
+            @slot Content to inject into each slide. Should be generated from an array of slides.
+              @binding {string} name The name of each indiviudal slide slot. Keys from the slides prop will be used for these values.
+              @binding {Object} data The slide data object of each slide.
+              @binding {func} change-slide Binds the [changeSlide](/zero-core/components/tabbed-slider#changeslide) method.
+              @binding {boolean} active Whether or not this slide is currently selected.
+          -->
           <slot
             :name="key"
             :data="slide"
@@ -39,6 +51,11 @@
     </div>
 
     <!-- ======================================================= after track -->
+    <!-- 
+      @slot Can be used to add control elements after the slides.
+        @binding {func} change-slide Binds the [changeSlide](/zero-core/components/tabbed-slider#changeslide) method.
+        @binding {func} current-slide Binds the [currentSlide](/zero-core/components/tabbed-slider#currentslide) computed property.
+    -->
     <slot
       name="after-track"
       :change-slide="changeSlide"
@@ -54,31 +71,30 @@
 // ======================================================================= Setup
 const props = defineProps({
   /**
-   * Specific slider ID that can be targetted with global $bus events
-   * @values small, medium, large
+   * Unique slider ID that can be targetted with global $bus events
    */
   id: {
     type: String,
     required: false,
     default: ''
   },
   /**
-   * Object keys used as slide IDs
+   * An object whose keys are unique slide ID strings and corresponding values are slide objects containing data pertaining to its respective slide.
    */
   slides: {
     type: Object,
     required: true
   },
   /**
-   * Set the default slide to be anything other than the first slide
+   * Explicitly set the default slide by index. Defaults to 0, the first slide.
    */
   defaultSlideIndex: {
     type: Number,
     required: false,
     default: 0
   },
   /**
-   * Choose to disable height animation
+   * Whether or not the slider should animate height as slides with differing heights slide into view.
    */
   animateHeight: {
     type: Boolean,
@@ -100,17 +116,47 @@ const slideRefs = ref(null)
 const activeSlide = ref(Object.keys(props.slides)[props.defaultSlideIndex])
 const activeSlideHeight = ref(null)
 
-const emit = defineEmits(['slideChanged'])
+const emit = defineEmits([
+  /**
+   * Emits the new value returned by [currentSlide](/zero-core/components/tabbed-slider#currentslide) right after the slide is changed.
+   * @returns {{ slug: string, data: Object }}
+   */
+  'slideChanged'
+])
 
 const { $bus } = useNuxtApp()
 
 // ==================================================================== Computed
 /**
- * A list of slugs corresponding to each slide
+ * @method slugs
+ * @computed
+ * @desc An array of unique slugs corresponding to each slide. Generated from the keys of the slides prop object.
+ * @returns {[string]}
  */
 const slugs = computed(() => Object.keys(props.slides))
+
+/**
+ * @method count
+ * @computed
+ * @desc Returns the number of slides.
+ * @returns {number}
+ */
 const count = computed(() => slugs.value.length)
+
+/**
+ * @method currentSlideIndex
+ * @computed
+ * @desc Returns the index of the currently selected slide.
+ * @returns {number}
+ */
 const currentSlideIndex = computed(() => slugs.value.indexOf(activeSlide.value))
+
+/**
+ * @method currentSlide
+ * @computed
+ * @desc Returns an object containing the slug/id of the newly selected slide and its data at the moment the slide is selected.
+ * @returns {{ slug: string, data: Object }}
+ */
 const currentSlide = computed(() => {
   const slug = activeSlide.value
   return {
@@ -129,6 +175,7 @@ watch(activeSlide, async slug => {
 // ===================================================================== Methods
 /**
  * @method setPanelHeight
+ * @desc Sets the new height of the slider track if the `animateHeight` prop is enabled.
  */
 
 const setPanelHeight = () => {
@@ -139,7 +186,7 @@ const setPanelHeight = () => {
 
 /**
  * @method changeSlide - Changes the current slide.
- * @desc - Changes the current slide.
+ * @desc - Changes the current slide. Emits the [currentSlide](/zero-core/components/tabbed-slider#currentslide) value.
  * @param {string} slug - The slug of the slide to switch to.
  */
 
@@ -150,6 +197,10 @@ const changeSlide = slug => {
 
 /**
  * @method handleChangeSlideBusEvent
+ * @desc Calls the [changeSlide](/zero-core/components/tabbed-slider#changeslide) method when the `ZeroTabbedSlider__changeSlide` bus event is fired via [$bus](/zero-core/plugins#bus).
+ * @param {Object} payload Slide data.
+ * @param {string} payload.id The ID of the slider. Must match the `id` prop of this component.
+ * @param {string} payload.slug The slug/id of the slide to set to active. Must be one of the keys in the `slides` prop.
  */
 
 const handleChangeSlideBusEvent = payload => {
@@ -159,6 +210,8 @@ const handleChangeSlideBusEvent = payload => {
 
 /**
  * @method handleResetHeightBusEvent
+ * @desc Calls the [setPanelHeight](/zero-core/components/tabbed-slider#setpanelheight) method when the `ZeroTabbedSlider__resetHeight` bus event is fired via [$bus](/zero-core/plugins#bus).
+ * @param {string} id The ID of the slider. Must match the `id` prop of this component.
  */
 
 const handleResetHeightBusEvent = id => {