@explorer-1/vue 0.3.6 → 0.3.8

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.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,5 +1,5 @@
 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,
@@ -21,21 +21,9 @@ export default {
     },
     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: {
-      description:
-        '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.',
-      control: { type: 'text' }
-    }
   }
 }
 
@@ -76,8 +64,7 @@ export const BaseStory = {
       objectFitClass: 'scaleDown',
       loading: ''
     },
-
-    noLogo: true,
+    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,4 +1,4 @@
-import BaseLink, { variants } from './BaseLink.vue'
+import BaseLink from './BaseLink.vue'
 export default {
   title: 'Components/Base/BaseLink',
   component: BaseLink,
@@ -8,54 +8,12 @@ export default {
     }
   },
   argTypes: {
-    variant: {
-      control: { type: 'select' },
-      options: Object.keys(variants),
-      description: 'Preset variants'
-    },
-    to: {
-      description: 'If populated, a router-link will be generated. Overrides `href`'
-    },
+    // JSDoc comments for these events aren't working, so we're setting them here
     linkClicked: {
-      type: '@click emit',
-      description: 'Event emitted at the root-level (globally available)'
+      description: 'Click event emitted at the root-level (globally available)'
     },
     specificLinkClicked: {
-      type: '@click emit',
-      description: 'Locally emitted event (includes event attributes)'
-    },
-    linkClass: {
-      description: 'Apply classes directly to the `<a>` element.'
-    },
-    externalTargetBlank: {
-      description: 'Autmatically sets target to `_blank` for external (non-router) links.'
-    },
-    exact: {
-      description:
-        "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."
-    },
-    usePrimaryColor: {
-      type: 'boolean',
-      description: "Overrides the theme's `active` color and uses the `primary` color instead."
-    },
-    caret: {
-      description:
-        'If a caret icon should be appended to the link. Set automatically when using the `primary` link variant.'
-    },
-    caretColor: {
-      control: { type: 'text' },
-      description: 'Tailwind text color class for the caret. Ex: `text-primary`'
-    },
-    caretWrapperClass: {
-      description: 'Add classes to the caret wrapper'
-    },
-    caretClass: {
-      description:
-        "Apply classes directly to the caret. Maps to `MixinAnimationCaret`'s `arrowClass` prop."
-    },
-    caretInline: { description: 'Apply `inline` class to the caret wrapper' },
-    caretMarginLeft: {
-      description: 'Customize the left margin of the caret using Tailwind classes.'
+      description: 'Locally emitted click event (includes event attributes)'
     }
   },
   excludeStories: /.*Data$/

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,28 +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 pill',
-      control: { type: 'select' },
-      options: ['primary', 'secondary', 'action']
-    },
-    size: {
-      type: { name: 'string', required: false },
-      description: 'The size of the pill',
-      control: { type: 'select' },
-      options: ['sm', 'md', 'lg']
-    },
-    contentType: {
-      control: { type: 'select' },
-      options: Object.keys(eduMetadataDictionary),
-      description: 'Maps to EDU Resource types. Must use `ThemeEdu` to have an effect.'
-    }
-  }
+  component: BasePill
 }
 
 // stories
@@ -31,7 +11,7 @@ export const PrimaryMedium = {
     size: 'md',
     variant: 'primary',
     text: 'Psyche Asteroid',
-    contentType: 'EDULessonPage'
+    contentType: undefined
   }
 }
 

package/src/components/BasePill/BasePill.vue

@@ -1,34 +1,53 @@
 <script setup lang="ts">
 import { computed } from 'vue'
-import type { Attributes } from './../../interfaces'
+import type { ContentTypeKey } from './../../interfaces.ts'
 import { eduMetadataDictionary } from './../../constants'
 
 // using borders to vertically center wonky font face
-const variantMap: Attributes = {
+const variantMap = {
   primary: 'bg-primary border-primary',
   'primary-inverted': 'bg-gray-light-mid !text-primary-darker border-gray-light-mid',
   secondary: 'bg-secondary border-secondary',
   action: 'bg-action border-action'
-}
+} as const
+type VariantMapKey = keyof typeof variantMap
 
-const sizeMap: Attributes = {
+const sizeMap = {
   sm: 'text-xs border-t-2 py-1 px-2.5',
   md: 'text-xs lg:text-base border-t py-1.5 px-3.5',
   lg: 'text-base lg:text-lg border-t pt-1.5 pb-1 px-5'
-}
+} as const
+type SizeMapKey = keyof typeof sizeMap
 
-interface BasePillProps {
-  text?: string
-  variant?: string
-  size?: string
-  contentType?: string
-}
-
-// define props
-const props = withDefaults(defineProps<BasePillProps>(), {
-  variant: 'primary',
-  size: 'md',
-  contentType: undefined
+const props = defineProps({
+  /**
+   * The text contained in the pill. Plain text only.
+   */
+  text: {
+    type: String,
+    default: undefined
+  },
+  /**
+   * The variant (color) of the pill
+   */
+  variant: {
+    type: String as () => VariantMapKey,
+    default: 'primary'
+  },
+  /**
+   * The size of the pill
+   */
+  size: {
+    type: String as () => SizeMapKey,
+    default: 'md'
+  },
+  /**
+   * Maps to EDU Resource types. Must use `ThemeEdu` to affect color.
+   */
+  contentType: {
+    type: String as () => ContentTypeKey,
+    default: undefined
+  }
 })
 
 const metadataType = computed(() => {

package/src/components/BasePlaceholder/BasePlaceholder.stories.js

@@ -4,18 +4,16 @@ export default {
   title: 'Components/Base/BasePlaceholder',
   component: BasePlaceholder,
   excludeStories: /.*Data$/,
+  tags: ['autodocs', 'listings'],
   parameters: {
     docs: {
       description: {
-        component: `An animated loading component frequently used as a placeholder for <a href="/story/components-search-searchresultcard--standard-result" target="_blank">SearchResultCard</a>`
+        component:
+          'An animated loading component frequently used as a placeholder for <a href="/story/components-search-searchresultcard--standard-result" target="_blank">SearchResultCard</a>'
       }
     }
   }
 }
-
-// shared data
-const BasePlaceholderData = {}
-
 // templates
 const BasePlaceholderTemplate = (args) => ({
   props: Object.keys(args),
@@ -24,5 +22,4 @@ const BasePlaceholderTemplate = (args) => ({
 })
 
 export const BaseStory = BasePlaceholderTemplate.bind({})
-BaseStory.storyName = 'BasePlaceholder' // single story hoisting
-BaseStory.args = { ...BasePlaceholderData }
+BaseStory.storyName = 'BasePlaceholder'

package/src/components/BasePlaceholder/BasePlaceholder.vue

@@ -19,7 +19,7 @@
 
 <script lang="ts">
 import { defineComponent } from 'vue'
-
+/** An animated loading component frequently used as a placeholder for <a href="/story/components-search-searchresultcard--standard-result" target="_blank">SearchResultCard</a> */
 export default defineComponent({
   name: 'BasePlaceholder'
 })

package/src/components/BaseRadioGroup/BaseRadioGroup.stories.js

@@ -3,6 +3,7 @@ import BaseRadioGroup from './BaseRadioGroup.vue'
 export default {
   title: 'Components/Base/BaseRadioGroup',
   component: BaseRadioGroup,
+  tags: ['autodocs', 'forms'],
   parameters: {
     docs: {
       description: {