@zeta-ui/json-tree NPM

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

prop-types react-editable-json-tree

0.0.1

2 months ago