@explorer-1/vue 0.3.4 → 0.3.7

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @explorer-1/vue
 
+## 0.3.7
+
+### Patch Changes
+
+- bc9dbbb: Documentation updates, Storybook improvements.
+
+## 0.3.6
+
+### Patch Changes
+
+- Updated dependencies [c307f7b]
+  - @explorer-1/common@1.3.3
+
+## 0.3.5
+
+### Patch Changes
+
+- 0a83db1: Documentation updates, Storybook improvements.
+
 ## 0.3.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorer-1/vue",
-  "version": "0.3.4",
+  "version": "0.3.7",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -31,7 +31,7 @@
     "vue-bind-once": "^0.2.1",
     "vue3-compare-image": "^1.2.5",
     "vue3-observe-visibility": "^1.0.1",
-    "@explorer-1/common": "1.3.2"
+    "@explorer-1/common": "1.3.3"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^5.0.4",

package/src/components/AboutTheAuthor/AboutTheAuthor.stories.js

@@ -3,7 +3,7 @@ import AboutTheAuthor from './AboutTheAuthor.vue'
 export default {
   title: 'Components/Utilities/AboutTheAuthor',
   component: AboutTheAuthor,
-  tags: ['!autodocs'],
+  tags: ['listings'],
   excludeStories: /.*Data$/
 }
 

package/src/components/AboutTheAuthor/AboutTheAuthor.vue

@@ -5,17 +5,17 @@ import BlockText from './../BlockText/BlockText.vue'
 import BaseImage from './../BaseImage/BaseImage.vue'
 import BaseImagePlaceholder from './../BaseImagePlaceholder/BaseImagePlaceholder.vue'
 
