feat(#249): add storybook docs (#425)

* feat(#249): add storybook README

* feat(#249): add DruxtDebug story

* feat(#249): add DruxtModule story

* chore: update changesets

* feat(#249): add detailed debug message

* chore(#249): update stories and documentation

* feat(#249): add required props error

* chore(#249): add mdx stories

* feat(#249): add default and debug slot

* chore(#249): update test

* chore(#249): update test coverage

* chore(#249): update router tests

* feat(#249): updated Block and Region stories

* chore(#249): update DruxtBlock documentation

* feat(#249): update DruxtBlockRegion docs and story

* chore(#249): update changesets

* feat(#249): update DruxtBreadcrumb storybook story

* feat(#249): update DruxtEntity stories and docs

* chore(#249): updated filename

* chore: add uuid error message

* chore(#249): update entity component docs

* chore(#249): fix entity uuid title issue

* feat(#239): update DruxtMenu storybook stories

* feat(#249): updated component stories and docs

* feat(#249): update DruxtView storybook stories

* chore(#249): update test coverage

* chore(#249): update DruxtView instance story

* feat(#249): update DruxtRouter story and docs

* chore(#249): update changesets

* chore(#249): fix router test coverage

* feat(#249): update DruxtSite docs and stories

* feat(#249): fix test snapshot

.changeset/cyan-buses-repeat.md

@@ -0,0 +1,5 @@
+---
+"druxt-router": minor
+---
+
+Added debug and default slots to the DruxtRouter component.

.changeset/empty-scissors-notice.md

@@ -0,0 +1,5 @@
+---
+"druxt-blocks": minor
+---
+
+Added detailed debug information for the DruxtBlock component.

.changeset/hip-brooms-jump.md

@@ -0,0 +1,5 @@
+---
+"druxt": minor
+---
+
+feat(#249): Added README story to storybook.

.changeset/hot-turtles-compare.md

@@ -0,0 +1,5 @@
+---
+"druxt-views": minor
+---
+
+feat(#249): Improved DruxtView storybook stories and documentation.

.changeset/nice-lemons-guess.md

@@ -0,0 +1,5 @@
+---
+"druxt": minor
+---
+
+Added required props error to DruxtModule components.

.changeset/ninety-books-sell.md

@@ -0,0 +1,5 @@
+---
+"druxt-menu": minor
+---
+
+feat(#249): Improved DruxtMenu storybook stories and documentation.

.changeset/old-dolphins-sit.md

@@ -0,0 +1,5 @@
+---
+"druxt-entity": minor
+---
+
+feat(#249): Improved DruxtEntity and DruxtEntityForm storybook stories and documentation.

.changeset/quick-moles-fix.md

@@ -0,0 +1,5 @@
+---
+"druxt-breadcrumb": minor
+---
+
+feat(#249): Improved DruxtBreadcrumb storybook stories and documentation.

.changeset/rotten-walls-speak.md

@@ -0,0 +1,5 @@
+---
+"druxt": minor
+---
+
+feat(#249): Added DruxtModule story to storybook.

.changeset/six-phones-trade.md

@@ -0,0 +1,5 @@
+---
+"druxt-blocks": minor
+---
+
+feat(#249): Improved DruxtBlock and DruxtBlockRegion storybook stories and documentation.

.changeset/slow-keys-provide.md

@@ -5,4 +5,4 @@
 "druxt-views": patch
 ---
 
-Fixed errors in storybook
+feat(#249): Fixed errors in storybook.

.changeset/strange-readers-help.md

@@ -0,0 +1,5 @@
+---
+"druxt-router": minor
+---
+
+feat(#249): Improved DruxtRouter storybook stories and documentation.

.changeset/thick-pears-speak.md

@@ -0,0 +1,5 @@
+---
+"druxt": minor
+---
+
+feat(#249): Added DruxtDebug story to storybook.

.changeset/witty-tables-live.md

@@ -0,0 +1,5 @@
+---
+"druxt-site": minor
+---
+
+feat(#249): Improved DruxtSite storybook stories and documentation.

packages/blocks/src/components/DruxtBlock.vue

@@ -4,13 +4,37 @@ import DruxtModule from 'druxt/dist/components/DruxtModule.vue'
 import { mapActions } from 'vuex'
 
 /**
- * Renders a Drupal Block by UUID or Drupal's internal ID.
+ * The DruxtBlock component is used to render a Drupal Block by UUID or Drupal's
+ * internal ID.
  *
- * @example @lang vue
+ * While the DruxtBlock component can't automatically render every Drupal block,
+ * it does provide the Block settings to a targetted Druxt wrapper component for
+ * manual theming.
+ *
+ * @example <caption>Render a block using **id**</caption> @lang vue
  * <DruxtBlock id="umami_branding" />
  *
- * @example @lang vue
+ * @example <caption>Render a block using **uuid**</caption> @lang vue
  * <DruxtBlock uuid="59104acd-88e1-43c3-bd5f-35800f206394" />
+ *
+ * @example <caption>DruxtBlock Wrapper component boilerplate</caption> @lang vue
+ * <template>
+ *   <DruxtDebug :json="block" />
+ * </template>
+ *
+ * <script>
+ * import { DruxtBlocksBlockMixin } from 'druxt-blocks'
+ * export default {
+ *   mixins: [DruxtBlocksBlockMixin]
+ * }
+ *
+ * @example <caption>DruxtBlock with template injection</caption> @lang vue
+ * <DruxtBlock id="umami_branding">
+ *   <template #default="{ block }">
+ *     <!-- Do whatever you want here -->
+ *     <DruxtDebug :json="block" />
+ *   </template>
+ * </DruxtBlock>
  */
 export default {
   name: 'DruxtBlock',
@@ -37,6 +61,8 @@ export default {
     /**
      * The Block Entity UUID.
      *
+     * If used, the **id** prop will be ignored.
+     *
      * @type {string}
      *
      * @example @lang vue
@@ -175,13 +201,29 @@ export default {
       const scopedSlots = {}
 
       // Debug data.
-      scopedSlots.debug = () => h('DruxtDebug',
-        { props: { summary: `Missing wrapper component for '${((this.block || {}).attributes || {}).drupal_internal__id}'`} },
-        [
-          h('label', ['Component options:', h('ul', this.component.options.map((s) => h('li', [s])))]),
-          h('label', ['Block settings:', h('pre', [JSON.stringify(((this.block || {}).attributes || {}).settings, null, '  ')])])
+      /* @slot Debug information */
+      scopedSlots.default = () => {
+        let summary = `Placeholder for the '${((this.block || {}).attributes || {}).drupal_internal__id}' block.`
+        let description = [
+          h('p', 'DruxtBlocks knows that a block can be rendered, and has information provided by Drupal, but not enough to automatically determine the behaviour of the block.'),
+          h('p', 'To render this block manually, create a Nuxt component with one of the following component options.'),
         ]
-      )
+
+        // Ensure an ID or UUID.
+        if (!this.id && !this.uuid) {
+          summary = "Missing required 'id' or 'uuid' prop."
+          description = [h('p', "The DruxtBlock component requires either the 'id' or 'uuid' prop to be set.")]
+        }
+
+        return h('DruxtDebug',
+          { props: { summary } },
+          [
+            h('div', description),
+            !!this.component.options.length && h('label', ['Component options:', h('ul', this.component.options.map((s) => h('li', [s])))]),
+            ((this.block || {}).attributes || {}).settings && h('label', ['Block settings:', h('pre', [JSON.stringify(this.block.attributes.settings, null, '  ')])])
+          ]
+        )
+      }
 
       return scopedSlots
     },

packages/blocks/src/components/DruxtBlockRegion.vue

@@ -4,15 +4,33 @@ import DruxtModule from 'druxt/dist/components/DruxtModule.vue'
 import { mapActions, mapState } from 'vuex'
 
 /**
- * Renders all visible blocks by theme and region name.
+ * The DruxtBlockRegion component renders visible blocks based on region and
+ * theme.
  *
- * Additional, non-visible blocks are available as slots and props data.
+ * All blocks, including those not visible, are provided as slots for the Druxt
+ * Wrapper component.
  *
  * @example @lang vue
- * <DruxtBlockRegion
- *   name="header"
- *   theme="umami"
- * />
+ * <DruxtBlockRegion name="header" theme="umami" />
+ *
+ * @example <caption>DruxtBlockRegion Wrapper component boilerplate</caption> @lang vue
+ * <template>
+ *   <DruxtDebug :json="blocks" />
+ * </template>
+ *
+ * <script>
+ * import { DruxtBlocksRegionMixin } from 'druxt-blocks'
+ * export default {
+ *   mixins: [DruxtBlocksRegionMixin]
+ * }
+ *
+ * @example <caption>DruxtBlockRegion with template injection</caption> @lang vue
+ * <DruxtBlock id="umami_branding">
+ *   <template #default="{ block }">
+ *     <!-- Do whatever you want here -->
+ *     <DruxtDebug :json="block" />
+ *   </template>
+ * </DruxtBlock>
  */
 export default {
   name: 'DruxtBlockRegion',

packages/blocks/src/mixins/region.js

@@ -11,9 +11,8 @@
  *
  * <script>
  * import { DruxtBlocksRegionMixin } from 'druxt-blocks'
- *
  * export default {
- *   mixins: [DruxtBlocksRegionMixin],
+ *   mixins: [DruxtBlocksRegionMixin]
  * }
  * </script>
  */

packages/blocks/src/nuxtModule.js

@@ -46,7 +46,6 @@ const DruxtBlocksNuxtModule = function (moduleOptions = {}) {
 
   // Nuxt Storybook.
   this.nuxt.hook('storybook:config', async ({ stories }) => {
-    stories.push('druxt-blocks/dist/components/*.stories.mjs')
     await DruxtBlocksStorybook.call(this, { stories })
   })
 }

packages/blocks/src/nuxtStorybook.js

@@ -10,43 +10,62 @@ const titleFn = (parts) =>
 export default async function ({ stories }) {
   const { addTemplate, options } = this
 
+  // Setup DruxtClient instance.
   const druxt = new DruxtClient(options.druxt.baseUrl, { ...options.druxt, proxy: { api: false } })
 
+  // Get all required data.
   const query = new DrupalJsonApiParams().addFilter('status', true)
   const blocks = (await druxt.getCollectionAll('block--block', query)).map((collection) => collection.data).flat()
+  const themes = Array.from(new Set(blocks.map((o) => o.attributes.theme)))
+
+  // DruxtBlock story.
+  addTemplate({
+    src: resolve(__dirname, `../templates/druxt-block.stories.js`),
+    fileName: `stories/druxt-block.stories.js`,
+    options: { blocks }
+  })
 
-  // DruxtBlock.
-  const blockStories = blocks.map((block) => {
+  // DruxtBlock instance stories.
+  blocks.forEach((block) => {
     addTemplate({
-      src: resolve(__dirname, `../templates/druxt-block.stories.js`),
+      src: resolve(__dirname, `../templates/druxt-block.instance.stories.js`),
       fileName: `stories/druxt-block.${block.attributes.drupal_internal__id}.stories.js`,
       options: {
         block,
         title: titleFn(['Druxt', 'Blocks', block.attributes.theme, block.attributes.region, block.attributes.drupal_internal__id])
       }
     })
+  })
 
-    return resolve(options.buildDir, `./stories/druxt-block.${block.attributes.drupal_internal__id}.stories.js`)
+  // DruxtBlockRegion story.
+  addTemplate({
+    src: resolve(__dirname, `../templates/druxt-block-region.stories.js`),
+    fileName: `stories/druxt-block-region.stories.js`,
+    options: {
+      regions: Array.from(new Set(blocks.map((o) => o.attributes.region))),
+      themes
+    }
   })
-  stories.push.apply(stories, blockStories)
 
-  // DruxtBlockRegion.
-  const themes = Array.from(new Set(blocks.map((o) => o.attributes.theme)))
-  const regionStories = themes.map((theme) => {
+  // DruxtBlockRegion instance stories.
+  themes.forEach((theme) => {
     const regions = Array.from(new Set(blocks.filter((o) => o.attributes.theme === theme).map((o) => o.attributes.region)))
-    return regions.map((region) => {
+    regions.forEach((region) => {
       addTemplate({
-        src: resolve(__dirname, `../templates/druxt-block-region.stories.js`),
+        src: resolve(__dirname, `../templates/druxt-block-region.instance.stories.js`),
         fileName: `stories/druxt-block-region.${theme}.${region}.stories.js`,
         options: {
           region,
           title: titleFn(['Druxt', 'Blocks', theme, region]),
           theme,
         }
       })
-
-      return resolve(options.buildDir, `./stories/druxt-block-region.${theme}.${region}.stories.js`)
     })
-  }).flat()
-  stories.push.apply(stories, regionStories)
+  })
+
+  // Add stories.
+  stories.push(resolve(options.buildDir, `./stories/druxt-block.stories.js`))
+  stories.push(resolve(options.buildDir, `./stories/druxt-block-region.stories.js`))
+  stories.push(resolve(options.buildDir, `./stories/druxt-block.*.stories.js`))
+  stories.push(resolve(options.buildDir, `./stories/druxt-block-region.*.stories.js`))
 }

packages/blocks/templates/druxt-block-region.instance.stories.js

@@ -0,0 +1,42 @@
+import DruxtBlockRegion from 'druxt-blocks/dist/components/DruxtBlockRegion.vue'
+
+export default {
+  title: '<%= options.title %>',
+  component: DruxtBlockRegion,
+  argTypes: {
+    name: {
+      control: false
+    },
+    theme: {
+      control: false
+    }
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: 'Renders all visible blocks assigned to the **<%= options.region %>** region for the **<%= options.theme %>** theme.\n\n```jsx\n\n<DruxtBlockRegion name="<%= options.region %>" theme="<%= options.theme %>" />\n```'
+      },
+    },
+  },
+}
+
+const Template = (args, { argTypes }) => {
+  return {
+    props: Object.keys(argTypes),
+    template: '<DruxtBlockRegion v-bind="$props" v-on="$props" />',
+  }
+}
+
+export const Default = Template.bind({})
+Default.args = {
+  name: '<%= options.region %>',
+  theme: '<%= options.theme %>',
+}
+Default.storyName = 'DruxtBlockRegion'
+Default.parameters = {
+  docs: {
+    source: {
+      code: '<DruxtBlockRegion name="<%= options.region %>" theme="<%= options.theme %>" />'
+    }
+  }
+}