json-edit-react 0.9.6 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +102 -31
- package/build/index.cjs.js +207 -51
- package/build/index.d.ts +44 -4
- package/build/index.esm.js +208 -49
- package/package.json +11 -11
package/README.md
CHANGED
|
@@ -10,6 +10,7 @@ Features include:
|
|
|
10
10
|
- fine-grained control over which elements can be edited, deleted, or added to
|
|
11
11
|
- customisable UI, through simple, pre-defined [themes](#themes), or specific CSS overrides
|
|
12
12
|
- self-contained — rendered with plain HTML/CSS, so no dependance on external UI libraries
|
|
13
|
+
- provide your own [custom component](#custom-nodes) to integrate specialised UI for certain data.
|
|
13
14
|
|
|
14
15
|
**[Explore the Demo](https://carlosnz.github.io/json-edit-react/)**
|
|
15
16
|
|
|
@@ -28,6 +29,7 @@ Features include:
|
|
|
28
29
|
- [A note about sizing and scaling](#a-note-about-sizing-and-scaling)
|
|
29
30
|
- [Icons](#icons)
|
|
30
31
|
- [Localisation](#localisation)
|
|
32
|
+
- [Custom nodes](#custom-nodes)
|
|
31
33
|
- [Undo functionality](#undo-functionality)
|
|
32
34
|
- [Issues, bugs, suggestions?](#issues-bugs-suggestions)
|
|
33
35
|
- [Roadmap](#roadmap)
|
|
@@ -45,21 +47,28 @@ or
|
|
|
45
47
|
|
|
46
48
|
## Implementation
|
|
47
49
|
|
|
48
|
-
```
|
|
50
|
+
```jsx
|
|
49
51
|
import { JsonEditor } from 'json-edit-react'
|
|
50
52
|
|
|
51
53
|
// In your React components:
|
|
52
|
-
<JsonEditor
|
|
53
|
-
|
|
54
|
+
<JsonEditor
|
|
55
|
+
data={ myData }
|
|
56
|
+
onUpdate={ ({newData} ) => {
|
|
57
|
+
// Set "myData" state, plus
|
|
58
|
+
// any desired side-effects.
|
|
59
|
+
}}
|
|
60
|
+
{ ...otherProps } />
|
|
54
61
|
```
|
|
55
62
|
|
|
63
|
+
You are responsible for maintaining the data state — in your `onUpdate` function, use the `newData` property to set `data`, which should update inside the editor.
|
|
64
|
+
|
|
56
65
|
## Usage
|
|
57
66
|
|
|
58
67
|
**(for end user)**
|
|
59
68
|
|
|
60
69
|
It's pretty self explanatory (click the "edit" icon to edit, etc.), but there are a few not-so-obvious ways of interacting with the editor:
|
|
61
70
|
|
|
62
|
-
- Double-click a value to edit it
|
|
71
|
+
- Double-click a value (or a key) to edit it
|
|
63
72
|
- When editing a string, use `Cmd/Ctrl/Shift-Enter` to add a new line (`Enter` submits the value)
|
|
64
73
|
- It's the opposite when editing a full object/array node (which you do by clicking "edit" on an object or array value) — `Enter` for new line, and `Cmd/Ctrl/Shift-Enter` for submit
|
|
65
74
|
- `Escape` to cancel editing
|
|
@@ -67,32 +76,35 @@ It's pretty self explanatory (click the "edit" icon to edit, etc.), but there ar
|
|
|
67
76
|
|
|
68
77
|
## Props overview
|
|
69
78
|
|
|
70
|
-
The only *required* value is `data`.
|
|
71
|
-
|
|
72
|
-
| prop
|
|
73
|
-
|
|
|
74
|
-
| `data`
|
|
75
|
-
| `rootName`
|
|
76
|
-
| `onUpdate`
|
|
77
|
-
| `onUpdate`
|
|
78
|
-
| `onDelete`
|
|
79
|
-
| `onAdd`
|
|
80
|
-
| `enableClipboard`
|
|
81
|
-
| `indent`
|
|
82
|
-
| `collapse`
|
|
83
|
-
| `restrictEdit`
|
|
84
|
-
| `restrictDelete`
|
|
85
|
-
| `restrictAdd`
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
79
|
+
The only *required* value is `data`.
|
|
80
|
+
|
|
81
|
+
| prop | type | default | description |
|
|
82
|
+
| ----------------------- | -------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
83
|
+
| `data` | `object\|array` | | The data to be displayed / edited |
|
|
84
|
+
| `rootName` | `string` | `"data"` | A name to display in the editor as the root of the data object. |
|
|
85
|
+
| `onUpdate` | `UpdateFunction` | | A function to run whenever a value is **updated** (edit, delete *or* add) in the editor. See [Update functions](#update-functions). |
|
|
86
|
+
| `onUpdate` | `UpdateFunction` | | A function to run whenever a value is **edited**. |
|
|
87
|
+
| `onDelete` | `UpdateFunction` | | A function to run whenever a value is **deleted**. |
|
|
88
|
+
| `onAdd` | `UpdateFunction` | | A function to run whenever a new property is **added**. |
|
|
89
|
+
| `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. |
|
|
90
|
+
| `indent` | `number` | `4` | Specify the amount of indentation for each level of nesting in the displayed data. |
|
|
91
|
+
| `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). |
|
|
92
|
+
| `restrictEdit` | `boolean\|FilterFunction` | `false` | If `false`, no editing is permitted. A function can be provided for more specificity — see [Filter functions](#filter-functions) |
|
|
93
|
+
| `restrictDelete` | `boolean\|FilterFunction` | `false` | As with `restrictEdit` but for deletion |
|
|
94
|
+
| `restrictAdd` | `boolean\|FilterFunction` | `false` | As with `restrictEdit` but for adding new properties |
|
|
95
|
+
| `restrictTypeSelection` | `boolean\|DataType[]\|TypeFilterFunction` | `false` | For restricting the data types the user can select. This varies slightly from the above restrictions in that the value (or output of the `TypeFilterFunction`) can be a list of data types *or* a `boolean`. |
|
|
96
|
+
| `keySort` | `boolean\|CompareFunction` | `false` | If `true`, object keys will be ordered (using default JS `.sort()`). A [compare function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) can also be provided to define sorting behaviour. |
|
|
97
|
+
| `showArrayIndices` | `boolean` | `true` | Whether or not to display the index (as a property key) for array elements. |
|
|
98
|
+
| `showCollectionCount` | `boolean\|"when-closed"` | `true` | Whether or not to display the number of items in each collection (object or array). |
|
|
99
|
+
| `defaultValue` | `any` | `null` | When a new property is added, it is initialised with this value. |
|
|
100
|
+
| `stringTruncate` | `number` | `250` | String values longer than this many characters will be displayed truncated (with `...`). The full string will always be visible when editing. |
|
|
101
|
+
| `translations` | `LocalisedStrings` object | `{ }` | UI strings (such as error messages) can be translated by passing an object containing localised string values (there are only a few). See [Localisation](#localisation) |
|
|
102
|
+
| `theme` | `string\|ThemeObject\|[string, ThemeObject]` | `"default"` | Either the name of one of the built-in themes, or an object specifying some or all theme properties. See [Themes](#themes). |
|
|
103
|
+
| `className` | `string` | | Name of a CSS class to apply to the component. In most cases, specifying `theme` properties will be more straightforward. |
|
|
104
|
+
| `icons` | `{[iconName]: JSX.Element, ... }` | `{ }` | Replace the built-in icons by specifying them here. See [Themes](#themes). | |
|
|
105
|
+
| `minWidth` | `number\|string` (CSS value) | `250` | Minimum width for the editor container. |
|
|
106
|
+
| `maxWidth` | `number\|string` (CSS value) | `600` | Maximum width for the editor container. |
|
|
107
|
+
| `customNodeDefinitions` | `CustomNodeDefinition[]` | | You can provide customised components to override specific nodes in the data tree, according to a condition function. See see [Custom nodes](#custom-nodes) for more detail. |
|
|
96
108
|
|
|
97
109
|
## Update functions
|
|
98
110
|
|
|
@@ -131,7 +143,7 @@ Since there is very little user feedback when clicking "Copy", a good idea would
|
|
|
131
143
|
|
|
132
144
|
## Filter functions
|
|
133
145
|
|
|
134
|
-
You can control which nodes of the data structure can be edited, deleted, or added to by passing Filter functions. These will be called on each property in the data and the attribute will be enforced depending on whether the function returns `true` or `false` (`true` means *cannot* be edited).
|
|
146
|
+
You can control which nodes of the data structure can be edited, deleted, or added to, or have their data type changed, by passing Filter functions. These will be called on each property in the data and the attribute will be enforced depending on whether the function returns `true` or `false` (`true` means *cannot* be edited).
|
|
135
147
|
|
|
136
148
|
The function receives the following object:
|
|
137
149
|
```js
|
|
@@ -146,6 +158,18 @@ The function receives the following object:
|
|
|
146
158
|
|
|
147
159
|
A Filter function is available for the `collapse` prop as well, so you can have your data appear with deeply-nested collections opened up, while collapsing everything else, for example.
|
|
148
160
|
|
|
161
|
+
For restricting data types, the (Type) filter function is slightly more sophisticated. The input is the same, but the output can be either a `boolean` (which would restrict the available types for a given node to either *all* or *none*), or an array of data types to be restricted to. The available values are:
|
|
162
|
+
- `"string"`
|
|
163
|
+
- `"number"`
|
|
164
|
+
- `"boolean"`
|
|
165
|
+
- `"null"`
|
|
166
|
+
- `"object"`
|
|
167
|
+
- `"array"`
|
|
168
|
+
|
|
169
|
+
There is no specific restriction function for editing object key names, but they must return `true` for *both* `restrictEdit` and `restrictDelete` (and `restrictAdd` for collections), since changing a key name is equivalent to deleting a property and adding a new one.
|
|
170
|
+
|
|
171
|
+
Using all these restriction filters together can allow you to enforce a reasonably sophisticated data schema.
|
|
172
|
+
|
|
149
173
|
### Examples
|
|
150
174
|
|
|
151
175
|
- A good case would be ensure your root node is not directly editable:
|
|
@@ -174,6 +198,20 @@ restrictAdd = { ({ key }) => key !== "address" && key !== "users" }
|
|
|
174
198
|
// "Adding" is irrelevant for non-collection nodes
|
|
175
199
|
```
|
|
176
200
|
|
|
201
|
+
- Multiple type restrictions:
|
|
202
|
+
- `string` values can only be changed to strings or objects (for nesting)
|
|
203
|
+
- `null` is not allowed anywhere
|
|
204
|
+
- `boolean` values must remain boolean
|
|
205
|
+
- data nested below the "user" field can be any simple property (i.e. not objects or arrays), and doesn't have to follow the above rules (except no "null")
|
|
206
|
+
```js
|
|
207
|
+
restrictTypeSelection = { ({ path, value }) => {
|
|
208
|
+
if (path.includes('user')) return ['string', 'number', 'boolean']
|
|
209
|
+
if (typeof value === 'boolean') return false
|
|
210
|
+
if (typeof value === 'string') return ['string', 'object']
|
|
211
|
+
return ['string', 'number', 'boolean', 'array', 'object'] // no "null"
|
|
212
|
+
} }
|
|
213
|
+
```
|
|
214
|
+
|
|
177
215
|
## Themes
|
|
178
216
|
|
|
179
217
|
There is a small selection of built-in themes (as seen in the [Demo app](https://carlosnz.github.io/json-edit-react/)). In order to use one of these, just pass the name into the `theme` prop (although realistically, these exist more to showcase the capabilities — I'm open to better built-in themes, so feel free to [create an issue](https://github.com/CarlosNZ/json-edit-react/issues) with suggestions). The available themes are:
|
|
@@ -313,6 +351,32 @@ Localise your implementation by passing in a `translations` object to replace th
|
|
|
313
351
|
|
|
314
352
|
```
|
|
315
353
|
|
|
354
|
+
## Custom nodes
|
|
355
|
+
|
|
356
|
+
You can replace certain nodes in the data tree with your own custom components. An example might be for an image display, or a custom date editor, or just to add some visual bling. See the "Custom Nodes" data set in the [interactive demo](https://carlosnz.github.io/json-edit-react/) to see it in action.
|
|
357
|
+
|
|
358
|
+
Custom nodes are provided in the `customNodeDefinitions` prop, as an array of objects of following structure:
|
|
359
|
+
|
|
360
|
+
```js
|
|
361
|
+
{
|
|
362
|
+
condition, // a FilterFunction, as above
|
|
363
|
+
element, // React Component
|
|
364
|
+
props, // object (optional)
|
|
365
|
+
hideKey, // boolean (optional)
|
|
366
|
+
showInTypesSelector, // boolean (optional)
|
|
367
|
+
defaultValue, // JSON value for a new instance of your component
|
|
368
|
+
name // string
|
|
369
|
+
}
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
The `condition` is just a [Filter function](#filter-functions), with the same input parameters (`key`, `path`, `level`, `value`, `size`), and `element` is a React component. Every node in the data structure will be run through each condition function, and any that match will be replaced by your custom component. Note that if a node matches more than one custom definition conditions (from multiple components), the *first* one will be used, so place them in the array in priority order.
|
|
373
|
+
|
|
374
|
+
The component will receive *all* the same props as a standard node component (see codebase), but you can pass additional props to your component if required through the `props` object.
|
|
375
|
+
|
|
376
|
+
By default, your component will be presented to the right of the property key it belongs to, like any other value. However, you can hide the key itself by setting `hideKey: true`, and the custom component will take the whole row. (See the "Presented by" box in the "Custom Nodes" data set for an example.)
|
|
377
|
+
|
|
378
|
+
You can allow users to create new instances of your special nodes by selecting them as a "Type" in the types selector when editing/adding values. Set `showInTypesSelector: true` to enable this. However, if this is enabled you need to also provide a `name` (which is what the user will see in the selector) and a `defaultValue` which is the data that is inserted when the user selects this "type". (The `defaultValue` must return `true` if passed through the `condition` function in order for it to be immediately displayed using your custom component.)
|
|
379
|
+
|
|
316
380
|
## Undo functionality
|
|
317
381
|
|
|
318
382
|
Even though Undo/Redo functionality is probably desirable in most cases, this is not built in to the component, for two main reasons:
|
|
@@ -337,6 +401,13 @@ This component is heavily inspired by [react-json-view](https://github.com/mac-s
|
|
|
337
401
|
|
|
338
402
|
## Changelog
|
|
339
403
|
|
|
404
|
+
- **1.1.0**: Don't manage data state within component
|
|
405
|
+
- **1.0.0**:
|
|
406
|
+
- [Custom nodes](#custom-nodes)
|
|
407
|
+
- Allow editing of keys
|
|
408
|
+
- Option to define restrictions on data type selection
|
|
409
|
+
- Option to hide array/object item counts
|
|
410
|
+
- Improve keyboard interaction
|
|
340
411
|
- **0.9.6**: Performance improvement by not processing child elements if not visible
|
|
341
412
|
- **0.9.4**:
|
|
342
413
|
- Layout improvements
|