-interface AboutTheAuthorProps {
+const props = defineProps({
+  /**
+   * Array of keyed `{AuthorObject}s`
+   */
   authors: {
-    author?: AuthorObject
-  }[]
-}
-
-// define props
-const props = withDefaults(defineProps<AboutTheAuthorProps>(), {
-  authors: undefined
+    type: Array as () => {
+      author?: AuthorObject
+    }[],
+    default: () => []
+  }
 })
-
 const { authors } = reactive(props)
 
 const headingString = computed(() => {

package/src/components/AsteroidWatchWidget/AsteroidWatchWidget.stories.js

@@ -6,17 +6,12 @@ export default {
   excludeStories: /.*Data$/,
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="mt-20"><story/></div>`
+      template: `<div id="storyRoot" class="mt-20"><story/></div>`
     })
   ],
   parameters: {
     html: {
-      root: '#storyDecorator' // to omit decorators from html output
-    }
-  },
-  argTypes: {
-    status: {
-      control: { type: 'text' }
+      root: '#storyRoot' // to omit decorators from html output
     }
   }
 }

package/src/components/AsteroidWatchWidget/AsteroidWatchWidget.vue

@@ -140,9 +140,13 @@ export default defineComponent({
     BaseUnitToggle
   },
   props: {
+    /**
+     * Array of next close approaches (structure provided by backend)
+     */
     nextCloseApproaches: {
       type: Array as PropType<NextCloseApproach[]>,
-      required: false
+      required: false,
+      default: undefined
     }
   }
 })

package/src/components/BackToTop/BackToTop.stories.js

@@ -19,6 +19,6 @@ const BackToTopTemplate = (args) => ({
 export const BaseStory = BackToTopTemplate.bind({})
 BaseStory.storyName = 'BackToTop'
 BaseStory.args = {
-  threshhold: 300,
+  threshold: 300,
   scrollTo: 0
 }

package/src/components/BackToTop/BackToTop.vue

@@ -24,18 +24,28 @@ export default defineComponent({
     IconDropdown
   },
   props: {
+    /**
+     * Threshold (px) of when the button should appear
+     */
     threshold: {
       type: Number,
       required: false,
       default: 300
     },
+    /**
+     * Pixel offset when scrolling to the top
+     */
     scrollTo: {
       type: Number,
       required: false,
       default: 0
     }
   },
+  emits: ['click'],
   data(): {
+    /**
+     * Dynamically altered value that determines when the button should appear
+     */
     showBackToTop: Boolean
     scrollHandler: DebouncedFunc<() => void> | null
   } {

package/src/components/BaseAccordionItem/BaseAccordionItem.stories.js

@@ -1,15 +1,35 @@
 import BaseAccordionItem from './BaseAccordionItem.vue'
-import { BlockStreamfieldTruncatedData } from '../BlockStreamfield/BlockStreamfield.stories'
 export default {
   title: 'Components/Base/BaseAccordionItem',
-  component: BaseAccordionItem
+  component: BaseAccordionItem,
+  argTypes: {
+    // slots
+    header: {
+      control: false
+    },
+    heading: {
+      control: false
+    },
+    default: {
+      control: false
+    },
+    panelContents: {
+      control: false
+    }
+  }
 }
 
 // stories
 export const BaseStory = {
   name: 'BaseAccordionItem',
   args: {
-    headingLevel: 'h3',
-    item: { title: 'Title for the accordion', body: BlockStreamfieldTruncatedData.body }
+    headingLevel: 'h5',
+
+    item: {
+      title: 'Title for the accordion',
+      body: [{ text: 'No default body template. Customize with the `panelContents` slot.' }]
+    },
+
+    header: '<h3>Test</h3>'
   }
 }

package/src/components/BaseAccordionItem/BaseAccordionItem.vue

@@ -1,25 +1,32 @@
 <script setup lang="ts">
+/**
+ * Component that includes an accessible clickable header that will expand a panel below it
+ */
+
 import { computed, reactive, ref } from 'vue'
-import type { AccordionItemObject } from './../../interfaces.ts'
+import type { AccordionItemObject, HeadingLevels } from './../../interfaces.ts'
 import { uniqueId } from 'lodash'
 import IconPlus from './../Icons/IconPlus.vue'
 import IconMinus from './../Icons/IconMinus.vue'
 
-export interface BaseAccordionItemProps {
-  headingLevel?: string
-  item: AccordionItemObject
-  backgroundClass?: string
-}
-
-// define props
-const props = withDefaults(defineProps<BaseAccordionItemProps>(), {
-  headingLevel: 'h2',
-  backgroundClass: undefined,
-  item(): AccordionItemObject {
-    return {
-      title: undefined,
-      body: undefined
-    }
+const props = defineProps({
+  /**
+   * Semantic heading level
+   */
+  headingLevel: {
+    type: String as () => HeadingLevels,
+    default: 'h2'
+  },
+  /**
+   * Data object that includes all content that should be rendered in the accordion item
+   */
+  item: {
+    type: Object as () => AccordionItemObject,
+    default: () =>
+      ({
+        title: undefined,
+        body: undefined
+      }) as AccordionItemObject
   }
 })
 
@@ -37,6 +44,18 @@ const headingId = computed(() => {
   return `block_accordion_heading_${itemId.value}`
 })
 
+const emit = defineEmits([
+  /**
+   * Fires when an item is opened
+   * @type {thing}
+   */
+  'accordionItemOpened',
+  /**
+   * Fires when an item is closed
+   */
+  'accordionItemClosed'
+])
+
 const handleClick = () => {
   ariaExpanded.value = !ariaExpanded.value
   isHidden.value = !isHidden.value
@@ -47,7 +66,27 @@ const handleClick = () => {
   }
 }
 
-const emit = defineEmits(['accordionItemOpened', 'accordionItemClosed'])
+defineSlots<{
+  /**
+   * The entire clickable area of the item, including `heading`.
+   * Override with `<template #header>` and requires reconstructing `handleClick()` behavior.
+   */
+  header(): void
+  /**
+   * The heading text within the item header. Override with `<template #heading>`
+   */
+  heading(): void
+  /**
+   * The entire contents of expanded item, including `panelContents`.
+   * Override with `<template #default>` and requires reconstructing `aria-labelledby` attributes.
+   */
+  default(): void // Use 'void' as the return type
+  /**
+   * Contents of expanded accordion item. There is no default template.
+   * Override with `<template #panelContents>`
+   */
+  panelContents(): void
+}>()
 </script>
 <template>
   <div

package/src/components/BaseAudio/BaseAudio.stories.js

@@ -5,22 +5,20 @@ export default {
   component: BaseAudio,
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="bg-black p-4 pb-5"><story/></div>`
+      template: `<div id="storyRoot" class="bg-black p-4 pb-5"><story/></div>`
     })
   ],
   parameters: {
     html: {
-      root: '#storyDecorator'
+      root: '#storyRoot'
     }
   },
   excludeStories: /.*Data$/
 }
 
-// shared data
-export const BaseAudioData = {
+const BaseAudioData = {
   file: '/audio/file_example_MP3_700KB.mp3',
-  autoPlay: false,
-  loop: false
+  autoPlay: false
 }
 
 export const BaseStory = {

package/src/components/BaseAudio/BaseAudio.vue

@@ -152,11 +152,17 @@ export default defineComponent({
     IconForwardTen
   },
   props: {
+    /**
+     * Path to audio file
+     */
     file: {
       type: String,
       default: null
     },
     autoPlay: {
+      /**
+       * If audio should play automatically
+       */
       type: Boolean,
       default: false
     }

package/src/components/BaseButton/BaseButton.stories.ts

@@ -1,44 +1,32 @@
-import BaseButton, { variants } from './BaseButton.vue'
+import BaseButton from './BaseButton.vue'
 
 // TODO: add the rest of the button stories (icons, disabled, etc.)
 export default {
   title: 'Components/Base/BaseButton',
   component: BaseButton,
   excludeStories: /.*(Data)$/,
-  tags: ['autodocs'],
   parameters: {
     slots: {
-      default: 'BaseStory slot content'
+      default: 'The contents of the button, usually text. Override with `<template #default>`',
+      icon: 'Appears to the right of the `default` slot. Override with `<template #icon>`',
+      afterIcon: 'Appears to the right of the `icon` slot. Override with `<template #afterIcon>`'
     },
     docs: {
       description: {
-        component: 'Simple button with several style variations.'
+        component: 'Simple button with style variations.'
       }
-    }
-  },
-  argTypes: {
-    ariaLabel: {
-      type: 'string',
-      description:
-        "ARIA label. Recommended if your button label isn't descriptive, or if it only contains an icon."
     },
-    variant: {
-      type: 'string',
-      description: 'Button variant type',
-      control: {
-        type: 'select'
-      },
-      options: Object.keys(variants),
-      table: {
-        defaultValue: { summary: 'default' }
-      }
+    to: {
+      description: 'If populated, a router-link will be generated. Overrides `href`'
+    },
+    click: {
+      type: '@click emit'
     }
   }
 }
 
 export const BaseButtonData = {
-  label: 'Explore',
-  ariaLabel: 'Explore',
+  ariaLabel: 'Link to learn more',
   compact: false,
   disabled: false,
   to: '/',
@@ -63,4 +51,5 @@ export const DarkButton = {
     ...BaseButtonData,
     variant: 'dark'
   }
+  // globals: { themeVariant: 'ThemeVariantDark' }
 }

package/src/components/BaseButton/BaseButton.vue

@@ -1,51 +1,68 @@
 <script lang="ts">
-import { defineComponent, resolveComponent } from 'vue'
+import { defineComponent, resolveComponent, type PropType } from 'vue'
 
-interface Variants {
-  [key: string]: string
-}
-
-export const variants: Variants = {
+const variants = {
   primary: '-primary',
   secondary: '-secondary',
   dark: '-dark',
   social: '-social'
-}
+} as const
+type VariantsMapKey = keyof typeof variants
 
+/**
+ * Simple button with style variations. Can be either a true `<button>` element or a link.
+ */
 export default defineComponent({
   name: 'BaseButton',
   props: {
+    /**
+     * Button style variants
+     */
     variant: {
-      type: String,
+      type: String as PropType<VariantsMapKey>,
       required: false,
       default: 'primary',
       validator: (prop: string): boolean => Object.keys(variants).includes(prop)
     },
+    /** Removes extra left and right padding */
     compact: {
       type: Boolean,
       default: false,
       required: false
     },
+    /** Additional arbitrary classes to add to the button */
     blockClasses: {
       type: String,
       required: false,
       default: 'inline-block'
     },
+    /** If the button should render as disabled */
     disabled: {
       type: Boolean,
       default: false,
       required: false
     },
+    /**
+     * ARIA label. Recommended if your button text isn't descriptive, or if it only contains an icon.
+     */
     ariaLabel: {
       type: String,
       default: '',
       required: false
     },
+    /**
+     * If populated, a router-link will be generated. Overrides `href`.
+     * If both `to` and `href` are blank, a `<button>` element will be rendered.
+     * */
     to: {
       type: [String, Object],
       required: false,
       default: undefined
     },
+    /**
+     * Optional link for the button.
+     * If both `to` and `href` are blank, a `<button>` element will be rendered.
+     * */
     href: {
       type: String,
       required: false,
@@ -54,6 +71,9 @@ export default defineComponent({
   },
   emits: ['click'],
   computed: {
+    /**
+     * Whether the html element should be `<button>`, `<a>` or `<nuxt-link>`
+     */
     tag() {
       if (this.disabled) {
         return 'button'
@@ -65,6 +85,9 @@ export default defineComponent({
         return 'button'
       }
     },
+    /**
+     * Necessary for valid html. Guards for `<a>` or `<nuxt-link>` use-cases
+     */
     computedTo() {
       let toValue = this.to
       // filter out unnecessary `/home/` prefix from wagtail default site urlPaths
@@ -73,8 +96,9 @@ export default defineComponent({
       }
       return toValue
     },
-    // necessary for valid html
-    // must account for <a>, <nuxt-link>, and <button> use-cases
+    /**
+     * Necessary for valid html. Guards for `<a>` or `<nuxt-link>` use-cases
+     */
     theHref(): string | undefined {
       let href = undefined
       if (this.tag === 'a') {

package/src/components/BaseCheckboxGroup/BaseCheckboxGroup.stories.js

@@ -2,7 +2,8 @@ import BaseCheckboxGroup from './BaseCheckboxGroup.vue'
 
 export default {
   title: 'Components/Base/BaseCheckboxGroup',
-  component: BaseCheckboxGroup
+  component: BaseCheckboxGroup,
+  tags: ['forms']
 }
 
 // stories

package/src/components/BaseCheckboxGroup/BaseCheckboxGroup.vue

@@ -71,26 +71,31 @@ import type { FormOption } from '../../interfaces'
 export default defineComponent({
   name: 'BaseCheckboxGroup',
   props: {
+    /** iContact group id */
     group: {
       type: String,
       default: null,
       required: false
     },
+    /** Heading */
     heading: {
       type: String,
       default: null,
       required: false
     },
+    /** Descriptive text or summary */
     subHeading: {
       type: String,
       default: null,
       required: false
     },
+    /** Fieldset title, for screen readers */
     title: {
       type: String,
       default: null,
       required: false
     },
+    /** Array of `{FormOption}s` */
     options: {
       type: Array as PropType<FormOption[]>,
       default: null,

package/src/components/BaseHeading/BaseHeading.stories.js

@@ -6,24 +6,9 @@ import IconUser from './../Icons/IconUser.vue'
 export default {
   title: 'Components/Base/BaseHeading',
   component: BaseHeading,
-  argTypes: {
-    size: {
-      type: { name: 'string', required: true },
-      description: 'The display size of the heading.',
-      control: { type: 'select' },
-      options: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']
-    },
-    level: {
-      type: { name: 'string', required: false },
-      description:
-        'The semantic heading tag if different from the display size (ex: a heading looks like an `h4`, but semantically, it is an `h1`.',
-      control: { type: 'select' },
-      options: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']
-    }
-  },
   parameters: {
     slots: {
-      default: 'BaseStory slot content'
+      default: 'The contents of the heading, usually text. Override with `<template #default>`'
     },
     docs: {
       description: {
@@ -71,4 +56,11 @@ const TemplateHeadingsWithIcons = (args) => ({
 })
 
 export const HeadingsWithIcons = TemplateHeadingsWithIcons.bind({})
-HeadingsWithIcons.args = { size: 'h1', level: 'h1', default: 'Heading 1' }
+HeadingsWithIcons.args = { size: 'h3', level: 'h3', default: 'Heading 3 with Icon' }
+HeadingsWithIcons.parameters = {
+  docs: {
+    description: {
+      story: 'Example of overriding the default slot to include an icon component.'
+    }
+  }
+}

package/src/components/BaseHeading/BaseHeading.vue

@@ -1,29 +1,39 @@
 <script lang="ts">
-import { defineComponent } from 'vue'
-import type { Attributes } from './../../interfaces'
-import type { PropType } from 'vue'
+/** Base component for headings. Allows for retaining semantic markup while varying the text size. */
 
-export type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+import { defineComponent, type PropType } from 'vue'
 
-const headings: Attributes = {
+type HeadingAttributes = {
+  h1: string
+  h2: string
+  h3: string
+  h4: string
+  h5: string
+  h6: string
+}
+export type HeadingLevel = keyof HeadingAttributes
+
+const headings: HeadingAttributes = {
   h1: 'text-h1',
   h2: 'text-h2',
   h3: 'text-h3',
   h4: 'text-h4',
   h5: 'text-h5',
   h6: 'text-h6'
-}
+} as const
 
 export default defineComponent({
   name: 'BaseHeading',
   props: {
+    /** The semantic heading tag if different from the display size (ex: a heading needs to look like an `h4`, but semantically is an `h1`. */
     level: {
-      type: String as PropType<HeadingLevel | undefined>,
+      type: String as PropType<HeadingLevel>,
       required: false,
       default: 'h2'
     },
+    /** The display size of the heading */
     size: {
-      type: String as PropType<HeadingLevel | '' | undefined>,
+      type: String as PropType<HeadingLevel>,
       required: false,
       default: ''
     }