#71 onError callback (#76)

Author: CarlosNZ

README.md

@@ -12,6 +12,7 @@ Features include:
  - self-contained — rendered with plain HTML/CSS, so no dependance on external UI libraries
  - search/filter data by key, value or custom function
  - provide your own [custom component](#custom-nodes) to integrate specialised UI for certain data.
+ - [localisable](#localisation) UI
 
 **[Explore the Demo](https://carlosnz.github.io/json-edit-react/)**
 
@@ -23,6 +24,7 @@ Features include:
 - [Props overview](#props-overview)
 - [Update functions](#update-functions)
   - [OnChange function](#onchange-function)
+  - [OnError function](#onerror-function)
   - [Copy function](#copy-function)
 - [Filter functions](#filter-functions)
   - [Examples](#examples-1)
@@ -96,6 +98,8 @@ The only *required* value is `data`.
 | `onDelete`              | `UpdateFunction`                              |             | A function to run whenever a value is **deleted**.                                                                                                                                                                                                                                                                   |
 | `onAdd`                 | `UpdateFunction`                              |             | A function to run whenever a new property is **added**.                                                                                                                                                                                                                                                              |
 | `onChange`              | `OnChangeFunction`                            |             | A function to modify/constrain user input as they type -- see [OnChange functions](#onchange-function).                                                                                                                                                                                                              |
+| `onError`               | `OnErrorFunction`                             |             | A function to run whenever the component reports an error -- see [OnErrorFunction](#onerror-function).                                                                                                                                                                                                               |
+| `showErrorMessages`     | `boolean `                                    | `true`      | Whether or not the component should display its own error messages (you'd probably only want to disable this if you provided your own `onError` function)                                                                                                                                                            |
 | `enableClipboard`       | `boolean\|CopyFunction`                       | `true`      | Whether or not to enable the "Copy to clipboard" button in the UI. If a function is provided, `true` is assumed and this function will be run whenever an item is copied.                                                                                                                                            |
 | `indent`                | `number`                                      | `3`         | Specify the amount of indentation for each level of nesting in the displayed data.                                                                                                                                                                                                                                   |
 | `collapse`              | `boolean\|number\|FilterFunction`             | `false`     | Defines which nodes of the JSON tree will be displayed "opened" in the UI on load. If `boolean`, it'll be either all or none. A `number` specifies a nesting depth after which nodes will be closed. For more fine control a function can be provided — see [Filter functions](#filter-functions).                   |
@@ -169,6 +173,26 @@ The input object is similar to the Update function input, but with no `newData`
     }
   ```
 
+### OnError function
+
+Normally, the component will display simple error messages whenever an error condition is detected (e.g. invalid JSON input, duplicate keys, or custom errors returned by the [`onUpdate` functions)](#update-functions)). However, you can provide your own `onError` callback in order to implement your own error UI, or run additional side effects. (In the former case, you'd probably want to disable the `showErrorMessages` prop, too.) The input to the callback is similar to the other callbacks:
+
+```js
+{
+    currentData,  // data state before update 
+    currentValue, // the current value of the property being updated
+    errorValue,   // the erroneous value that failed to update the property
+    name,         // name of the property being updated
+    path,         // full path to the property being updated, as an array of property keys
+                  // (e.g. [ "user", "friends", 1, "name" ] ) (equivalent to "user.friends[1].name"),
+    error: {
+      code,       // one of 'UPDATE_ERROR' | 'DELETE_ERROR' | 'ADD_ERROR' | 'INVALID_JSON' | 'KEY_EXISTS'
+      message     // the (localised) error message that would be displayed
+    }
+}
+```
+ (An example of a custom Error UI can be seen in the [Demo](#https://carlosnz.github.io/json-edit-react/) with the "Custom Nodes" data set -- when you enter invalid JSON input a "Toast" notification is displayed instead of the normal component error message.)
+
 ### Copy function
 
 A similar callback is executed whenever an item is copied to the clipboard (if passed to the `enableClipboard` prop), but with a different input parameter:
@@ -560,7 +584,7 @@ A few helper functions, components and types that might be useful in your own im
 - `Theme`: a full [Theme](#themes--styles) object
 - `ThemeInput`: input type for the `theme` prop
 - `JsonEditorProps`: all input props for the Json Editor component
-- [`UpdateFunction`](#update-functions), [`OnChangeFunction`](#onchange-function), [`FilterFunction`](#filter-functions), [`CopyFunction`](#copy-function), [`SearchFilterFunction`](#searchfiltering), [`CompareFunction`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort), [`LocalisedString`](#localisation), [`CustomNodeDefinition`](#custom-nodes), [`CustomTextDefinitions`](#custom-text)
+- [`UpdateFunction`](#update-functions), [`OnChangeFunction`](#onchange-function), [`OnErrorFunction`](#onerror-function) [`FilterFunction`](#filter-functions), [`CopyFunction`](#copy-function), [`SearchFilterFunction`](#searchfiltering), [`CompareFunction`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort), [`LocalisedString`](#localisation), [`CustomNodeDefinition`](#custom-nodes), [`CustomTextDefinitions`](#custom-text)
 - `TranslateFunction`: function that takes a [localisation](#localisation) key and returns a translated string
 - `IconReplacements`: input type for the `icons` prop
 - `CollectionNodeProps`: all props passed internally to "collection" nodes (i.e. objects/arrays)
@@ -584,6 +608,9 @@ This component is heavily inspired by [react-json-view](https://github.com/mac-s
 
 ## Changelog
 
+- **1.12.0**:
+  - Preserve editing mode when changing Data Type
+  - [`onError` callback](#onerror-function) available for custom error handling
 - **1.11.8**: Fix regression for empty data root name introduces in 1.11.7
 - **1.11.7**: Handle \<empty-string\> object keys / prevent duplicate keys
 - **1.11.3**: Bug fix for invalid state when changing type to Collection node

demo/package.json

@@ -17,7 +17,7 @@
     "@types/react-dom": "^18.2.18",
     "firebase": "^10.7.2",
     "framer-motion": "^11.0.3",
-    "json-edit-react": "^1.11.9",
+    "json-edit-react": "^1.12.0",
     "just-compare": "^2.3.0",
     "react": "^18.2.0",
     "react-datepicker": "^5.0.0",

demo/src/App.tsx

@@ -33,10 +33,11 @@ import {
 } from '@chakra-ui/react'
 import logo from './image/logo_400.png'
 import { ArrowBackIcon, ArrowForwardIcon } from '@chakra-ui/icons'
-import { demoData } from './demoData'
+import { DemoData, demoData } from './demoData'
 import { useDatabase } from './useDatabase'
 import './style.css'
 import { version } from './version'
+import { OnErrorFunction } from './json-edit-react/src/types'
 
 function App() {
   const [selectedData, setSelectedData] = useState('intro')
@@ -260,6 +261,21 @@ function App() {
                     }
                   : undefined
               }
+              onError={
+                demoData[selectedData].onError
+                  ? (errorData) => {
+                      const error = (demoData[selectedData].onError as OnErrorFunction)(errorData)
+                      toast({
+                        title: 'ERROR 😢',
+                        description: error as any,
+                        status: 'error',
+                        duration: 5000,
+                        isClosable: true,
+                      })
+                    }
+                  : undefined
+              }
+              showErrorMessages={demoData[selectedData].showErrorMessages}
               collapse={collapseLevel}
               showCollectionCount={
                 showCount === 'Yes' ? true : showCount === 'When closed' ? 'when-closed' : false

demo/src/_imports.ts

@@ -3,10 +3,10 @@
  */
 
 /* Installed package */
-export * from 'json-edit-react'
+// export * from 'json-edit-react'
 
 /* Local src */
-// export * from './json-edit-react/src'
+export * from './json-edit-react/src'
 
 /* Compiled local package */
 // export * from './package/build'

demo/src/demoData/dataDefinitions.tsx

@@ -15,13 +15,14 @@ import {
   DataType,
   DefaultValueFunction,
   OnChangeFunction,
+  OnErrorFunction,
   SearchFilterFunction,
   ThemeStyles,
   UpdateFunction,
 } from '../json-edit-react/src/types'
 import { Input } from 'object-property-assigner/build'
 
-interface DemoData {
+export interface DemoData {
   name: string
   description: JSX.Element
   data: object
@@ -51,6 +52,8 @@ interface DemoData {
     path: CollectionKey[]
   }) => any
   onChange?: OnChangeFunction
+  onError?: OnErrorFunction
+  showErrorMessages?: boolean
   defaultValue?: unknown | DefaultValueFunction
   customNodeDefinitions?: CustomNodeDefinition[]
   customTextDefinitions?: CustomTextDefinitions
@@ -428,6 +431,12 @@ export const demoData: Record<string, DemoData> = {
         </Text>
         <Text>
           In this example, compare the raw JSON (edit the data root) with what is presented here.
+          (You can also see a custom{' '}
+          <Link href="https://github.com/CarlosNZ/json-edit-react#onerror-function" isExternal>
+            <span className="code">onError</span>
+          </Link>{' '}
+          function that displays a Toast notification rather than the standard error message when
+          you enter invalid JSON input.)
         </Text>
         <Text>
           You can also see how the property count text changes depending on the data. This is using
@@ -459,6 +468,8 @@ export const demoData: Record<string, DemoData> = {
     restrictEdit: ({ level }) => level > 0,
     restrictAdd: true,
     restrictDelete: true,
+    onError: (errorData) => errorData.error.message,
+    showErrorMessages: false,
     customNodeDefinitions: [
       {
         condition: ({ key, value }) =>

demo/src/version.ts

@@ -1 +1 @@
-export const version = '1.11.9'
+export const version = '1.12.0-rc1'

demo/yarn.lock

@@ -7965,10 +7965,10 @@ [email protected]:
   resolved "https://registry.yarnpkg.com/json-buffer/-/json-buffer-3.0.1.tgz#9338802a30d3b6605fbe0613e094008ca8c05a13"
   integrity sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==
 
-json-edit-react@^1.11.9:
-  version "1.11.9"
-  resolved "https://registry.yarnpkg.com/json-edit-react/-/json-edit-react-1.11.9.tgz#9057940f4bc6e50d057238811f80d3beedec532c"
-  integrity sha512-uhRWiJzgf8RGvcc75+lq/LNpTCw6jxM62DHN4xS3JJOuoR6AoECbKsj4xcz5i/aWs6f19OkDn6DJ9syv9VD03w==
+json-edit-react@^1.12.0:
+  version "1.12.0-rc1"
+  resolved "https://registry.yarnpkg.com/json-edit-react/-/json-edit-react-1.12.0-rc1.tgz#878338843fd872e136448c985eb9fb25ca9590a8"
+  integrity sha512-NzREei+lEtshSzSfiy/SkQz9P9CpnnJzCxTKTW7uhEo6M+y7f9cSiAh9uTWTeonO7SQH0VuShesPzmayEcQnCA==
   dependencies:
     json5 "^2.2.3"
     just-clone "^6.2.0"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-edit-react",
-  "version": "1.11.9",
+  "version": "1.12.0-rc1",
   "description": "React component for editing or viewing JSON/object data",
   "main": "build/index.cjs.js",
   "module": "build/index.esm.js",

src/CollectionNode.tsx

@@ -7,7 +7,9 @@ import {
   type CollectionNodeProps,
   type ErrorString,
   type NodeData,
+  type JerError,
   ERROR_DISPLAY_TIME,
+  CollectionData,
 } from './types'
 import { Icon } from './Icons'
 import { filterNode, isCollection } from './filterHelpers'
@@ -16,6 +18,7 @@ import { AutogrowTextArea } from './AutogrowTextArea'
 import { useTheme } from './theme'
 import { useTreeState } from './TreeStateProvider'
 import { toPathString } from './ValueNodes'
+import extractProperty from 'object-property-extractor'
 
 export const CollectionNode: React.FC<CollectionNodeProps> = ({
   data,
@@ -37,6 +40,8 @@ export const CollectionNode: React.FC<CollectionNodeProps> = ({
     onEdit,
     onAdd,
     onDelete,
+    onError: onErrorCallback,
+    showErrorMessages,
     restrictEditFilter,
     restrictDeleteFilter,
     restrictAddFilter,
@@ -112,6 +117,31 @@ export const CollectionNode: React.FC<CollectionNodeProps> = ({
     showCollectionWrapper = true,
   } = useMemo(() => getCustomNode(customNodeDefinitions, nodeData), [])
 
+  const showError = (errorString: ErrorString) => {
+    if (showErrorMessages) {
+      setError(errorString)
+      setTimeout(() => setError(null), ERROR_DISPLAY_TIME)
+    }
+    console.warn('Error', errorString)
+  }
+
+  const onError = useMemo(
+    () => (error: JerError, errorValue: CollectionData | string) => {
+      showError(error.message)
+      if (onErrorCallback) {
+        onErrorCallback({
+          currentData: nodeData.fullData,
+          errorValue,
+          currentValue: data,
+          name,
+          path,
+          error,
+        })
+      }
+    },
+    [onErrorCallback, showErrorMessages]
+  )
+
   // Early return if this node is filtered out
   if (!filterNode('collection', nodeData, searchFilter, searchText) && nodeData.level > 0) {
     return null
@@ -144,25 +174,22 @@ export const CollectionNode: React.FC<CollectionNodeProps> = ({
     }
   }
 
-  const showError = (errorString: ErrorString) => {
-    setError(errorString)
-    setTimeout(() => setError(null), ERROR_DISPLAY_TIME)
-    console.log('Error', errorString)
-  }
-
   const handleEdit = () => {
     try {
       const value = JSON5.parse(stringifiedValue)
       setCurrentlyEditingElement(null)
       setError(null)
       if (JSON.stringify(value) === JSON.stringify(data)) return
       onEdit(value, path).then((error) => {
-        if (error) showError(error)
+        if (error) {
+          onError({ code: 'UPDATE_ERROR', message: error }, value as CollectionData)
+        }
       })
     } catch {
-      setError(translate('ERROR_INVALID_JSON', nodeData))
-      setTimeout(() => setError(null), ERROR_DISPLAY_TIME)
-      console.log('Invalid JSON')
+      onError(
+        { code: 'INVALID_JSON', message: translate('ERROR_INVALID_JSON', nodeData) },
+        stringifiedValue
+      )
     }
   }
 
@@ -173,7 +200,7 @@ export const CollectionNode: React.FC<CollectionNodeProps> = ({
     const parentPath = path.slice(0, -1)
     const existingKeys = Object.keys(parentData)
     if (existingKeys.includes(newKey)) {
-      showError(translate('ERROR_KEY_EXISTS', nodeData))
+      onError({ code: 'KEY_EXISTS', message: translate('ERROR_KEY_EXISTS', nodeData) }, newKey)
       return
     }
 
@@ -194,22 +221,27 @@ export const CollectionNode: React.FC<CollectionNodeProps> = ({
     const newValue = getDefaultNewValue(nodeData)
     if (collectionType === 'array') {
       onAdd(newValue, [...path, (data as unknown[]).length]).then((error) => {
-        if (error) showError(error)
+        if (error) onError({ code: 'ADD_ERROR', message: error }, newValue as CollectionData)
       })
     } else if (key in data) {
-      showError(translate('ERROR_KEY_EXISTS', nodeData))
+      onError({ code: 'KEY_EXISTS', message: translate('ERROR_KEY_EXISTS', nodeData) }, key)
     } else {
       onAdd(newValue, [...path, key]).then((error) => {
-        if (error) showError(error)
+        if (error) onError({ code: 'ADD_ERROR', message: error }, newValue as CollectionData)
       })
     }
   }
 
   const handleDelete =
     path.length > 0
       ? () => {
-          onDelete(data, path).then((result) => {
-            if (result) showError(result)
+          onDelete(data, path).then((error) => {
+            if (error) {
+              onError(
+                { code: 'DELETE_ERROR', message: error },
+                extractProperty(data, path) as CollectionData
+              )
+            }
           })
         }
       : undefined

src/JsonEditor.tsx

@@ -27,6 +27,8 @@ const Editor: React.FC<JsonEditorProps> = ({
   onDelete: srcDelete = onUpdate,
   onAdd: srcAdd = onUpdate,
   onChange,
+  onError,
+  showErrorMessages = true,
   enableClipboard = true,
   theme = 'default',
   icons,
@@ -174,6 +176,8 @@ const Editor: React.FC<JsonEditorProps> = ({
     onDelete,
     onAdd,
     onChange,
+    onError,
+    showErrorMessages,
     showCollectionCount,
     collapseFilter,
     restrictEditFilter,