@explorer-1/vue 0.3.4 → 0.3.7

package/src/components/BlockImage/BlockImage.vue

@@ -1,5 +1,7 @@
 <script lang="ts">
-import { defineComponent } from 'vue'
+/** The combination of BaseImage and BaseImageCaption, plus adding support for expanding the image in a lightbox and styling it to be a full-bleed image. */
+import { defineComponent, type PropType } from 'vue'
+import type { ImageBlock } from './../../interfaces'
 import BlockImageStandard from './BlockImageStandard.vue'
 import BlockImageFullBleed from './BlockImageFullBleed.vue'
 import LayoutHelper from './../LayoutHelper/LayoutHelper.vue'
@@ -13,9 +15,10 @@ export default defineComponent({
   },
   props: {
     data: {
-      type: Object,
+      type: Object as PropType<ImageBlock>,
       required: false
     },
+    /** If image should be the full width of the container */
     fullBleed: {
       type: Boolean,
       required: false,

package/src/components/BlockImageCarousel/BlockImageCarousel.stories.js

@@ -3,27 +3,15 @@ import BlockImageCarousel from './BlockImageCarousel.vue'
 export default {
   title: 'Components/Blocks/BlockImageCarousel',
   component: BlockImageCarousel,
+  tags: ['autodocs', 'wagtail-blocks', 'carousels'],
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="container"><story/></div>`
+      template: `<div id="storyRoot" class="container"><story/></div>`
     })
   ],
-  argTypes: {
-    blockId: {
-      text: { type: 'string' },
-      required: false,
-      description:
-        'Fancybox: the block id is used to differentiate the fancybox of this carousel from others on the page. Generated by Wagtail.'
-    },
-    showTitle: {
-      text: { type: 'string' },
-      required: false,
-      description: "Fancybox: if image titles should be displayed in the carousel's fancybox"
-    }
-  },
   parameters: {
     html: {
-      root: '#storyDecorator'
+      root: '#storyRoot'
     }
   },
   excludeStories: /.*Data$/

package/src/components/BlockImageCarousel/BlockImageCarousel.vue

@@ -101,10 +101,12 @@ export default defineComponent({
       type: Number,
       required: false
     },
+    /** Fancybox: the block id is used to differentiate the fancybox of this carousel from others on the page. Generated by Wagtail. */
     blockId: {
       type: String,
       required: false
     },
+    /** Fancybox: if image titles should be displayed in the carousel's fancybox */
     showTitle: {
       type: Boolean,
       required: false,

package/src/components/BlockImageCarouselItem/BlockImageCarouselItem.stories.js

@@ -5,26 +5,12 @@ export default {
   component: BlockImageCarouselItem,
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="container mx-auto"><story/></div>`
+      template: `<div id="storyRoot" class="container mx-auto"><story/></div>`
     })
   ],
-  argTypes: {
-    blockId: {
-      text: { type: 'string' },
-      required: false,
-      description:
-        'Fancybox: the block id is used to differentiate the fancybox of the items in a carousel from other carousels on the page. Generated by Wagtail. Usually provided by parent component `BlockImageCarousel`.'
-    },
-    showTitle: {
-      text: { type: 'string' },
-      required: false,
-      description:
-        "Fancybox: if the image title should be displayed in the item's fancybox. Usually provided by parent component `BlockImageCarousel`."
-    }
-  },
   parameters: {
     html: {
-      root: '#storyDecorator'
+      root: '#storyRoot'
     }
   },
   excludeStories: /.*Data$/

package/src/components/BlockImageCarouselItem/BlockImageCarouselItem.vue

@@ -41,7 +41,7 @@
   </div>
 </template>
 <script lang="ts">
-import { defineComponent } from 'vue'
+import { defineComponent, type PropType } from 'vue'
 import type { ImageObject } from '../../interfaces'
 import MixinFancybox from './../MixinFancybox/MixinFancybox.vue'
 import BaseImage from './../BaseImage/BaseImage.vue'
@@ -58,26 +58,26 @@ export default defineComponent({
   },
   props: {
     image: {
-      type: Object,
+      type: Object as PropType<ImageObject>,
       required: true,
       default: () => ({})
     },
-    // if a caption should even be visible
+    /** If caption should be visible */
     displayCaption: {
       type: Boolean,
       default: true
     },
-    // overrides caption provided with image model
+    /** Overrides caption provided by `{ImageObject}` */
     caption: {
       type: String,
       required: false
     },
-    // used to differentiate the fancybox of this carousel from others on the page; generated by Wagtail
+    /** 'Fancybox: the block id is used to differentiate the fancybox of the items in a carousel from other carousels on the page. Generated by Wagtail. Usually provided by parent component `BlockImageCarousel`.' */
     blockId: {
       type: String,
       required: false
     },
-    // if image titles should be displayed in the carousel's fancybox
+    /** Fancybox: if the image title should be displayed in the item's fancybox. Usually provided by parent component `BlockImageCarousel`. */
     showTitle: {
       type: Boolean,
       required: false,
@@ -108,7 +108,7 @@ export default defineComponent({
       }
       return null
     },
-    hasCaptionArea(): string | boolean {
+    hasCaptionArea(): string | boolean | undefined {
       if (this.image) {
         return this.theCaption || this.image.credit || this.image.detailUrl
       }

package/src/components/BlockImageComparison/BlockImageComparison.stories.js

@@ -3,14 +3,15 @@ import BlockImageComparison from './BlockImageComparison.vue'
 export default {
   title: 'Components/Blocks/BlockImageComparison',
   component: BlockImageComparison,
+  tags: ['wagtail-blocks'],
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="container mx-auto"><story/></div>`
+      template: `<div id="storyRoot" class="container mx-auto"><story/></div>`
     })
   ],
   parameters: {
     html: {
-      root: '#storyDecorator'
+      root: '#storyRoot'
     }
   },
   excludeStories: /.*Data$/
@@ -41,6 +42,7 @@ export const BlockImageComparisonData = {
 export const BaseStory = {
   name: 'BlockImageComparison',
   args: {
-    data: BlockImageComparisonData
+    data: BlockImageComparisonData,
+    customDetailUrl: 'https://www.google.com'
   }
 }

package/src/components/BlockImageComparison/BlockImageComparison.vue

@@ -27,17 +27,26 @@
 </template>
 
 <script lang="ts">
-import { defineComponent } from 'vue'
+import { defineComponent, type PropType } from 'vue'
+import type { BlockData, ImageObject } from './../../interfaces.ts'
 import BaseImageCaption from './../BaseImageCaption/BaseImageCaption.vue'
 
+export type BlockImageComparisonData = BlockData & {
+  beforeImage: ImageObject
+  afterImage: ImageObject
+  constrain: boolean
+  caption: string
+}
+
 export default defineComponent({
   name: 'BlockImageComparison',
   components: { BaseImageCaption },
   props: {
     data: {
-      type: Object,
+      type: Object as PropType<BlockImageComparisonData>,
       required: true
     },
+    /** Link to more image details. Link text defaults to "Full image details" */
     customDetailUrl: {
       type: String,
       default: undefined

package/src/components/BlockImageGallery/BlockImageGallery.stories.js

@@ -4,23 +4,16 @@ import BlockImageGallery from './BlockImageGallery.vue'
 export default {
   title: 'Components/Blocks/BlockImageGallery',
   component: BlockImageGallery,
+  tags: ['wagtail-blocks', 'carousels'],
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="max-w-screen-3xl mx-auto"><story/></div>`
+      template: `<div id="storyRoot" class="max-w-screen-3xl mx-auto"><story/></div>`
     })
   ],
-  argTypes: {
-    blockId: {
-      text: { type: 'string' },
-      required: false,
-      description:
-        'Fancybox: the block id is used to differentiate the fancybox of this gallery from others on the page. Generated by Wagtail.'
-    }
-  },
 
   parameters: {
     html: {
-      root: '#storyDecorator'
+      root: '#storyRoot'
     }
   },
   excludeStories: /.*Data$/
@@ -41,7 +34,7 @@ export const BlockImageGalleryData = {
 
 export const ImageGalleryData = {
   label: 'Mars',
-  'block-id': 'x121p1yuly',
+  blockId: 'x121p1yuly',
   title: 'Image Gallery',
   description:
     'Gallery description, maximus quis nibh eu, luctus ultrices nulla. Curabitur tempus, massa vitae porttitor porttitor, tortor erat tincidunt magna, vulputate varius nulla leo et mauris.',

package/src/components/BlockImageGallery/BlockImageGallery.vue

@@ -86,18 +86,22 @@ export default defineComponent({
     BlockImageCarousel
   },
   props: {
+    /** Small label text appears above the title on the gallery cover */
     label: {
       type: String,
       required: false
     },
+    /** Title of the gallery. Appears on gallery cover. */
     title: {
       type: String,
       required: false
     },
+    /** Short description of the gallery (plain text). Appears on gallery cover.  */
     description: {
       type: String,
       required: false
     },
+    /** Image to use as the gallery cover */
     cover: {
       type: Object as PropType<ImageObject>,
       required: false
@@ -106,6 +110,7 @@ export default defineComponent({
       type: Array as PropType<ImageObject[]>,
       required: false
     },
+    /** Fancybox: the block id is used to differentiate the fancybox of this gallery from others on the page. Generated by Wagtail. */
     blockId: {
       type: String,
       required: false

package/src/components/BlockInlineImage/BlockInlineImage.stories.js

@@ -4,6 +4,7 @@ import BlockInlineImage from './BlockInlineImage.vue'
 export default {
   title: 'Components/Blocks/BlockInlineImage',
   component: BlockInlineImage,
+  tags: ['wagtail-blocks'],
   excludeStories: /.*(Data)$/
 }
 
@@ -30,7 +31,7 @@ export const BlockInlineImageData = {
 
 export const BaseStory = {
   name: 'Align Right',
-  args: { data: BlockInlineImageData.block }
+  args: { data: BlockInlineImageData.block, variant: 'large' }
 }
 
 export const CustomCaption = {
@@ -64,6 +65,8 @@ export const PortraitImage = {
           width: 500
         }
       }
-    }
+    },
+
+    variant: 'large'
   }
 }

package/src/components/BlockInlineImage/BlockInlineImage.vue

@@ -55,13 +55,22 @@
 
 <script lang="ts">
 import { defineComponent, type PropType } from 'vue'
-import type { ImageObject } from '../../interfaces'
+import type { BlockData, ImageObject } from '../../interfaces'
 import { mixinGetSrcSet } from './../../utils/mixins'
 import MixinFancybox from './../MixinFancybox/MixinFancybox.vue'
 import BaseImagePlaceholder from './../BaseImagePlaceholder/BaseImagePlaceholder.vue'
 import BaseImage from './../BaseImage/BaseImage.vue'
 import BaseImageCaption from './../BaseImageCaption/BaseImageCaption.vue'
-import BlockText from './../BlockText/BlockText.vue'
+import BlockText, { type VariantKey as BlockTextVariantKey } from './../BlockText/BlockText.vue'
+
+export type BlockInlineImageData = BlockData & {
+  /** rich text */
+  text?: string
+  caption?: string
+  displayCaption: boolean
+  image?: ImageObject
+  alignTo: 'left' | 'right'
+}
 
 export default defineComponent({
   name: 'BlockInlineImage',
@@ -74,11 +83,15 @@ export default defineComponent({
   },
   props: {
     data: {
-      type: Object,
-      required: false
+      type: Object as PropType<BlockInlineImageData>,
+      required: false,
+      default: undefined
     },
+    /**
+     * Adjusts text size and vertical spacing. Corresponds with the same variants in `BlockText`
+     */
     variant: {
-      type: String as PropType<'small' | 'medium' | 'large'>,
+      type: String as PropType<BlockTextVariantKey>,
       default: 'large'
     }
   },
@@ -93,7 +106,7 @@ export default defineComponent({
         return this.data.caption
       } else if (
         this.data &&
-        this.data.image.caption &&
+        this.data.image?.caption &&
         this.data.image.caption.length > 2 &&
         this.data.displayCaption
       ) {
@@ -111,7 +124,7 @@ export default defineComponent({
       }
       return null
     },
-    hasCaptionArea(): string | false {
+    hasCaptionArea(): string | false | undefined {
       if (this.data && this.data.image) {
         return this.theCaption || this.data.image.credit || this.data.image.detailUrl
       }

package/src/components/BlockKeyPoints/BlockKeyPoints.stories.js

@@ -3,6 +3,7 @@ import BlockKeyPoints from './BlockKeyPoints.vue'
 export default {
   title: 'Components/Blocks/BlockKeyPoints',
   component: BlockKeyPoints,
+  tags: ['wagtail-blocks'],
   excludeStories: /.*Data$/
 }
 

package/src/components/BlockKeyPoints/BlockKeyPoints.vue

@@ -4,6 +4,7 @@
     class="BlockKeyPoints border-gray-light-mid lg:py-10 py-6 border-t border-b"
   >
     <BlockHeading
+      v-if="data.heading"
       class="mb-5"
       :data="{ heading: data.heading }"
     />
@@ -24,10 +25,17 @@
 </template>
 
 <script lang="ts">
-import { defineComponent } from 'vue'
+import { defineComponent, type PropType } from 'vue'
+import { BlockData } from './../../interfaces.ts'
 import BlockHeading from './../BlockHeading/BlockHeading.vue'
 import BlockText from './../BlockText/BlockText.vue'
 
+export type BlockKeyPointsData = BlockData & {
+  listItem: {
+    text: string
+  }[]
+}
+
 export default defineComponent({
   name: 'BlockKeyPoints',
   components: {
@@ -36,8 +44,9 @@ export default defineComponent({
   },
   props: {
     data: {
-      type: Object,
-      required: false
+      type: Object as PropType<BlockKeyPointsData>,
+      required: false,
+      default: undefined
     }
   }
 })

package/src/components/BlockLinkCard/BlockLinkCard.stories.js

@@ -5,27 +5,11 @@ import BlockLinkCard from './BlockLinkCard.vue'
 export default {
   title: 'Components/Cards/BlockLinkCard',
   component: BlockLinkCard,
-  tags: ['!autodocs'],
+  tags: ['cards'],
   excludeStories: /.*Data$/,
-  argTypes: {
-    size: {
-      control: {
-        type: 'select'
-      },
-      options: ['sm', 'md', 'lg']
-    },
-    headingLevel: {
-      description:
-        'Change the heading level for semantic markup. This does not affect the style of the heading.',
-      control: {
-        type: 'select',
-        options: [null, 'h1', 'h2', 'h3', 'h4', 'h5']
-      }
-    }
-  },
   parameters: {
     html: {
-      root: '#storyDecorator' // to omit decorators from html output
+      root: '#storyRoot' // to omit decorators from html output
     }
   }
 }
@@ -46,16 +30,14 @@ export const BlockLinkCardData = {
       alt: 'Alt text'
     }
   },
-  headingLevel: 'h2',
-  startDate: undefined,
-  endDate: undefined
+  headingLevel: 'h2'
 }
 
 export const BaseStory = {
   name: 'Single Item',
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="relative grid grid-cols-2 gap-3"><story/></div>`
+      template: `<div id="storyRoot" class="relative grid grid-cols-2 gap-3"><story/></div>`
     })
   ],
   args: {
@@ -66,7 +48,7 @@ export const BaseStory = {
 export const SingleItemCompactStyles = {
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="relative grid grid-cols-2 gap-3"><story/></div>`
+      template: `<div id="storyRoot" class="relative grid grid-cols-2 gap-3"><story/></div>`
     })
   ],
   args: {
@@ -78,7 +60,7 @@ export const SingleItemCompactStyles = {
 export const Compact = {
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="relative grid grid-cols-2 gap-3"><story/></div>`
+      template: `<div id="storyRoot" class="relative grid grid-cols-2 gap-3"><story/></div>`
     })
   ],
   name: 'Compact w/ Custom Props',
@@ -110,7 +92,7 @@ export const Compact = {
 export const EventItem = {
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="relative grid grid-cols-2 gap-3"><story/></div>`
+      template: `<div id="storyRoot" class="relative grid grid-cols-2 gap-3"><story/></div>`
     })
   ],
   args: {
@@ -132,7 +114,7 @@ export const EventItem = {
 export const EventItemWithChip = {
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="relative grid grid-cols-2 gap-3"><story/></div>`
+      template: `<div id="storyRoot" class="relative grid grid-cols-2 gap-3"><story/></div>`
     })
   ],
   args: {
@@ -155,12 +137,13 @@ export const EventItemWithChip = {
 export const EventWithDateNoTime = {
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="relative grid grid-cols-2 gap-3"><story/></div>`
+      template: `<div id="storyRoot" class="relative grid grid-cols-2 gap-3"><story/></div>`
     })
   ],
   args: {
     ...BlockLinkCardData,
     showCalendarChip: true,
+
     data: {
       page: {
         ...BlockLinkCardData.data,
@@ -172,13 +155,17 @@ export const EventWithDateNoTime = {
         ongoing: false,
         eventType: 'Workshop'
       }
-    }
+    },
+
+    startDate: 1760598000000,
+    endDate: 1761894000000,
+    startDatetime: "2025-10-11T00:00:00-08:00'"
   }
 }
 export const EduLesson = {
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="relative grid grid-cols-2 gap-3"><story/></div>`
+      template: `<div id="storyRoot" class="relative grid grid-cols-2 gap-3"><story/></div>`
     })
   ],
   globals: { theme: 'ThemeEdu' },
@@ -208,12 +195,13 @@ export const EduLesson = {
 export const EduExplainerArticle = {
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="relative grid grid-cols-2 gap-3"><story/></div>`
+      template: `<div id="storyRoot" class="relative grid grid-cols-2 gap-3"><story/></div>`
     })
   ],
   globals: { theme: 'ThemeEdu' },
   args: {
     ...BlockLinkCardData,
+
     data: {
       page: {
         __typename: 'EDUExplainerArticlePage',
@@ -232,7 +220,9 @@ export const EduExplainerArticle = {
           { gradeLevel: '8' }
         ]
       }
-    }
+    },
+
+    size: 'md'
   }
 }
 export const LargeEduExplainerArticle = {
@@ -266,7 +256,7 @@ export const EduCollection = {
   globals: { theme: 'ThemeEdu' },
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="relative grid grid-cols-2 gap-3"><story/></div>`
+      template: `<div id="storyRoot" class="relative grid grid-cols-2 gap-3"><story/></div>`
     })
   ],
   args: {
@@ -336,7 +326,7 @@ export const EduNewsItem = {
   globals: { theme: 'ThemeEdu' },
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="relative grid grid-cols-2 gap-3"><story/></div>`
+      template: `<div id="storyRoot" class="relative grid grid-cols-2 gap-3"><story/></div>`
     })
   ],
   args: {
@@ -355,7 +345,7 @@ export const EduNewsItem = {
 export const ExternalLink = {
   decorators: [
     () => ({
-      template: `<div id="storyDecorator" class="relative grid grid-cols-2 gap-3"><story/></div>`
+      template: `<div id="storyRoot" class="relative grid grid-cols-2 gap-3"><story/></div>`
     })
   ],
   args: {