druxt 0.16.0 → 0.17.0

package/dist/components/DruxtDebug.stories.mjs

@@ -0,0 +1,48 @@
+import DruxtDebug from './DruxtDebug.vue'
+
+export default {
+  title: 'Druxt/DruxtDebug',
+  component: DruxtDebug
+}
+
+const Template = (args) => ({
+  components: { DruxtDebug },
+  props: Object.keys(args),
+  template: `<DruxtDebug v-bind="$props">Debug information.</DruxtDebug>`
+})
+
+export const Default = Template.bind({})
+Default.storyName = 'Default slot'
+
+export const Json = Template.bind({})
+Json.args = {
+  json: {
+    type: '',
+    id: '',
+    links: {},
+    attributes: {},
+    relationships: {},
+  },
+  open: true,
+}
+Json.parameters = {
+  docs: {
+    storyDescription: 'The **json** prop takes any data and runs it through a basic JSON formatter for improved readability.',
+    source: {
+      code: '<DruxtDebug :json="entity" open>Debug information</DruxtDebug>'
+    },
+  },
+}
+
+export const Summary = Template.bind({})
+Summary.args = {
+  summary: 'A brief debug message'
+}
+Summary.parameters = {
+  docs: {
+    storyDescription: 'The **summary** prop can be used to provide a quick explanation of the debug component.',
+    source: {
+      code: `<DruxtDebug summary="${Summary.args.sumary}">Debug information</DruxtDebug>`
+    },
+  },
+}

package/dist/components/DruxtDebug.vue

@@ -4,6 +4,7 @@
     <pre v-if="json"><!--
       --><code>{{ JSON.stringify(json, null, '  ') }}</code><!--
     --></pre>
+    <!-- @slot Debug content -->
     <slot />
   </details>
 
