@kong-ui-public/error-boundary 0.0.2-pr.821.7039db25.0 → 0.0.2-pr.821.d465c6e4.0

package/README.md

@@ -1,31 +1,179 @@
 # @kong-ui-public/error-boundary
 
-{A description of this package}
+A Vue error boundary component to capture unhandled errors that allows for providing a fallback UI and error callback function via [Vue's `onErrorCaptured` hook](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured).
 
 - [Features](#features)
 - [Requirements](#requirements)
 - [Usage](#usage)
   - [Install](#install)
+  - [Register](#register)
+  - [Slots](#slots)
   - [Props](#props)
 
 ## Features
 
-- List of package features
+- Renderless (by default) Vue component that **captures** uncaught errors from child components and **prevents the error from propagating further**
+- Allows passing in a list of [tags](#tags) to forward along to the [`onError` callback function](#onerror).
+- Allows providing an error callback function (defined inline or during global Vue plugin initialization)
+- Provides a [`fallback` slot](#fallback) to allow a host app to provide an error UI
+- Allows for **nested** `ErrorBoundary` components in the DOM. Any nested `ErrorBoundary` components will inherit the tags of its ancestors
+- See the package `sandbox` for more examples
+
+The `ErrorBoundary` component will **always** capture any unhandled errors and prevent them from further propagating. This is essentially saying "this error has been handled and should be ignored." It will prevent any additional `ErrorBoundary` components from receiving the error and prevent additional `errorCaptured` hooks or `app.config.errorHandler` from being invoked for this error.
+
+The `ErrorBoundary` component can be used to wrap a single component or an entire tree of children, tagging any errors that are captured in the DOM tree.
+
+When nesting `ErrorBoundary` components, the [`tags`](#tags) from any parent `ErrorBoundary` component will be passed down to its children and included in their `ErrorCallbackParams`.
+
+```html
+<template>
+  <div class="my-page">
+    <!-- 1 -->
+    <ErrorBoundary :tags="['team-settings']">
+      <SettingsComponent />
+      <form>
+        <!-- 2 -->
+        <ErrorBoundary :tags="['team-billing']">
+          <BuggyComponent />
+          <!-- 3 -->
+          <ErrorBoundary :tags="['team-core-ui']">
+            <CreditCardComponent />
+            <!-- The fallback slot has access to all params -->
+            <template #fallback="{ error, instance, componentName, info, tags }">
+              <div class="fallback-content">
+                <p>This component has custom fallback UI; most likely just an icon, etc.</p>
+                <p class="error-message">{{ componentName }}: {{ error.message }}</p>
+              </div>
+            </template>
+          </ErrorBoundary>
+        <ActionButtonsComponent />
+        </ErrorBoundary>
+      </form>
+    </ErrorBoundary>
+  </div>
+</template>
+```
+
+Looking at the numbered examples above:
+
+1. `team-settings` will be tagged if any child of this component throws an uncaught error, including the `<SettingsComponent>` all the way down to the `<CreditCardComponent>`
+2. `team-settings` and `team-billing` will be tagged for anything inside the `<form>` element
+3. `team-core-ui` will **only** be tagged if the `<CreditCardComponent>` throws an error, as it is the only DOM child of its error boundary.
 
 ## Requirements
 
-- List of package requirements (e.g. "`vue` and must be initialized in the host application")
+- `vue` must be initialized in the host application
 
 ## Usage
 
 ### Install
 
-{Installation instructions}
+Install the package in your host application
+
+```sh
+yarn add @kong-ui-public/error-boundary
+```
+
+### Register
+
+You can register the `ErrorBoundary` component in your app [globally](#global-registration) or [locally](#in-component-registration) in another component.
+
+> **Note**: There are no style imports for this package.
+
+#### Global Registration
+
+When registering the component globally via the default export Vue plugin, you may provide a default [`onError` callback](#onerror) to be used throughout your application for all instances of the `ErrorBoundary` component.
+
+You may still override this global callback on individual instances of the component by passing a function to the [`onError` component prop](#onerror). _(This includes providing an empty function to disable the global behavior)_
+
+```typescript
+// Global registration
+import { createApp } from 'vue'
+import ErrorBoundary from '@kong-ui-public/error-boundary' // No style imports needed
+// Datadog package example
+import { datadogRum } from '@datadog/browser-rum'
+
+
+const app = createApp(App)
+
+app.use(ErrorBoundary, {
+  // Provide a global, default `onError` callback for all ErrorBoundary instances
+  onError: ({ error, instance, componentName, info, tags }) => {
+    // Example of sending errors to Datadog
+    datadogRum.addError(error, {
+      source: 'ErrorBoundary',
+      component: componentName,
+      tags,
+      info,
+    })
+  },
+})
+```
+
+#### In-Component Registration
+
+When registering the component locally, you can provide the `onError` callback as a prop.
+
+```html
+<!-- Local registration -->
+<template>
+  <ErrorBoundary
+    :on-error="customErrorCallback"
+    :tags="myTags"
+  >
+    <BuggyComponent />
+  </ErrorBoundary>
+</template>
+
+<script setup lang="ts">
+import { ErrorBoundary } from '@kong-ui-public/error-boundary' // No style imports needed
+
+const myTags = ['first-tag', 'another-tag']
+const customErrorCallback = ({ error, instance, componentName, info, tags }) => {
+  // Do something fancy
+}
+</script>
+```
+
+### Slots
+
+#### `default`
+
+The `default` slot should be utilized for your "potentially buggy" Vue component(s). The `default` slot can handle a single child, or an entire tree of child components/elements.
+
+#### `fallback`
+
+The `fallback` slot can optionally be used to provide a fallback UI should any child component (not already wrapped with another `ErrorBoundary` component) thrown an unhandled error. **The default fallback behavior is to render nothing in the UI.**
+
+The `fallback` slot has access to all of the `ErrorCallbackParams` as slot props:
+
+```html
+<ErrorBoundary :tags="myTags">
+  <BuggyComponent />
+  <template #fallback="{ error, instance, componentName, info, tags }">
+    <!-- Your fallback UI here -->
+  </template>
+</ErrorBoundary>
+```
 
 ### Props
 
-#### `example`
+#### `tags`
 
-- type: `Boolean`
+- type: `String[]`
 - required: `false`
-- default: `false`
+- default: `[]`
+
+A list of strings to "tag" the captured error with that are passed along to the `onError` callback.
+
+For example, if you want to provide custom attributes to errors on Datadog, you can pass in an array of strings to add to the logged error's custom attributes.
+
+#### `onError`
+
+- type: `Function as PropType<(payload: ErrorCallbackParams) => void>`
+- required: `false`
+- default: `[]`
+
+A function to be called from the `ErrorBoundary` component when an error in a child component is captured. Receives a payload of [ErrorCallbackParams](src/types/error-boundary.ts).
+
+> **Note**: Providing a callback function via the `onError` prop will take precedence over any callback function defined during global registration. You can also provide an empty function in order to prevent the global callback from being executed.

package/dist/error-boundary.es.js

@@ -1,14 +1,5 @@
-import { defineComponent as f, inject as l, ref as E, computed as g, unref as v, provide as y, onErrorCaptured as O, renderSlot as d, pushScopeId as b, popScopeId as k, createElementVNode as c, createTextVNode as _ } from "vue";
-const p = "kong-ui-error-boundary-on-error", i = "kong-ui-error-boundary-tags", m = (r) => (b("data-v-aa3e0847"), r = r(), k(), r), N = /* @__PURE__ */ m(() => /* @__PURE__ */ c("div", {
-  class: "kong-ui-public-error-boundary",
-  "data-testid": "kong-ui-public-error-boundary-fallback-content"
-}, [
-  /* @__PURE__ */ c("p", null, [
-    /* @__PURE__ */ _("This is the "),
-    /* @__PURE__ */ c("b", null, "ErrorBoundary"),
-    /* @__PURE__ */ _(" fallback content.")
-  ])
-], -1)), R = /* @__PURE__ */ f({
+import { defineComponent as y, inject as d, ref as i, computed as g, unref as m, provide as O, onErrorCaptured as R, renderSlot as f } from "vue";
+const E = "kong-ui-error-boundary-on-error", c = "kong-ui-error-boundary-tags", N = /* @__PURE__ */ y({
   __name: "ErrorBoundary",
   props: {
     tags: {
@@ -22,42 +13,37 @@ const p = "kong-ui-error-boundary-on-error", i = "kong-ui-error-boundary-tags",
       default: void 0
     }
   },
-  setup(r) {
-    const o = r, n = l(p, o.onError), s = l(i, []), e = E(), a = g(() => {
-      const t = /* @__PURE__ */ new Set();
-      for (const u of [...v(s), ...o.tags])
-        t.add(u);
-      return Array.from(t);
+  setup(n) {
+    const r = n, t = d(E, r.onError), _ = d(c, []), a = i(), u = g(() => {
+      const o = /* @__PURE__ */ new Set();
+      for (const e of [...m(_), ...r.tags])
+        o.add(e);
+      return Array.from(o);
     });
-    return y(i, a), O((t, u, B) => (console.log("onErrorCaptured"), e.value = t, e.value.context = "custom", console.log("allTags", a.value), typeof o.onError == "function" ? o.onError({
-      error: e.value,
-      tags: a.value
-    }) : typeof n == "function" && n({
-      error: e.value,
-      tags: a.value
-    }), !1)), (t, u) => e.value ? d(t.$slots, "fallback", {
+    return O(c, u), R((o, e, p) => {
+      var l;
+      a.value = o;
+      const s = {
+        error: a.value,
+        instance: e,
+        info: p,
+        tags: u.value,
+        componentName: (l = e == null ? void 0 : e.$options) == null ? void 0 : l.__name
+      };
+      return typeof r.onError == "function" ? r.onError(s) : typeof t == "function" && t(s), !1;
+    }), (o, e) => a.value ? f(o.$slots, "fallback", {
       key: 1,
-      error: e.value,
-      tags: r.tags
-    }, () => [
-      N
-    ], !0) : d(t.$slots, "default", { key: 0 }, void 0, !0);
+      error: a.value,
+      tags: n.tags
+    }) : f(o.$slots, "default", { key: 0 });
   }
-});
-const I = (r, o) => {
-  const n = r.__vccOpts || r;
-  for (const [s, e] of o)
-    n[s] = e;
-  return n;
-}, T = /* @__PURE__ */ I(R, [["__scopeId", "data-v-aa3e0847"]]), C = {
+}), k = {
   // Customize Vue plugin options as desired
-  // Providing a `name` property allows for customizing the registered
-  // name of your component (useful if exporting a single component).
-  install: (r, o = {}) => {
-    r.component(o.name || "ErrorBoundary", T), r.provide(p, o.onError);
+  install: (n, r = {}) => {
+    n.component(r.name || "ErrorBoundary", N), n.provide(E, r.onError);
   }
 };
 export {
-  T as ErrorBoundary,
-  C as default
+  N as ErrorBoundary,
+  k as default
 };

package/dist/error-boundary.umd.js

@@ -1 +1 @@
-(function(t,e){typeof exports=="object"&&typeof module<"u"?e(exports,require("vue")):typeof define=="function"&&define.amd?define(["exports","vue"],e):(t=typeof globalThis<"u"?globalThis:t||self,e(t["kong-ui-public-error-boundary"]={},t.Vue))})(this,function(t,e){"use strict";const u="kong-ui-error-boundary-on-error",i="kong-ui-error-boundary-tags",_=(r=>(e.pushScopeId("data-v-aa3e0847"),r=r(),e.popScopeId(),r))(()=>e.createElementVNode("div",{class:"kong-ui-public-error-boundary","data-testid":"kong-ui-public-error-boundary-fallback-content"},[e.createElementVNode("p",null,[e.createTextVNode("This is the "),e.createElementVNode("b",null,"ErrorBoundary"),e.createTextVNode(" fallback content.")])],-1)),p=e.defineComponent({__name:"ErrorBoundary",props:{tags:{type:Array,required:!1,default:()=>[]},onError:{type:Function,required:!1,default:void 0}},setup(r){const o=r,s=e.inject(u,o.onError),d=e.inject(i,[]),n=e.ref(),c=e.computed(()=>{const a=new Set;for(const l of[...e.unref(d),...o.tags])a.add(l);return Array.from(a)});return e.provide(i,c),e.onErrorCaptured((a,l,m)=>(console.log("onErrorCaptured"),n.value=a,n.value.context="custom",console.log("allTags",c.value),typeof o.onError=="function"?o.onError({error:n.value,tags:c.value}):typeof s=="function"&&s({error:n.value,tags:c.value}),!1)),(a,l)=>n.value?e.renderSlot(a.$slots,"fallback",{key:1,error:n.value,tags:r.tags},()=>[_],!0):e.renderSlot(a.$slots,"default",{key:0},void 0,!0)}}),g="",f=((r,o)=>{const s=r.__vccOpts||r;for(const[d,n]of o)s[d]=n;return s})(p,[["__scopeId","data-v-aa3e0847"]]),y={install:(r,o={})=>{r.component(o.name||"ErrorBoundary",f),r.provide(u,o.onError)}};t.ErrorBoundary=f,t.default=y,Object.defineProperties(t,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})});
+(function(e,r){typeof exports=="object"&&typeof module<"u"?r(exports,require("vue")):typeof define=="function"&&define.amd?define(["exports","vue"],r):(e=typeof globalThis<"u"?globalThis:e||self,r(e["kong-ui-public-error-boundary"]={},e.Vue))})(this,function(e,r){"use strict";const d="kong-ui-error-boundary-on-error",s="kong-ui-error-boundary-tags",f=r.defineComponent({__name:"ErrorBoundary",props:{tags:{type:Array,required:!1,default:()=>[]},onError:{type:Function,required:!1,default:void 0}},setup(a){const o=a,l=r.inject(d,o.onError),E=r.inject(s,[]),u=r.ref(),i=r.computed(()=>{const n=new Set;for(const t of[...r.unref(E),...o.tags])n.add(t);return Array.from(n)});return r.provide(s,i),r.onErrorCaptured((n,t,_)=>{var p;u.value=n;const c={error:u.value,instance:t,info:_,tags:i.value,componentName:(p=t==null?void 0:t.$options)==null?void 0:p.__name};return typeof o.onError=="function"?o.onError(c):typeof l=="function"&&l(c),!1}),(n,t)=>u.value?r.renderSlot(n.$slots,"fallback",{key:1,error:u.value,tags:a.tags}):r.renderSlot(n.$slots,"default",{key:0})}}),y={install:(a,o={})=>{a.component(o.name||"ErrorBoundary",f),a.provide(d,o.onError)}};e.ErrorBoundary=f,e.default=y,Object.defineProperties(e,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})});

package/dist/types/components/ErrorBoundary.vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ErrorBoundary.vue.d.ts","sourceRoot":"","sources":["../../../src/components/ErrorBoundary.vue.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAA2B,QAAQ,EAAE,MAAM,KAAK,CAAA;AAE5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmMnD,wBAA8G;AAE9G,KAAK,uBAAuB,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAAE,QAAO;QAClD,MAAM,EAAE,CAAC,CAAC;KACT,CAAA;CAAE,CAAC"}
+{"version":3,"file":"ErrorBoundary.vue.d.ts","sourceRoot":"","sources":["../../../src/components/ErrorBoundary.vue.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAA2B,QAAQ,EAAE,MAAM,KAAK,CAAA;AAK5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8JnD,wBAA8G;AAE9G,KAAK,uBAAuB,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAAE,QAAO;QAClD,MAAM,EAAE,CAAC,CAAC;KACT,CAAA;CAAE,CAAC"}

package/dist/types/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,eAAO,MAAM,6CAA6C,oCAAoC,CAAA;AAC9F,oGAAoG;AACpG,eAAO,MAAM,yCAAyC,gCAAgC,CAAA"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,eAAO,MAAM,6CAA6C,oCAAoC,CAAA;AAE9F,oGAAoG;AACpG,eAAO,MAAM,yCAAyC,gCAAgC,CAAA"}

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;AAC9B,OAAO,aAAa,MAAM,gCAAgC,CAAA;AAE1D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;;mBAOxC,GAAG,YAAW,0BAA0B,KAAQ,IAAI;;AAJrE,wBAQC;AAED,OAAO,EAAE,aAAa,EAAE,CAAA;AAExB,cAAc,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;AAC9B,OAAO,aAAa,MAAM,gCAAgC,CAAA;AAE1D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;;mBAKxC,GAAG,YAAW,0BAA0B,KAAQ,IAAI;;AAFrE,wBAMC;AAED,OAAO,EAAE,aAAa,EAAE,CAAA;AAExB,cAAc,SAAS,CAAA"}

package/dist/types/types/error-boundary.d.ts

@@ -1,9 +1,13 @@
+import type { ComponentPublicInstance } from 'vue';
 export interface ErrorCallbackParams {
     error: unknown;
+    instance: ComponentPublicInstance | null;
+    componentName?: string;
+    info: string;
     tags: string[];
 }
 export interface ErrorBoundaryPluginOptions {
     name?: string;
-    onError?: ({ error, tags }: ErrorCallbackParams) => void;
+    onError?: ({ error, instance, componentName, info, tags }: ErrorCallbackParams) => void;
 }
 //# sourceMappingURL=error-boundary.d.ts.map

package/dist/types/types/error-boundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../../../src/types/error-boundary.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAA;IACd,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,mBAAmB,KAAK,IAAI,CAAA;CACzD"}
+{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../../../src/types/error-boundary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,KAAK,CAAA;AAElD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,EAAE,uBAAuB,GAAG,IAAI,CAAA;IACxC,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,mBAAmB,KAAK,IAAI,CAAA;CACxF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kong-ui-public/error-boundary",
-  "version": "0.0.2-pr.821.7039db25.0",
+  "version": "0.0.2-pr.821.d465c6e4.0",
   "type": "module",
   "main": "./dist/error-boundary.umd.js",
   "module": "./dist/error-boundary.es.js",

package/dist/style.css

@@ -1 +0,0 @@
-.kong-ui-public-error-boundary[data-v-aa3e0847]{align-items:center;background:#d60027;border-radius:8px;color:#fff;display:flex;font-size:16px;font-weight:400;justify-content:center;line-height:24px;max-width:100%;width:100%}