@explorer-1/vue 0.3.4 → 0.3.7

package/src/components/BaseImage/BaseImage.stories.ts

@@ -1,22 +1,17 @@
-import BaseImage, { objectFitClasses } from './BaseImage.vue'
+import BaseImage from './BaseImage.vue'
 export default {
   title: 'Components/Base/BaseImage',
   component: BaseImage,
   excludeStories: /.*Data$/,
-  argTypes: {
-    objectFitClass: {
-      description:
-        'Use Tailwind CSS object fit classes to specify how the image will scale within `BaseImagePlaceholder`',
-      control: { type: 'select' },
-      options: Object.keys(objectFitClasses)
-    }
-  },
   parameters: {
     docs: {
       description: {
         component:
           'The BaseImage component is a simple `<img />` tag wrapped in a `<div>` and is used to render an image with object-fit classes and lazy loading properties.'
       }
+    },
+    html: {
+      root: '#storyRoot'
     }
   }
 }
@@ -33,7 +28,7 @@ export const BaseImageData = {
 // stories
 export const BaseStory = {
   args: BaseImageData,
-  decorators: [() => ({ template: '<div class="max-w-full"><story /></div>' })]
+  decorators: [() => ({ template: '<div id="storyRoot" class="max-w-full"><story /></div>' })]
 }
 
 export const LazyLoading = {
@@ -41,12 +36,7 @@ export const LazyLoading = {
   decorators: [
     () => ({
       template:
-        '<div class="max-w-full"><div style="height:3500px">Scroll down and watch the network tab ⬇️</div><div id="storyRoot"><story /></div></div>'
+        '<div class="max-w-full"><div style="height:3500px">Scroll down and watch the network tab ⬇️</div><div id="storyDecorator"><story /></div></div>'
     })
-  ],
-  parameters: {
-    html: {
-      root: '#storyRoot'
-    }
-  }
+  ]
 }

package/src/components/BaseImage/BaseImage.vue

@@ -1,52 +1,64 @@
 <script lang="ts">
-import { defineComponent } from 'vue'
-import type { PropType } from 'vue'
+/**
+ * The BaseImage component is a simple `<img />` tag wrapped in a `<div>`
+ * and is used to render an image with object-fit classes and lazy loading properties.
+ */
 
-export type ImageLoader = 'lazy' | 'eager' | undefined
+import { defineComponent, type PropType } from 'vue'
 
-interface ObjectFitClasses {
-  [key: string]: string
-}
-
-export const objectFitClasses: ObjectFitClasses = {
+type ImageLoader = 'lazy' | 'eager' | undefined
+const objectFitClasses = {
   none: 'object-none',
   contain: 'object-contain',
   cover: 'object-cover',
   fill: 'object-fill',
   scaleDown: 'object-scale-down'
-}
+} as const
+type ObjectFitClassesKey = keyof typeof objectFitClasses
 
 export default defineComponent({
   name: 'BaseImage',
   props: {
+    /** CSS classes to apply directory to the `<img>` element */
     imageClass: {
       type: String,
-      required: false
+      required: false,
+      default: ''
     },
+    /** Tailwind CSS object fit classes to specify how the image will scale within `BaseImagePlaceholder` */
     objectFitClass: {
-      type: String,
+      type: String as PropType<ObjectFitClassesKey>,
       required: false,
       default: 'contain',
       validator: (prop: string): boolean => Object.keys(objectFitClasses).includes(prop)
     },
+    /** `<img> src` attribute */
     src: {
       type: String,
       required: true
     },
+    /** `<img> srcset` attribute  */
     srcset: {
       type: String,
       required: false,
       default: ''
     },
+    /** `<img> alt` attribute */
     alt: {
-      type: String
+      type: String,
+      default: ''
     },
+    /** `<img> width` attribute */
     width: {
-      type: [Number, String]
+      type: [Number, String],
+      default: ''
     },
+    /** `<img> height` attribute */
     height: {
-      type: [Number, String]
+      type: [Number, String],
+      default: ''
     },
+    /** `<img> loading` attribute */
     loading: {
       type: String as PropType<ImageLoader>,
       required: false,

package/src/components/BaseImageCaption/BaseImageCaption.stories.js

@@ -9,6 +9,17 @@ export default {
         component: 'Caption text used with both images and videos.'
       }
     }
+  },
+  argTypes: {
+    customLink: {
+      type: 'string',
+      description:
+        'Appends a link to the end of the caption. Overrides "Full Image Details" link, if it exists.'
+    },
+    customLinkText: {
+      type: 'string',
+      description: 'Text for the custom link.'
+    }
   }
 }
 

package/src/components/BaseImageCaption/BaseImageCaption.vue

@@ -1,7 +1,8 @@
 <script lang="ts">
-import { defineComponent } from 'vue'
-import type { PropType } from 'vue'
-import type { ImageObject } from '../../interfaces'
+/** Caption text used with both images and videos. */
+
+import { defineComponent, type PropType } from 'vue'
+import type { ImageObject, VideoObject } from '../../interfaces'
 import BaseLink from './../BaseLink/BaseLink.vue'
 
 export default defineComponent({
@@ -10,15 +11,18 @@ export default defineComponent({
     BaseLink
   },
   props: {
+    /** `{ImageObject}` data */
     data: {
-      type: Object as PropType<Partial<ImageObject>>,
-      required: true,
-      default: undefined
+      // type: Object as PropType<<PartialImageObject>>,
+      type: Object as PropType<Partial<ImageObject> | Partial<VideoObject> | any>,
+      required: true
     },
+    /** Appends a link to the end of the caption. Overrides "Full Image Details" link, if it exists. */
     customLink: {
       type: String,
       default: undefined
     },
+    /** Text for the custom link. Does not appear if `customLink` is blank */
     customLinkText: {
       type: String,
       default: 'Custom Link'

package/src/components/BaseImagePlaceholder/BaseImagePlaceholder.stories.js

@@ -1,11 +1,11 @@
 import BaseImage from './../BaseImage/BaseImage.vue'
-import BaseImagePlaceholder, { aspectRatios } from './BaseImagePlaceholder.vue'
+import BaseImagePlaceholder from './BaseImagePlaceholder.vue'
 export default {
   title: 'Components/Base/BaseImagePlaceholder',
   component: BaseImagePlaceholder,
   excludeStories: /.*Data$/,
   decorators: () => ({
-    template: '<div class="w-2/3"><story /></div>'
+    template: '<div id="storyRoot" class="w-3/4"><story /></div>'
   }),
   tags: ['autodocs'],
   parameters: {
@@ -16,21 +16,14 @@ export default {
         template: `<BaseImage :object-fit-class="args.BaseImageProps.objectFitClass" :loading="args.BaseImageProps.loading" :src="args.BaseImageProps.src" :srcset="args.BaseImageProps.srcset" :alt="args.BaseImageProps.alt" :width="args.BaseImageProps.width" :height="args.BaseImageProps.height" />`
       }
     },
+    html: {
+      root: '#storyRoot'
+    },
     docs: {
       description: {
-        component:
-          'Aspect ratio CSS class. View dropdown to see all options. More classes can be added in `/src/scss/_aspect-ratios.scss`'
+        component: 'Placeholder image component with aspect ratio and background controls'
       }
     }
-  },
-  argTypes: {
-    aspectRatio: {
-      control: { type: 'select' },
-      options: Object.keys(aspectRatios)
-    },
-    responsiveAspectRatio: {
-      control: { type: 'text' }
-    }
   }
 }
 
@@ -38,7 +31,8 @@ export default {
 export const BaseImagePlaceholderData = {
   aspectRatio: '12:9',
   darkMode: true,
-  transparentMode: false
+  transparentMode: false,
+  noLogo: false
 }
 
 export const WithImage = {
@@ -60,6 +54,7 @@ export const BaseStory = {
   name: 'No Image',
   args: {
     ...BaseImagePlaceholderData,
+
     BaseImageProps: {
       src: '',
       srcset: '',
@@ -68,6 +63,9 @@ export const BaseStory = {
       height: '',
       objectFitClass: 'scaleDown',
       loading: ''
-    }
+    },
+    noLogo: false,
+    aspectRatio: '16:9',
+    responsiveAspectRatio: 'md:aspect-ratio-four-three lg:aspect-ratio-twelve-nine'
   }
 }

package/src/components/BaseImagePlaceholder/BaseImagePlaceholder.vue

@@ -1,11 +1,8 @@
 <script lang="ts">
-import { defineComponent } from 'vue'
+import { defineComponent, type PropType } from 'vue'
+/** Placeholder image component with aspect ratio and background controls */
 
-interface AspectRatios {
-  [key: string]: string
-}
-
-export const aspectRatios: AspectRatios = {
+export const aspectRatios = {
   none: 'aspect-ratio-none',
   portrait: 'aspect-ratio-four-five',
   square: 'aspect-ratio-square',
@@ -22,33 +19,40 @@ export const aspectRatios: AspectRatios = {
   '16:7': 'aspect-ratio-sixteen-seven',
   '16:9': 'aspect-ratio-sixteen-nine',
   '21:9': 'aspect-ratio-twentyone-nine'
-}
+} as const
+type AspectRatiosKey = keyof typeof aspectRatios
 
 export default defineComponent({
   name: 'BaseImagePlaceholder',
   props: {
+    /** If the placeholder background should be dark */
     darkMode: {
       type: Boolean,
       required: false,
       default: true
     },
+    /** If the placeholder background should be transparent (ovverrides `darkMode`) */
     transparentMode: {
       type: Boolean,
       required: false,
       default: false
     },
+    /** If the JPL logo should not appear in the background of the placeholder */
     noLogo: {
       type: Boolean,
       default: false
     },
+    /** Desired aspect ratio of image. If the contained image doesn't match, it will be adjusted to fit within the selected aspect ratio */
     aspectRatio: {
-      type: String,
+      type: String as PropType<AspectRatiosKey>,
       default: 'none',
       validator: (prop: string): boolean => Object.keys(aspectRatios).includes(prop)
     },
+    /** Custom tailwind classes to combine screen-size directives with aspect ratios.
+     * Example: `md:aspect-ratio-four-three lg:aspect-ratio-twelve-nine`. Overrides `aspectRatio` setting. */
     responsiveAspectRatio: {
       type: String,
-      required: false
+      default: ''
     }
   },
   computed: {

package/src/components/BaseLink/BaseLink.stories.js

@@ -1,16 +1,19 @@
-import BaseLink, { variants } from './BaseLink.vue'
+import BaseLink from './BaseLink.vue'
 export default {
   title: 'Components/Base/BaseLink',
   component: BaseLink,
   parameters: {
     slots: {
-      default: 'BaseStory slot content'
+      default: 'Text or markup contained in the link'
     }
   },
   argTypes: {
-    variant: {
-      control: { type: 'select' },
-      options: Object.keys(variants)
+    // JSDoc comments for these events aren't working, so we're setting them here
+    linkClicked: {
+      description: 'Click event emitted at the root-level (globally available)'
+    },
+    specificLinkClicked: {
+      description: 'Locally emitted click event (includes event attributes)'
     }
   },
   excludeStories: /.*Data$/
@@ -21,8 +24,6 @@ export const BaseLinkData = {
   variant: 'primary',
   to: '/',
   href: '/',
-  caret: false,
-  caretColor: 'text-primary',
   default: 'Link Text'
 }
 

package/src/components/BaseLink/BaseLink.vue

@@ -1,46 +1,47 @@
 <script lang="ts">
-import { defineComponent } from 'vue'
+import { defineComponent, type PropType } from 'vue'
 import { mapStores } from 'pinia'
 import { useThemeStore } from '../../store/theme'
 import { eventBus } from './../../utils/eventBus'
 import MixinAnimationCaret from './../MixinAnimationCaret/MixinAnimationCaret.vue'
 import { isEduExternalLink } from './../../utils/isEduExternalLink'
 
-interface Variants {
-  [key: string]: string
-}
-
-export const variants: Variants = {
+const variants = {
   primary: 'text-subtitle text-action can-hover:hover:text-action-dark',
   secondary: 'text-subtitle text-action can-hover:hover:text-action-dark',
   default: '-default underline text-action can-hover:hover:text-action-dark',
   none: ''
-}
-export const primaryColorVariants: Variants = {
+} as const
+type VariantsKey = keyof typeof variants
+
+const primaryColorVariants = {
   primary: 'text-subtitle text-primary can-hover:hover:text-primary-dark',
   secondary: 'text-subtitle text-primary can-hover:hover:text-primary-dark',
   default: '-default underline text-primary can-hover:hover:text-primary-dark',
   none: ''
-}
+} as const
 
 export default defineComponent({
-  // this component is useful when you need a link that can either be an 'a' or router link
-  // falls back to a <div> if no url is provided
+  /**  this component is useful when you need a link that can either be an 'a' or router link.
+   * falls back to a <div> if no url is provided
+   */
   name: 'BaseLink',
   components: {
     MixinAnimationCaret
   },
   props: {
     variant: {
-      type: String,
+      type: String as PropType<VariantsKey>,
       required: false,
       default: 'default',
       validator: (prop: string): boolean => Object.keys(variants).includes(prop)
     },
+    /** If populated, a router-link will be generated. Overrides `href` */
     to: {
       type: [String, Object],
       default: undefined
     },
+    /** Maps to the `exact` prop in Nuxt's native `NuxtLink` component. If `true`, `active-class` will be applied to the link only if the current path is an exact match. Only affects router links. */
     exact: {
       type: Boolean,
       default: false
@@ -57,65 +58,73 @@ export default defineComponent({
       type: String,
       default: ''
     },
+    /** Apply classes directly to the `<a>` element */
     linkClass: {
       type: String,
       default: ''
     },
-    // this will always override the target
+    /** This setting will always override the target, regardless of external link settings */
     target: {
       type: String,
       required: false,
       default: undefined
     },
-    // if external links should open in a new window
+    /** Autmatically sets target to `_blank` for external (non-router) links */
     externalTargetBlank: {
       type: Boolean,
       required: false,
       default: false
     },
-    // the 'primary' variant will always have the caret
+    /** 'If a caret icon should be appended to the link. Set automatically when using the `primary` link variant. */
     caret: {
       type: Boolean,
       required: false,
       default: false
     },
-    // Class applied to the overall MixinAnimationCaret component
+    /** Add classes to the caret wrapper */
     caretWrapperClass: {
       type: String,
       default: ''
     },
-    // Class applied to the caret itself
+    /** Add classes directly to the caret. Maps to `MixinAnimationCaret`'s `arrowClass` prop. */
     caretClass: {
       type: String,
       default: ''
     },
-    // if caret should be displayed inline with text
+    /** Apply `inline` class to the caret wrapper */
     caretInline: {
       type: Boolean,
       required: false,
       default: false
     },
-    // to customize the caret color. also works with group-hover
+    /** Tailwind CSS text color class for the caret. Ex: `text-primary` */
     caretColor: {
       type: String,
       required: false,
       default: ''
     },
+    /** Customize the left margin of the caret using Tailwind classes */
     caretMarginLeft: {
       type: String,
       required: false,
       default: ''
     },
+    /** Overrides the theme's `active` color and uses the `primary` color instead. */
     usePrimaryColor: {
       type: Boolean,
       required: false,
       default: false
     }
   },
-  emits: ['linkClicked', 'specificLinkClicked'],
+  emits: [
+    /** Apply classes directly to the `<a>` element. */
+    'linkClicked',
+    /** Locally emitted click event (includes event attributes) */
+    'specificLinkClicked'
+  ],
   computed: {
     ...mapStores(useThemeStore),
-    computedVariants(): Variants {
+    computedVariants() {
       if (this.usePrimaryColor) {
         return primaryColorVariants
       }
@@ -131,12 +140,14 @@ export default defineComponent({
       }
       return classes
     },
+    /** If the href link is an external link relative to the EDU site  */
     isEduExternal(): boolean | string {
       if (this.href) {
         return isEduExternalLink(this.href)
       }
       return ''
     },
+    /** If the href is an external link (takes theme and `isEduExternal` into account) */
     isExternal(): boolean {
       if (this.href) {
         if (this.themeStore.isEdu && isEduExternalLink(this.href)) {

package/src/components/BaseModal/BaseModal.stories.js

@@ -5,9 +5,6 @@ import BaseModalDialog from './BaseModalDialog.vue'
 export default {
   title: 'Components/Base/BaseModal',
   component: BaseModal,
-  argTypes: {
-    bgClose: { control: { type: 'boolean' } }
-  },
   excludeStories: /.*Data$/
 }
 
@@ -15,7 +12,7 @@ export default {
 const BaseModalTemplate = (args) => ({
   props: Object.keys(args),
   components: { BaseModal },
-  template: `<BaseModal :bg-close="bgClose"><div>Modal content. Lorem ipsum dolor sit amet.</div></BaseModal>`
+  template: `<BaseModal :bg-close="bgClose"><div>{{ bgClose }} Modal content. Lorem ipsum dolor sit amet.</div></BaseModal>`
 })
 const BaseModalWithTriggerTemplate = (args) => ({
   props: Object.keys(args),
@@ -72,13 +69,13 @@ export const BaseModalDialogData = {
 
 // stories
 export const BaseStory = BaseModalTemplate.bind({})
-BaseStory.args = { ...BaseModalData }
+BaseStory.args = BaseModalData
 
 export const CustomTrigger = BaseModalWithTriggerTemplate.bind({})
-CustomTrigger.args = { ...BaseModalData }
+CustomTrigger.args = BaseModalData
 
 export const Nested = BaseModalNested.bind({})
-Nested.args = { ...BaseModalData }
+Nested.args = BaseModalData
 
 export const Dialog = BaseModalDialogTemplate.bind({})
 Dialog.args = { ...BaseModalDialogData, modalHeaderSlot: '' }

package/src/components/BaseModal/BaseModal.vue

@@ -26,6 +26,7 @@ export default defineComponent({
     BaseModalDialog
   },
   props: {
+    /** If clicking on the background should close the modal. Note: doesn't have an affect within Storybook */
     bgClose: {
       type: Boolean,
       default: false

package/src/components/BaseModal/BaseModalDialog.vue

@@ -1,7 +1,7 @@
 <template>
   <div
     class="bg-gray-dark fixed top-0 left-0 z-50 flex w-full h-full overflow-auto bg-opacity-75"
-    @click="bgCloseModal"
+    @click="bgClose ? closeModal() : null"
   >
     <div
       class="relative w-full p-8 m-auto bg-white"
@@ -54,11 +54,6 @@ export default defineComponent({
   methods: {
     closeModal() {
       this.$emit('close')
-    },
-    bgCloseModal() {
-      if (this.bgClose) {
-        this.closeModal()
-      }
     }
   }
 })

package/src/components/BasePill/BasePill.stories.js

@@ -1,27 +1,8 @@
 import BasePill from './BasePill.vue'
-import { eduMetadataDictionary } from './../../constants'
 
 export default {
   title: 'Components/Base/BasePill',
-  component: BasePill,
-  argTypes: {
-    variant: {
-      type: { name: 'string', required: false },
-      description: 'The variant (color) of the tag',
-      control: { type: 'select' },
-      options: ['primary', 'secondary', 'action']
-    },
-    size: {
-      type: { name: 'string', required: false },
-      description: 'The size of the tag',
-      control: { type: 'select' },
-      options: ['sm', 'md', 'lg']
-    },
-    contentType: {
-      control: { type: 'select' },
-      options: Object.keys(eduMetadataDictionary)
-    }
-  }
+  component: BasePill
 }
 
 // stories
@@ -30,7 +11,7 @@ export const PrimaryMedium = {
     size: 'md',
     variant: 'primary',
     text: 'Psyche Asteroid',
-    contentType: 'EDULessonPage'
+    contentType: undefined
   }
 }
 
@@ -39,5 +20,10 @@ export const SecondarySmall = {
 }
 
 export const WithType = {
-  args: { size: 'sm', variant: 'secondary', text: 'Do it yourself' }
+  args: {
+    size: 'sm',
+    variant: 'primary',
+    text: 'Student Project',
+    contentType: 'EDUStudentProjectPage'
+  }
 }