JSON Tree

Install

npm install zeta-global/json-tree
# or
yarn add zeta-global/json-tree

Example Usage

// Import
import {
    JsonTree,
    ADD_DELTA_TYPE,
    REMOVE_DELTA_TYPE,
    UPDATE_DELTA_TYPE,
    DATA_TYPES,
    INPUT_USAGE_TYPES,
} from 'zeta-global/json-tree'

// Data
const data = {
    error: new Error('error'),
    text: 'text',
    int: 100,
    boolean: true,
    null: null,
    object: {
        text: 'text',
        int: 100,
        boolean: true,
    },
    array: [
        1,
        {
            string: 'test',
        },
    ],
}

// Component
<JsonTree data={data} />

Props

data

| Key | Description | Type | Required | Default | | :--: | :-------------------------: | :------------------------------: | :------: | :-----: | | data | Data to be displayed/edited | Object | Array | True | None |

rootName

| Key | Description | Type | Required | Default | | :------: | :---------------------: | :------: | :------: | :-----: | | rootName | Name of the root object | string | False | root |

isCollapsed

| Key | Description | Type | Required | Default | | :---------: | :----------------------------------------------------: | :--------: | :------: | :-------------------------------: | | isCollapsed | Whether the node is collapsed (for Array/Object/Error) | Function | False | (keyPath, deep) => (deep !== 0) |

Function parameters:

| Key | Description | Type | Example | | :-----: | :----------------------------: | :--------: | :-------------------------------------------------------------: | | keyPath | Path to the current node/value | string[] | ['object'] for data: { object: { string: 'test' } } | | deep | Depth of the current node | number | 1 for data: { object: { string: 'test' } } on 'object' node | | data | Data of the current node/value | unknown | { string: 'test' } for data: { object: { string: 'test' } } |

onFullyUpdate

| Key | Description | Type | Required | Default | | :-----------: | :--------------------------------------------------------------------------: | :--------: | :------: | :--------: | | onFullyUpdate | Callback function called upon each update with the entire new data structure | Function | False | () => {} |

Function parameters:

| Key | Description | Type | | :--: | :----------: | :-------------------------------------------------------------: | | data | Updated data | Object | Array (same type as the data prop) |

onDeltaUpdate

| Key | Description | Type | Required | Default | | :-----------: | :---------------------------------------------------------------------------: | :--------: | :------: | :--------: | | onDeltaUpdate | Callback function called upon each update with only the data that has changed | Function | False | () => {} |

Function parameters:

| Key | Description | Type | | :--: | :---------: | :------: | | data | Delta data | Object |

Delta data structure:

| Key | Description | Type | Example | | :------: | :-------------------------------: | :--------: | :-----------------------------------------------------------------: | | type | Delta type | string | 'ADD_DELTA_TYPE', 'REMOVE_DELTA_TYPE', or 'UPDATE_DELTA_TYPE' | | keyPath | Path to the current node/value | string[] | ['object'] for data: { object: { string: 'test' } } | | deep | Depth of the current node | number | 1 for data: { object: { string: 'test' } } on 'object' node | | key | Modified/created/removed key name | string | None | | newValue | New value | unknown | None | | oldValue | Old value | unknown | None |

readOnly

| Key | Description | Type | Required | Default | | :------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------: | :------: | :-------------------------------------------------: | | readOnly | If a boolean, whether the entire structure should be read-only. If a function, whether the node/value supplied to the function should be read-only (called for all nodes/values). | boolean | Function | False | (keyName, data, keyPath, deep, dataType) => false |

This function must return a boolean.

Function parameters:

| Key | Description | Type | Example | | :------: | :---------------------------------: | :--------: | :------------------------------------------------------------------------: | | keyName | Key name of the current node/value | string | 'object' for data: { object: { string: 'test' } } | | data | Data of the current node/value | unknown | { string: 'test' } for data: { object: { string: 'test' } } | | keyPath | Path to the current node/value | string[] | ['object'] for data: { object: { string: 'test' } } | | deep | Depth of the current node | number | 1 for data: { object: { string: 'test' } } on 'object' node | | dataType | Data type of the current node/value | string | 'Object', 'Array', 'Null', 'Undefined', 'Error', 'Number', ... |

getStyle

| Key | Description | Type | Required | Default | | :------: | :---------------------------------------------------------------------: | :--------: | :------: | :-------------------------------------------------: | | getStyle | Callback function which should return the CSS style for each node/value | Function | False | (keyName, data, keyPath, deep, dataType) => {...} |

Function parameters:

