druxt 0.15.0 → 0.18.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'])
+ *       }
+ *     }
  *   }
  * }
  */
@@ -107,12 +118,16 @@ export default {
 
     // Fetch configuration.
     if ((this.$options.druxt || {}).fetchConfig) {
-      await this.$options.druxt.fetchConfig.call(this)
+      try {
+        await this.$options.druxt.fetchConfig.call(this)
+      } catch(err) {
+        return this.error(err)
+      }
     }
 
     // Build wrapper component object.
     let options = []
-    const hasDefaultTemplate = !!(this.$vnode.data.scopedSlots || {}).default
+    const hasDefaultTemplate = !!(((this.$vnode || {}).data || {}).scopedSlots || {}).default
     // Load wrapper components if:
     if (
       // No default template and wrapper isn't false OR
@@ -138,7 +153,11 @@ export default {
 
     // Fetch resource.
     if ((this.$options.druxt || {}).fetchData) {
-      await this.$options.druxt.fetchData.call(this, component.settings)
+      try {
+        await this.$options.druxt.fetchData.call(this, component.settings)
+      } catch(err) {
+        return this.error(err, { component })
+      }
     }
 
     // Get scoped slots.
@@ -153,7 +172,7 @@ export default {
 
   watch: {
     model() {
-      if (this.component.props.value !== this.model) {
+      if (this.component.props && this.component.props.value !== this.model) {
         this.component.props.value = this.model
 
         // Only emit 'input' if using the default 'DruxtWrapper' component.
@@ -172,6 +191,31 @@ export default {
 
   /** */
   methods: {
+    /**
+     * Sets the component to render a DruxtDebug error message.
+     */
+    error(err, context = {}) {
+      // Build error details.
+      const { url } = err.druxt || {}
+      const title = (err.response || {}).statusText || ((((err.response || {}).data || {}).errors || [])[0] || {}).title
+      const summary = (err.response || {}).status
+        ? [(err.response || {}).status, title].filter((s) => s).join(': ')
+        : err.message
+
+      // Set the component to a Debug component with error details.
+      this.component = {
+        ...context.component || {},
+        is: 'DruxtDebug',
+        props: {
+          json: {
+            url,
+            errors: ((err.response || {}).data || {}).errors
+          },
+          summary
+        }
+      }
+    },
+
     /**
      * Get list of module wrapper components.
      *
@@ -193,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)))
@@ -265,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.15.0";
+var version = "0.18.0";
 var description = "The Fully Decoupled Drupal Framework for Nuxt.js.";
 var keywords = [
 	"cms",
@@ -43,11 +43,12 @@ var main = "dist/druxt.ssr.js";
 var module = "dist/druxt.esm.js";
 var files = [
 	"dist",
+	"stories",
 	"templates"
 ];
 var dependencies = {
+	"@nuxtjs/axios": "^5.13.6",
 	"@nuxtjs/proxy": "^2.1.0",
-	axios: "^0.21.1",
 	chalk: "^4.1.2",
 	deepmerge: "^4.2.2",
 	"drupal-jsonapi-params": "^1.2.1",
@@ -55,7 +56,11 @@ var dependencies = {
 	querystring: "^0.2.0",
 	scule: "^0.2.0"
 };
+var devDependencies = {
+	"@storybook/addon-docs": "^6.4.13"
+};
 var peerDependencies = {
+	axios: "*",
 	consola: "*"
 };
 var optionalDependencies = {
@@ -80,6 +85,7 @@ var meta = {
 	module: module,
 	files: files,
 	dependencies: dependencies,
+	devDependencies: devDependencies,
 	peerDependencies: peerDependencies,
 	optionalDependencies: optionalDependencies,
 	publishConfig: publishConfig
@@ -119,6 +125,14 @@ const DruxtNuxtModule = function(moduleOptions = {}) {
     }
     this.addModule("@nuxtjs/proxy");
   }
+  if (!options.axios) {
+    this.options.axios = {
+      baseURL: options.baseUrl,
+      proxy: !!this.options.proxy,
+      ...this.options.axios
+    };
+    this.addModule("@nuxtjs/axios");
+  }
   this.nuxt.hook("components:dirs", (dirs) => {
     dirs.push({ path: join(__dirname, "components") });
   });
@@ -127,6 +141,18 @@ const DruxtNuxtModule = function(moduleOptions = {}) {
     fileName: "druxt.js",
     options
   });
+  const extendPlugins = this.options.extendPlugins;
+  this.options.extendPlugins = (plugins) => {
+    plugins = typeof extendPlugins === "function" ? extendPlugins(plugins) : plugins;
+    const axiosIndex = plugins.findIndex(({ src }) => src === `${this.options.buildDir}/axios.js`);
+    const axiosPlugin = plugins[axiosIndex];
+    plugins.splice(axiosIndex, 1);
+    const druxtIndex = plugins.findIndex(({ src }) => src === `${this.options.buildDir}/druxt.js`);
+    const druxtPlugin = plugins[druxtIndex];
+    plugins.splice(druxtIndex, 1);
+    plugins = [axiosPlugin, druxtPlugin, ...plugins];
+    return plugins;
+  };
   this.addPlugin({
     src: resolve(__dirname, "../templates/store.js"),
     fileName: "store/druxt.js",
@@ -136,8 +162,12 @@ 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");
+  });
 };
-DruxtNuxtModule.meta = meta;
 
 class DruxtClient {
   constructor(baseUrl, options = {}) {
@@ -147,14 +177,15 @@ class DruxtClient {
     if (!baseUrl) {
       throw new Error("The 'baseUrl' parameter is required.");
     }
-    let axiosSettings = {};
-    if (baseUrl && !(options.proxy || {}).api) {
-      axiosSettings.baseURL = baseUrl;
-    }
-    if (typeof options.axios === "object") {
-      axiosSettings = Object.assign(axiosSettings, options.axios);
+    this.axios = {};
+    if (typeof options.axios === "function") {
+      this.axios = options.axios;
+    } else {
+      this.axios = axios.create({
+        ...options.axios || {},
+        baseURL: baseUrl
+      });
     }
-    this.axios = axios.create(axiosSettings);
     if (options.debug) {
       const log = this.log;
       this.axios.interceptors.request.use((config) => {
@@ -206,9 +237,16 @@ class DruxtClient {
         }
       }
       if (Object.keys(permissions).length) {
-        throw new TypeError(`${res.data.meta.omitted.detail}
-
- Required permissions: ${Object.keys(permissions).join(", ")}.`);
+        const err = {
+          response: {
+            statusText: res.data.meta.omitted.detail,
+            data: {
+              errors: [{ detail: `Required permissions:
+ - ${Object.keys(permissions).join("\n - ")}` }]
+            }
+          }
+        };
+        throw err;
       }
     }
   }
@@ -228,19 +266,49 @@ class DruxtClient {
         }
       });
     } catch (err) {
-      response = (err.response || {}).data || err.message;
+      this.error(err, { url: href });
     }
     return response;
   }
+  error(err, context = {}) {
+    let { url } = context;
+    if (!url && ((err.response || {}).config || {}).url) {
+      url = err.response.config.url;
+    }
+    const title = [
+      (err.response || {}).status,
+      (err.response || {}).statusText || err.message
+    ].filter((s) => s).join(": ");
+    const meta = { url: url && [this.options.baseUrl, url].join("") };
+    let message = [title];
+    if (Object.values(meta).filter((o) => o).length) {
+      message.push(Object.entries(meta).filter(([, v]) => v).map(([key, value]) => `${key.toUpperCase()}: ${value}`).join("\n"));
+    }
+    if (((((err.response || {}).data || {}).errors || [])[0] || {}).detail) {
+      message.push(err.response.data.errors[0].detail);
+    }
+    const error = Error(message.join("\n\n"));
+    error.response = err.response;
+    error.druxt = context;
+    throw error;
+  }
+  async get(url, options) {
+    try {
+      const res = await this.axios.get(url, options);
+      this.checkPermissions(res);
+      return res;
+    } catch (err) {
+      this.error(err, { url });
+    }
+  }
   async getCollection(type, query) {
     const { href } = await this.getIndex(type);
     if (!href) {
       return false;
     }
     const url = this.buildQueryUrl(href, query);
-    const res = await this.axios.get(url);
-    this.checkPermissions(res);
-    return res.data;
+    const { data } = await this.get(url);
+    return data;
   }
   async getCollectionAll(type, query) {
     const collections = [];
@@ -260,16 +328,27 @@ class DruxtClient {
     if (this.index && resource) {
       return this.index[resource] ? this.index[resource] : false;
     }
-    let index = ((await this.axios.get(this.options.endpoint) || {}).data || {}).links;
+    const url = this.options.endpoint;
+    const { data } = await this.get(url);
+    let index = data.links;
+    if (typeof index !== "object") {
+      const err = { response: { statusText: "Invalid JSON:API endpoint" } };
+      this.error(err, { url });
+    }
     const baseUrl = this.options.baseUrl;
     index = Object.fromEntries(Object.entries(index).map(([key, value]) => {
       value.href = value.href.replace(baseUrl, "");
       return [key, value];
     }));
     if (index[this.options.jsonapiResourceConfig]) {
-      const resources = await this.axios.get(index[this.options.jsonapiResourceConfig].href);
-      for (const resourceType in resources.data.data) {
-        const resource2 = resources.data.data[resourceType];
+      let resources = [];
+      try {
+        resources = (await this.get(index[this.options.jsonapiResourceConfig].href)).data.data;
+      } catch (err) {
+        this.log.warn(err.message);
+      }
+      for (const resourceType in resources) {
+        const resource2 = resources[resourceType];
         const internal = resource2.attributes.drupal_internal__id.split("--");
         const item = {
           resourceType: resource2.attributes.resourceType,
@@ -285,11 +364,7 @@ class DruxtClient {
       }
     }
     this.index = index;
-    if (resource) {
-      const response = this.index[resource] ? this.index[resource] : false;
-      return response;
-    }
-    return this.index;
+    return resource ? this.index[resource] || false : this.index;
   }
   async getRelated(type, id, related, query) {
     if (!id || !type || !related) {
@@ -300,12 +375,8 @@ class DruxtClient {
       href = this.options.endpoint + "/" + type.replace("--", "/");
     }
     const url = this.buildQueryUrl(`${href}/${id}/${related}`, query);
-    try {
-      const related2 = await this.axios.get(url);
-      return related2.data;
-    } catch (e) {
-      return false;
-    }
+    const { data } = await this.get(url);
+    return data;
   }
   async getResource(type, id, query) {
     if (!id || !type) {
@@ -315,13 +386,9 @@ class DruxtClient {
     if (!href) {
       href = this.options.endpoint + "/" + type.replace("--", "/");
     }
-    const url = this.buildQueryUrl(`${href}/${id}`, query);
-    try {
-      const resource = await this.axios.get(url);
-      return resource.data;
-    } catch (e) {
-      return false;
-    }
+    const url = this.buildQueryUrl([href, id].join("/"), query);
+    const { data } = await this.get(url);
+    return data;
   }
   async updateResource(resource) {
     const { href } = await this.getIndex(resource.type);
@@ -337,7 +404,7 @@ class DruxtClient {
         }
       });
     } catch (err) {
-      response = (err.response || {}).data || err.message;
+      this.error(err);
     }
     return response;
   }
@@ -348,7 +415,7 @@ const getDrupalJsonApiParams = (query) => {
 };
 
 const dehydrateResources = ({ commit, queryObject, resources }) => {
-  return resources.map((data) => {
+  return (resources || []).map((data) => {
     const link = decodeURI(((data.links || {}).self || {}).href || "");
     const href = typeof (queryObject.fields || {})[data.type] === "string" ? [link.split("?")[0], `fields[${data.type}]=${queryObject.fields[data.type]}`].join("?") : link;
     commit("druxt/addResource", {
@@ -539,5 +606,7 @@ class DruxtClass {
   }
 }
 
+DruxtNuxtModule.meta = require("../package.json");
+
 export default DruxtNuxtModule;
 export { DruxtClass, DruxtClient, DruxtStore };