@@ -13,10 +14,14 @@
 <script>
 
 /**
- * Renders Debug data only when Nuxt is in development mode.
+ * The DruxtDebug component can be used to render debug information that is
+ * visible only when Nuxt is run in development mode.
+ *
+ * You can render your debug information through the default slot, or via the
+ * **json** prop to format your data, or a combination of the two.
  *
  * @example @lang vue
- * <DruxtDebug :json="entity" />
+ * <DruxtDebug :json="entity">Debug information</DruxtDebug>
  */
 export default {
   /** */

package/dist/components/DruxtModule.stories.mdx

@@ -0,0 +1,126 @@
+import { Canvas, Meta, Story } from '@storybook/addon-docs'
+
+<Meta title="Druxt/DruxtModule" />
+
+# DruxtModule
+
+The DruxtModule component is the core component to be extended by core and
+custom modules.
+
+```js
+import DruxtModule from 'druxt/dist/components/DruxtModule.vue'
+export default {
+  extends: DruxtModule
+}
+```
+
+---
+
+## Fetch config
+
+All modules have a two part fetch system available to them; **fetchConfig** and
+**fetchData**.
+
+```js
+async fetchConfig() {
+  // Load configuration data here.
+  this.config = await this.getResource({...})
+},
+```
+
+Fetch config is used to load information from Drupal to determine the default
+behaviour of that component, as well as to determine the available component
+
+---
+
+## Component options
+
+The Druxt Wrapper system looks for available Vue components using a specific
+naming convention, determined by the Druxt module **componentOptions**.
+
+This allows for targetted theming of components based on the props or
+configuration data.
+
+```js
+componentOptions: (context) => ([[context.attributes.foo, 'default']]),
+```
+
+---
+
+## Fetch data
+
+After the Component options are determined, the first available component is
+determined, and any exported Druxt settings are loaded and used to fetch the
+main module data.
+
+```js
+async fetchData(settings) {
+  // Load data using the settings determine based on the configuration data.
+  this.resource = await this.getResource({
+    type: this.config.attributes.foo,
+    id: this.id,
+    query: this.getQuery(settings)
+  })
+},
+```
+
+---
+
+## Props data
+
+The **propsData** callback returns the props data for the render Wrapper
+component, making props data available to the frontend developer.
+
+```js
+propsData: (context) => ({ foo: context.config.attributes.foo })
+```
+
+---
+
+## Slots
+
+The **slots** method builds the slots that are made available to the Wrapper
+component. It is expected to return an object of scoped slot functions.
+
+```
+slots(h) {
+  return {
+    default: () => h('div', ['Hello world']),
+  }
+}
+```
+
+---
+
+### Custom module boilerplate
+
+Paste this into a Vue component as a starting point for a custom or contrib
+Druxt module.
+
+```vue
+<script>
+import DruxtModule from 'druxt/dist/components/DruxtModule.vue'
+export default {
+  name: 'MyModule',
+  extends: DruxtModule
+  druxt: {
+    async fetchConfig() {
+      // Load configuration data here.
+    },
+    async fetchData(settings) {
+      // Load data using the settings determine based on the configuration data.
+    },
+    // Build nested arrays of component options based on the context.
+    componentOptions: (context) => ([['default']]),
+    // Map props data from the context.
+    propsData: (context) => ({ ...context }),
+    // Build slots render arrays.
+    slots(h) {
+      return {
+        default: () => h('div', ['Hello world'])
+      }
+    }
+  }
+}
+</script>
+```

package/dist/components/DruxtModule.vue

@@ -6,7 +6,11 @@ import Vue from 'vue'
 import DruxtWrapper from './DruxtWrapper.vue'
 
 /**
- * Base component for core and custom Druxt modules.
+ * The DruxtModule component is used to make a Druxt module, simply import and
+ * extend the component to get started.
+ *
+ * The component provides access to the Druxt Wrapper theming and fetch system
+ * via the druxt settings object.
  *
  * @example @lang js
  * import DruxtModule from 'druxt/dist/components/DruxtModule.vue'
@@ -14,11 +18,18 @@ import DruxtWrapper from './DruxtWrapper.vue'
  *   name: 'DruxtTestModule',
  *   extends: DruxtModule,
  *   druxt: {
- *     componentOptions: () => ([['wrapper']]),
- *     propsData: (ctx) => ({
- *       bar: ctx.bar,
- *       foo: ctx.foo,
+ *     async fetchConfig() {},
+ *     async fetchData(settings) {},
+ *     componentOptions: (context) => ([[context.foo, context.bar, 'default']]),
+ *     propsData: (context) => ({
+ *       foo: context.foo,
+ *       bar: context.bar,
  *     }),
+ *     slots(h) {
+ *       return {
+ *         default: (attrs) => h('DruxtDebug', ['Hello world'])
+ *       }
+ *     }
  *   }
  * }
  */
@@ -226,7 +237,7 @@ export default {
       let components = []
       for (const set of options.filter(set => Array.isArray(set))) {
         const variants = []
-        components = [...components, ...set.map(item => {
+        components = [...components, ...set.filter((o) => o).map(item => {
           // Build array of name parts.
           const parts = variants.length ? [...variants[0].parts] : []
           parts.push(pascalCase(splitByCase(item)))
@@ -298,6 +309,18 @@ export default {
      */
     getScopedSlots() {
       const h = this.$createElement
+
+      // Get an array of unmet required props.
+      const required = Object.entries(this.$options.props)
+        .filter(([k, o]) => o.required && !this[k])
+        .map(([k]) => k)
+      // Return debug error if any missing props are found.
+      if (required.length) {
+        return {
+          default: () => h('DruxtDebug', { props: { summary: `Missing required props: ${required.join(', ')}.` } })
+        }
+      }
+
       const scopedSlots = typeof (this.$options.druxt || {}).slots === 'function'
         ? this.$options.druxt.slots.call(this, h)
         : {}

package/dist/druxt.esm.js

@@ -9,7 +9,7 @@ import Vue from 'vue';
 import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
 
 var name = "druxt";
-var version = "0.16.0";
+var version = "0.17.0";
 var description = "The Fully Decoupled Drupal Framework for Nuxt.js.";
 var keywords = [
 	"cms",
@@ -43,6 +43,7 @@ var main = "dist/druxt.ssr.js";
 var module = "dist/druxt.esm.js";
 var files = [
 	"dist",
+	"stories",
 	"templates"
 ];
 var dependencies = {
@@ -55,6 +56,9 @@ var dependencies = {
 	querystring: "^0.2.0",
 	scule: "^0.2.0"
 };
+var devDependencies = {
+	"@storybook/addon-docs": "^6.4.13"
+};
 var peerDependencies = {
 	consola: "*"
 };
@@ -80,6 +84,7 @@ var meta = {
 	module: module,
 	files: files,
 	dependencies: dependencies,
+	devDependencies: devDependencies,
 	peerDependencies: peerDependencies,
 	optionalDependencies: optionalDependencies,
 	publishConfig: publishConfig
@@ -145,6 +150,11 @@ const DruxtNuxtModule = function(moduleOptions = {}) {
   this.options.components = (_a = this.options.components) != null ? _a : true;
   this.options.cli.badgeMessages.push(`${chalk.blue.bold("Druxt")} @ v${meta.version}`);
   this.options.cli.badgeMessages.push(`${chalk.bold("API:")} ${chalk.blue.underline(options.baseUrl + options.endpoint)}`);
+  this.nuxt.hook("storybook:config", async ({ stories }) => {
+    stories.push("druxt/stories/*.stories.mdx");
+    stories.push("druxt/dist/components/*.stories.mdx");
+    stories.push("druxt/dist/components/*.stories.mjs");
+  });
 };
 
 class DruxtClient {

package/dist/druxt.ssr.js

@@ -22,7 +22,7 @@ const md5__default = /*#__PURE__*/_interopDefaultLegacy(md5);
 const Vue__default = /*#__PURE__*/_interopDefaultLegacy(Vue);
 
 var name = "druxt";
-var version = "0.16.0";
+var version = "0.17.0";
 var description = "The Fully Decoupled Drupal Framework for Nuxt.js.";
 var keywords = [
 	"cms",
@@ -56,6 +56,7 @@ var main = "dist/druxt.ssr.js";
 var module$1 = "dist/druxt.esm.js";
 var files = [
 	"dist",
+	"stories",
 	"templates"
 ];
 var dependencies = {
@@ -68,6 +69,9 @@ var dependencies = {
 	querystring: "^0.2.0",
 	scule: "^0.2.0"
 };
+var devDependencies = {
+	"@storybook/addon-docs": "^6.4.13"
+};
 var peerDependencies = {
 	consola: "*"
 };
@@ -93,6 +97,7 @@ const meta = {
 	module: module$1,
 	files: files,
 	dependencies: dependencies,
+	devDependencies: devDependencies,
 	peerDependencies: peerDependencies,
 	optionalDependencies: optionalDependencies,
 	publishConfig: publishConfig
@@ -158,6 +163,11 @@ const DruxtNuxtModule = function(moduleOptions = {}) {
   this.options.components = (_a = this.options.components) != null ? _a : true;
   this.options.cli.badgeMessages.push(`${chalk__default['default'].blue.bold("Druxt")} @ v${meta.version}`);
   this.options.cli.badgeMessages.push(`${chalk__default['default'].bold("API:")} ${chalk__default['default'].blue.underline(options.baseUrl + options.endpoint)}`);
+  this.nuxt.hook("storybook:config", async ({ stories }) => {
+    stories.push("druxt/stories/*.stories.mdx");
+    stories.push("druxt/dist/components/*.stories.mdx");
+    stories.push("druxt/dist/components/*.stories.mjs");
+  });
 };
 
 class DruxtClient {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "druxt",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "The Fully Decoupled Drupal Framework for Nuxt.js.",
   "keywords": [
     "cms",
@@ -34,6 +34,7 @@
   "module": "dist/druxt.esm.js",
   "files": [
     "dist",
+    "stories",
     "templates"
   ],
   "dependencies": {
@@ -46,6 +47,9 @@
     "querystring": "^0.2.0",
     "scule": "^0.2.0"
   },
+  "devDependencies": {
+    "@storybook/addon-docs": "^6.4.13"
+  },
   "peerDependencies": {
     "consola": "*"
   },

package/stories/README.stories.mdx

@@ -0,0 +1,74 @@
+import { Meta } from '@storybook/addon-docs'
+
+<Meta title="Druxt/README" />
+
+# Druxt Storybook
+
+> Druxt + @nuxtjs/Storybook
+
+The following documentation and stories are provided by
+[DruxtJS](https://druxtjs.org) and the installed Druxt modules.
+
+The stories are connected to your Drupal JSON:API via the DruxtClient; this
+allows you to test your Druxt Wrapper components using live data.
+
+- For more information, refer to the
+[Druxt Storybook guide](https://druxtjs.org/guide/storybook).
+
+---
+
+## Introduction
+
+This is a live Druxt Storybook, with autogenerated stories based on the
+configuration of your Drupal backend.
+
+---
+
+### Autogenerated stories
+
+Each Druxt module is able to use configuration from your Drupal backend to craft
+site specific stories.
+
+For instance, the DruxtEntity module will create a story for each Entity type,
+Bundle and Display mode, while the Block module will create a story for each
+backend Theme, Region and Block.
+
+Search or navigate through the Druxt components and stories in the Storybook
+sidebar.
+
+---
+
+### What is Druxt?
+
+> Drupal + Nuxt = Druxt
+
+Druxt is a framework for building Fully Decoupled Drupal and Nuxt.js
+applications and sites. It allows you to leverage the content modelling and
+management power of Drupal, and build elegant user experiences with Nuxt.js.
+
+- Find out more @ [DruxtJS.org](https://druxtjs.org)
+
+---
+
+### Druxt components
+
+Druxt components are provided by Druxt modules to provide targetted decoupled
+Drupal functionality; A **DruxtEntity** component to render Drupal Content
+entities, or a **DruxtMenu** component to render a Drupal menu, etc.
+
+- See the core Druxt components @
+  [https://druxtjs.org/api/components](https://druxtjs.org/api/components)
+
+---
+
+### Druxt Wrapper theme system
+
+Druxt components that extend the **DruxtModule** use slot based wrapper system,
+providing the frontend developer the ability to create theme templates per
+Content type, or Display mode, and many more component options depending on the
+module.
+
+The available component options are provided via the `component.options` data
+on the relevant Druxt module component.
+
+- For more information, see the [Themeing guide](https://druxtjs.org/guide/theming)

package/CHANGELOG.md

@@ -1,375 +0,0 @@
-# druxt
-
-## 0.16.0
-
-### Minor Changes
-
-- dc226c2: Made the \$druxt plugin first to be available to all Druxt module plugins.
-- 7b749bd: Added improved error handling.
-
-## 0.15.0
-
-### Minor Changes
-
-- 2ae1d6d: Reduced Fetch based UI flicker in the DruxtModule
-
-## 0.14.0
-
-### Minor Changes
-
-- 85fff42: Added debug mode and Axios request logging.
-
-  ```
-  export default {
-    druxt: {
-      // Enable debug log messages.
-      debug: true,
-    }
-  }
-  ```
-
-- 39e2e2e: Added ability to render readable JSON with the DruxtDebug component
-
-  ```jsx
-  <DruxtDebug :json="{ data: [{ one: true, two: false }] }" />
-  ```
-
-- 9c33d82: Made summary prop optional on DruxtDebug component
-- 45bc0b9: Added Druxt version to Nuxt badge
-
-## 0.13.0
-
-### Minor Changes
-
-- 77ab204: Added ability to proxy the API
-
-  ```js
-  export default {
-    druxt: {
-      proxy: {
-        api: true
-      }
-    }
-  };
-  ```
-
-  Creates two proxy entries:
-
-  - The JSON:API: `${ENDPOINT}` -> `${BASEURL}${ENDPOINT}`
-  - The Decoupled Router:`/router/translate-path` -> `${BASEURL}/router/translate-path`
-
-- 77ab204: Added ability to proxy the Drupal file system
-
-  ```js
-  export default {
-    druxt: {
-      proxy: {
-        files: "default"
-      }
-    }
-  };
-  ```
-
-  Creates a proxy entry:
-
-  - `/sites/${PATH}/files` -> `${BASEURL}/site/${PATH}/files`
-
-- c4457e1: Changed template injected module components to not use a DruxtWrapper component by default.
-- e7b1533: Refactored DruxtModule fetch hooks
-
-## 0.12.0
-
-### Minor Changes
-
-- 897dcbc: Added createResource method to DruxtClient
-
-  ```js
-  this.$druxt.createResource({ type, attributes: {}, relationships: {} });
-  ```
-
-- 897dcbc: Added updateResource method to DruxtClient
-
-  ```js
-  await this.$druxt.updateResource({
-    type,
-    id,
-    attributes: {},
-    relationships: {}
-  });
-  ```
-
-- 4504a2f: Added getRelated() method
-
-  ```js
-  await this.$druxt.getRelated(type, id, related);
-  ```
-
-- e3e634c: Enabled Components auto-discovery by default
-
-## 0.11.0
-
-### Minor Changes
-
-- dae345e: Added Druxt modules settings to `$druxt.settings`
-
-### Patch Changes
-
-- 75ff8a9: Fixed issue with Axios settings and Storybook
-
-## 0.10.0
-
-### Minor Changes
-
-- 715e5ef: Updated component registration method to use the Nuxt `components:dirs` hook
-- 2b8c3f3: Added DruxtDebug component
-- 317184e: Added Druxt API URL to Nuxt CLI badge
-
-## 0.9.0
-
-### Minor Changes
-
-- 21170fb: Moved Vue components out of bundle
-
-  ⚠ Potential breaking change
-
-  _**Note:** This only effects custom Druxt modules and implementations._
-
-  ```diff
-  -import { DruxtModule } from 'druxt'
-  +import DruxtModule from 'druxt/dist/components/DruxtModule.vue'
-  ```
-
-## 0.8.3
-
-### Patch Changes
-
-- Fixed issue with attrs passthrough
-
-## 0.8.2
-
-### Patch Changes
-
-- Fixed bug with fetchKey and attrs passthrough
-
-## 0.8.1
-
-### Patch Changes
-
-- Fixed DruxtModule emit behavior
-
-## 0.8.0
-
-### Minor Changes
-
-- Added support for default template injection to DruxtModule
-
-  _**Example:** Default template injection with DruxtEntity and DruxtMenu components_
-
-  ```vue
-  <DruxtEntity v-bind="props">
-    <template #default="{ entity }">
-      <h2>{{ entity.attributes.title }}</h2>
-      <DruxtMenu name="main" :depth="1" :parentId="parentId(entity)">
-        <template #default="{ items }">
-          {{ items }}
-        </template>
-      </DruxtMenu>
-    </template>
-  </DruxtEntity>
-  ```
-
-## 0.7.1
-
-### Patch Changes
-
-- Fixed issue with attrs passthrough
-- Updated support for Drupal JSON-API Params
-
-Thanks to [d34dman](https://github.com/d34dman)
-
-## 0.7.0
-
-### Minor Changes
-
-- Added support for v-model to DruxtModule
-
-  _**Example:** Passing a custom entity model to the DruxtEntity component_
-
-  ```vue
-  <DruxtEntity
-    type="node--article"
-    v-model="{
-      attributes: {
-        title: 'My Entity',
-        field_name: 'Value'
-      },
-      relationships: {}
-    }"
-  />
-  ```
-
-## 0.6.1
-
-### Patch Changes
-
-- Fixed issue with normalizaton of include/sort data
-- Fixed issue with queryobject in getResource action
-- Updated dependencies
-
-## 0.6.0
-
-### Minor Changes
-
-- Refactored DruxtStore
-  - Added support for partial resources
-  - Added dehyrdation/rehydration of included resources and collections
-- Fixed issue with DruxtStore reactivity
-
-## 0.5.1
-
-### Patch Changes
-
-- Fixed issue with getWrapperData
-- Fixed issue with DruxtStore reactivity
-
-## 0.5.0
-
-### Minor Changes
-
-- Added DruxtModule component
-
-  ```vue
-  <script>
-  import { DruxtModule } from "druxt";
-  export default {
-    name: "MyCustomDruxtModule",
-    extends: DruxtModule
-  };
-  </script>
-  ```
-
-  - For more details, refer to the [DruxtModule API documentation](/api/packages/druxt/components/DruxtModule)
-
-- Added \$attrs/props splitting
-
-## 0.4.2
-
-### Patch Changes
-
-- Added metadata to Nuxt module
-
-## 0.4.1
-
-### Patch Changes
-
-- Fixed dependency issues
-
-## 0.4.0
-
-### Minor Changes
-
-- Added DruxtClient
-
-  _**Example:** Using the DruxtClient to load a JSON:API resource in a node.js application_
-
-  ```js
-  import { DruxtClient } from 'druxt'
-  const druxt = new DruxtClient('https://demo-api.druxtjs.org')
-  druxt.getResource('node--page', uuid, query).then((resource) => {
-    console.log('getResource', resource)
-  }))
-  ```
-
-  - For more details, refer to the [DruxtClient API documentation](/api/packages/druxt/client)
-
-- Added DruxtStore
-
-  _**Example:** Using the DruxtStore to load a JSON:API resource within Nuxt_
-
-  ```vue
-  <script>
-  export default {
-    data: () => ({
-      resource: null
-    }),
-
-    async fetch() {
-      const resource = await this.$store.dispatch("druxt/getResource", {
-        type: "node--article",
-        id: uuid,
-        query
-      });
-      this.resource = resource;
-    }
-  };
-  </script>
-  ```
-
-  - For more details, refer to the [DruxtStore API documentation](/api/packages/druxt/stores/druxt)
-
-- Added \$druxt plugin wrapper for DruxtClient
-
-## 0.3.4
-
-### Patch Changes
-
-- Updated dependencies
-
-## 0.3.3
-
-### Patch Changes
-
-- Added Inner prop to DruxtComponentMixin
-
-## 0.3.2
-
-### Patch Changes
-
-- Added sorting of component options
-- Fixed issue with component options
-
-## 0.3.1
-
-### Patch Changes
-
-- Added DruxtWrapper to DruxtComponentMixin
-- Added unique filter to component options
-
-## 0.3.0
-
-### Minor Changes
-
-- Moved Site functionality to the [DruxtSite module](/modules/site)
-- Added Druxt component and mixin
-- Added available component options data
-- Removed unused Class and Store
-
-## 0.2.1
-
-### Patch Changes
-
-- Added @nuxtjs/proxy and default configuration
-- Updated dependencies for no-JS support
-
-## 0.2.0
-
-### Minor Changes
-
-- Updated dependencies for no-JS support
-
-## 0.1.2
-
-### Patch Changes
-
-- Fixed Vuex store installation
-- Updated dependencies
-
-## 0.1.1
-
-### Patch Changes
-
-- Removed schema generation workaround
-
-## 0.1.0
-
-### Initial release