| Key | Description | Type | Example | | :------: | :---------------------------------: | :--------: | :------------------------------------------------------------------------: | | keyName | Key name of the current node/value | string | 'object' for data: { object: { string: 'test' } } | | data | data of the current node/value | unknown | { string: 'test' } for data: { object: { string: 'test' } } | | keyPath | Path to the current node/value | string[] | ['object'] for data: { object: { string: 'test' } } | | deep | Depth of the current node | number | 1 for data: { object: { string: 'test' } } on 'object' node | | dataType | Data type of the current node/value | string | 'Object', 'Array', 'Null', 'Undefined', 'Error', 'Number', ... |

An example of return:

{
    minus: {
        color: 'red',
    },
    plus: {
        color: 'green',
    },
    collapsed: {
        color: 'grey',
    },
    delimiter: {},
    ul: {
        padding: '0px',
        margin: '0 0 0 25px',
        listStyle: 'none',
    },
    name: {
        color: '#2287CD',
    },
    addForm: {},
}

You can see the default style definitions in src/utils/styles.js.

addButtonElement

| Key | Description | Type | Required | Default | | :--------------: | :--------------------------------------------------------------------------: | :-----------: | :------: | :------------------: | | addButtonElement | Custom add button element (to confirm adding a new value to an object/array) | JSX.Element | False | <button>+</button> |

The library will add an onClick handler to the element.

cancelButtonElement

| Key | Description | Type | Required | Default | | :-----------------: | :------------------------------------------------------: | :-----------: | :------: | :------------------: | | cancelButtonElement | Custom cancel button element (to cancel editing a value) | JSX.Element | False | <button>c</button> |

The library will add an onClick handler to the element.

editButtonElement

| Key | Description | Type | Required | Default | | :---------------: | :----------------------------------------------------: | :-----------: | :------: | :------------------: | | editButtonElement | Custom edit button element (to finish editing a value) | JSX.Element | False | <button>e</button> |

The library will add an onClick handler to the element.

inputElement

| Key | Description | Type | Required | Default | | :----------: | :-----------------------------------------: | :--------------------------------------: | :------: | :------------------------------------------------------------: | | inputElement | Custom text input element (to edit a value) | JSX.Element | Function | False | (usage, keyPath, deep, keyName, data, dataType) => <input /> |

The library will add a placeholder, ref, and defaultValue prop to the element. This element will be focused when possible.

Function parameters:

| Key | Description | Type | Example | | :------: | :----------------------------: | :--------: | :-------------------------------------------------------------------------------------------------------------------------------------------: | | usage | Usage of the generated input | string | All values are listed in INPUT_USAGE_TYPES | | keyPath | Path to the current node/value | string[] | [] for data: { object: { string: 'test' } } | | deep | Depth of the current node | number | 1 for data: { object: { string: 'test' } } on 'object' node | | key | Key of the current node/value | string | 'object' for data: { object: { string: 'test' } } | | value | Value of the key | unknown | { string: 'test' } for data: { object: { string: 'test' } } on 'object' node | | dataType | Data type of the value | string | All values are listed in DATA_TYPES |

textareaElement

| Key | Description | Type | Required | Default | | :-------------: | :------------------------------------------------------------: | :--------------------------------------: | :------: | :---------------------------------------------------------------: | | textareaElement | Custom textarea element (to edit a long value, like functions) | JSX.Element | Function | False | (usage, keyPath, deep, keyName, data, dataType) => <textarea /> |

The library will add a ref and defaultValue prop to the element. This element will be focused when possible.

Function parameters:

| Key | Description | Type | Example | | :------: | :----------------------------: | :--------: | :-------------------------------------------------------------------------------------------------------------------------------------------: | | usage | Usage of the generated input | string | All values are listed in INPUT_USAGE_TYPES | | keyPath | Path to the current node/value | string[] | [] for data: { object: { string: 'test' } } | | deep | Depth of the current node | number | 1 for data: { object: { string: 'test' } } on 'object' node | | key | Key of the current node/value | string | 'object' for data: { object: { string: 'test' } } | | value | Value of the key | unknown | { string: 'test' } for data: { object: { string: 'test' } } on 'object' node | | dataType | Data type of the value | string | All values are listed in DATA_TYPES |

minusMenuElement

| Key | Description | Type | Required | Default | | :--------------: | :----------------------------------------------------------------: | :-----------: | :------: | :----------------: | | minusMenuElement | Custom minus menu element (to remove a value from an object/array) | JSX.Element | False | <span> - </span> |

The library will add an onClick, className, and style prop to the element.

plusMenuElement

| Key | Description | Type | Required | Default | | :-------------: | :-----------------------------------------------------------------------: | :-----------: | :------: | :----------------: | | plusMenuElement | Custom plus menu element (to begin adding a new value to an object/array) | JSX.Element | False | <span> + </span> |

The library will add an onClick, className, and style prop to the element.

beforeRemoveAction

| Key | Description | Type | Required | Default | | :----------------: | :-------------------------------------------------------------------------------------------: | :--------: | :------: | :-------------------------------------------------------------------: | | beforeRemoveAction | Async function called upon the user trying to remove a node/value with the minus menu element | Function | False | (key, keyPath, deep, oldValue) => new Promise(resolve => resolve()) |

This function must return a Promise. If the promise is resolved, the node/value will be removed. Otherwise, if rejected, nothing will be done.

Function parameters:

| Key | Description | Type | Example | | :------: | :--------------------------------: | :--------: | :------------------------------------------------------------------------------: | | key | Key name of the current node/value | string | 'object' for data: { object: { string: 'test' } } | | keyPath | Path to the current node/value | string[] | [] for data: { object: { string: 'test' } } | | deep | Depth of the current node | number | 1 for data: { object: { string: 'test' } } on 'object' node | | oldValue | Old value of the key | unknown | { string: 'test' } for data: { object: { string: 'test' } } on 'object' node |

beforeAddAction

| Key | Description | Type | Required | Default | | :-------------: | :--------------------------------------------------------------------------------------: | :--------: | :------: | :-------------------------------------------------------------------: | | beforeAddAction | Async function called upon the user trying to add a node/value with the add menu element | Function | False | (key, keyPath, deep, newValue) => new Promise(resolve => resolve()) |

This function must return a Promise. If the promise is resolved, the node/value will be added. Otherwise, if rejected, nothing will be done.

Function parameters:

| Key | Description | Type | Example | | :------: | :----------------------------: | :--------: | :------------------------------------------------------------------: | | key | Key of the current node/value | string | 'string' for data: { object: { string: 'test' } } | | keyPath | Path to the current node/value | string[] | ['object'] for data: { object: { string: 'test' } } | | deep | Depth of the current node | number | 1 for data: { object: { string: 'test' } } on 'object' node | | newValue | New value of the key | unknown | 'test' for data: { object: { string: 'test' } } on 'string' node |

beforeUpdateAction

| Key | Description | Type | Required | Default | | :----------------: | :-------------------------------------------------------------: | :--------: | :------: | :-----------------------------------------------------------------------------: | | beforeUpdateAction | Async function called upon the user trying to edit a node/value | Function | False | (key, keyPath, deep, oldValue, newValue) => new Promise(resolve => resolve()) |

This function must return a Promise. If the promise is resolved, the node/value will be updated. Otherwise, if rejected, nothing will be done.

Function parameters:

| Key | Description | Type | Example | | :------: | :----------------------------: | :--------: | :----------------------------------------------------------------------: | | key | Key of the current node/value | string | 'string' for data: { object: { string: 'test' } } | | keyPath | Path to the current node/value | string[] | ['object'] for data: { object: { string: 'test' } } | | deep | Depth of the current node | number | 1 for data: { object: { string: 'test' } } on 'object' node | | oldValue | Old value of the key | unknown | 'test' for data: { object: { string: 'test' } } on 'string' node | | newValue | New value of the key | unknown | 'update' for data: { object: { string: 'update' } } on 'string' node |

logger

| Key | Description | Type | Required | Default | | :----: | :-------------------------------------------------------------------------: | :------: | :------: | :-------------------: | | logger | Object used to log errors caught from promises (using only the 'error' key) | Object | False | { error: () => {} } |

onSubmitValueParser

| Key | Description | Type | Required | Default | | :-----------------: | :--------------------------------------------------------------------------------------------------------------------------------------------: | :--------: | :------: | :--------------------------------------------------------------------: | | onSubmitValueParser | Function called upon every value addition/update to parse raw string data from inputElements or textareaElements into the correct object types | Function | False | (isEditMode, keyPath, deep, key, rawValue) => nativeParser(rawValue) |

Function parameters:

| Key | Description | Type | Example | | :--------: | :-------------------------------------------------------------------------------------------: | :--------: | :-------------------------------------------------------------: | | isEditMode | Whether the value is being edited on an existing node/value, otherwise it's being newly added | boolean | True | | keyPath | Path to the current node/value | string[] | ['object'] for data: { object: { string: 'test' } } | | deep | Depth of the current node | number | 1 for data: { object: { string: 'test' } } on 'object' node | | key | Key of the current node/value | string | 'string' for data: { object: { string: 'test' } } | | rawValue | Raw string value from the inputElement or textareaElement | string | 'test' for data: { object: { string: 'test' } } |

allowFunctionEvaluation

| Key | Description | Type | Required | Default | | :---------------------: | :-----------------------------------------------------------------------------------------------------: | :-------: | :------: | :-----: | | allowFunctionEvaluation | Allow strings that appear to be Javascript function definitions to be evaluated as Javascript functions | boolean | False | True |

Development

npm commands

Build

Build the library to dist/ using parcel.

npm run build

Publish

Publishes the library to npm. This runs a parcel build.

npm publish