feat: implement support for vanilla JS components in onRenderValue using Svelte Action (#398)

Author: josdejong

README.md

@@ -279,118 +279,148 @@ const editor = new JSONEditor({
 
   To adjust the text color of keys or values, the color of the classes `.jse-key` and `.jse-value` can be overwritten.
 
-  - `onRenderValue(props: RenderValueProps) : RenderValueComponentDescription[]`
+- `onRenderValue(props: RenderValueProps) : RenderValueComponentDescription[]`
 
-    _EXPERIMENTAL! This API will most likely change in future versions._
+  Customize rendering of the values. By default, `renderValue` is used, which renders a value as an editable div and depending on the value can also render a boolean toggle, a color picker, and a timestamp tag. Multiple components can be rendered alongside each other, like the boolean toggle and color picker being rendered left from the editable div. Built in value renderer components: `EditableValue`, `ReadonlyValue`, `BooleanToggle`, `ColorPicker`, `TimestampTag`, `EnumValue`.
 
-    Customize rendering of the values. By default, `renderValue` is used, which renders a value as an editable div and depending on the value can also render a boolean toggle, a color picker, and a timestamp tag. Multiple components can be rendered alongside each other, like the boolean toggle and color picker being rendered left from the editable div. Built in value renderer components: `EditableValue`, `ReadonlyValue`, `BooleanToggle`, `ColorPicker`, `TimestampTag`, `EnumValue`.
+  For JSON Schema enums, there is a ready-made value renderer `renderJSONSchemaEnum` which renders enums using the `EnumValue` component. This can be used like:
 
-    For JSON Schema enums, there is a value renderer `renderJSONSchemaEnum` which renders enums using the `EnumValue` component. This can be used like:
+  ```js
+  import { renderJSONSchemaEnum, renderValue } from 'svelte-jsoneditor'
+
+  function onRenderValue(props) {
+    // use the enum renderer, and fallback on the default renderer
+    return renderJSONSchemaEnum(props, schema, schemaDefinitions) || renderValue(props)
+  }
+  ```
+
+  The callback `onRenderValue` must return an array with one or multiple renderers. Each renderer can be either a Svelte component or a Svelte action:
+
+  ```ts
+  interface SvelteComponentRenderer {
+    component: typeof SvelteComponent<RenderValuePropsOptional>
+    props: Record<string, unknown>
+  }
+
+  interface SvelteActionRenderer {
+    action: Action // Svelte Action
+    props: Record<string, unknown>
+  }
+  ```
 
-    ```js
-    import { renderJSONSchemaEnum, renderValue } from 'svelte-jsoneditor'
+  The `SvelteComponentRenderer` interface can be used to provide Svelte components like the `EnumValue` component mentioned above. The `SvelteActionRenderer` expects a [Svelte Action](https://svelte.dev/docs/svelte-action) as `action` property. Since this interface is a plain JavaScript interface, this allows to create custom components in a vanilla JS environment. Basically it is a function that gets a DOM node passed, and needs to return an object with `update` and `destroy` functions:
 
-    function onRenderValue(props) {
-      // use the enum renderer, and fallback on the default renderer
-      return renderJSONSchemaEnum(props, schema, schemaDefinitions) || renderValue(props)
+  ```js
+  const myRendererAction = {
+    action: (node) => {
+      // attach something to the HTML DOM node
+      return {
+        update: (node) => {
+          // update the DOM
+        },
+        destroy: () => {
+          // cleanup the DOM
+        }
+      }
+    }
+  }
+  ```
+
+- `onRenderMenu(items: MenuItem[], context: { mode: 'tree' | 'text' | 'table', modal: boolean }) : MenuItem[] | undefined`.
+  Callback which can be used to make changes to the menu items. New items can
+  be added, or existing items can be removed or reorganized. When the function
+  returns `undefined`, the original `items` will be applied. Using the context values `mode` and `modal`, different actions can be taken depending on the mode of the editor and whether the editor is rendered inside a modal or not.
+
+  A menu item `MenuItem` can be one of the following types:
+
+  - Button:
+
+    ```ts
+    interface MenuButton {
+      type: 'button'
+      onClick: () => void
+      icon?: IconDefinition
+      text?: string
+      title?: string
+      className?: string
+      disabled?: boolean
     }
     ```
 
-  - `onRenderMenu(items: MenuItem[], context: { mode: 'tree' | 'text' | 'table', modal: boolean }) : MenuItem[] | undefined`.
-    Callback which can be used to make changes to the menu items. New items can
-    be added, or existing items can be removed or reorganized. When the function
-    returns `undefined`, the original `items` will be applied. Using the context values `mode` and `modal`, different actions can be taken depending on the mode of the editor and whether the editor is rendered inside a modal or not.
+  - Separator (gray vertical line between a group of items):
 
-    A menu item `MenuItem` can be one of the following types:
+    ```ts
+    interface MenuSeparator {
+      type: 'separator'
+    }
+    ```
 
-    - Button:
+  - Space (fills up empty space):
 
-      ```ts
-      interface MenuButton {
-        type: 'button'
-        onClick: () => void
-        icon?: IconDefinition
-        text?: string
-        title?: string
-        className?: string
-        disabled?: boolean
-      }
-      ```
+    ```ts
+    interface MenuSpace {
+      type: 'space'
+    }
+    ```
 
-    - Separator (gray vertical line between a group of items):
+- `onRenderContextMenu(items: ContextMenuItem[], context: { mode: 'tree' | 'text' | 'table', modal: boolean, selection: JSONEditorSelection | null }) : ContextMenuItem[] | undefined`.
+  Callback which can be used to make changes to the context menu items. New items can
+  be added, or existing items can be removed or reorganized. When the function
+  returns `undefined`, the original `items` will be applied. Using the context values `mode`, `modal` and `selection`, different actions can be taken depending on the mode of the editor, whether the editor is rendered inside a modal or not and the path of selection.
 
-      ```ts
-      interface MenuSeparator {
-        type: 'separator'
-      }
-      ```
+  A menu item `ContextMenuItem` can be one of the following types:
 
-    - Space (fills up empty space):
+  - Button:
 
-      ```ts
-      interface MenuSpace {
-        type: 'space'
-      }
-      ```
-
-  - `onRenderContextMenu(items: ContextMenuItem[], context: { mode: 'tree' | 'text' | 'table', modal: boolean, selection: JSONEditorSelection | null }) : ContextMenuItem[] | undefined`.
-    Callback which can be used to make changes to the context menu items. New items can
-    be added, or existing items can be removed or reorganized. When the function
-    returns `undefined`, the original `items` will be applied. Using the context values `mode`, `modal` and `selection`, different actions can be taken depending on the mode of the editor, whether the editor is rendered inside a modal or not and the path of selection.
-
-    A menu item `ContextMenuItem` can be one of the following types:
-
-    - Button:
-
-      ```ts
-      interface MenuButton {
-        type: 'button'
-        onClick: () => void
-        icon?: IconDefinition
-        text?: string
-        title?: string
-        className?: string
-        disabled?: boolean
-      }
-      ```
+    ```ts
+    interface MenuButton {
+      type: 'button'
+      onClick: () => void
+      icon?: IconDefinition
+      text?: string
+      title?: string
+      className?: string
+      disabled?: boolean
+    }
+    ```
 
-    - Dropdown button:
+  - Dropdown button:
 
-      ```ts
-      interface MenuDropDownButton {
-        type: 'dropdown-button'
-        main: MenuButton
-        width?: string
-        items: MenuButton[]
-      }
-      ```
+    ```ts
+    interface MenuDropDownButton {
+      type: 'dropdown-button'
+      main: MenuButton
+      width?: string
+      items: MenuButton[]
+    }
+    ```
 
-    - Separator (gray line between a group of items):
+  - Separator (gray line between a group of items):
 
-      ```ts
-      interface MenuSeparator {
-        type: 'separator'
-      }
-      ```
+    ```ts
+    interface MenuSeparator {
+      type: 'separator'
+    }
+    ```
 
-    - Menu row and column:
+  - Menu row and column:
 
-      ```ts
-      interface MenuLabel {
-        type: 'label'
-        text: string
-      }
+    ```ts
+    interface MenuLabel {
+      type: 'label'
+      text: string
+    }
 
-      interface ContextMenuColumn {
-        type: 'column'
-        items: Array<MenuButton | MenuDropDownButton | MenuLabel | MenuSeparator>
-      }
+    interface ContextMenuColumn {
+      type: 'column'
+      items: Array<MenuButton | MenuDropDownButton | MenuLabel | MenuSeparator>
+    }
 
-      interface ContextMenuRow {
-        type: 'row'
-        items: Array<MenuButton | MenuDropDownButton | ContextMenuColumn>
-      }
-      ```
+    interface ContextMenuRow {
+      type: 'row'
+      items: Array<MenuButton | MenuDropDownButton | ContextMenuColumn>
+    }
+    ```
 
 - `onSelect: (selection: JSONEditorSelection | null) => void`
 

src/lib/components/__snapshots__/JSONEditor.test.ts.snap

@@ -300,6 +300,7 @@ exports[`JSONEditor > render table mode 1`] = `
                   
                   
                   
+                  
                   <!--&lt;JSONValue&gt;-->
                   
                   
@@ -320,6 +321,7 @@ exports[`JSONEditor > render table mode 1`] = `
                   
                   
                   
+                  
                   <!--&lt;JSONValue&gt;-->
                   
                   
@@ -352,6 +354,7 @@ exports[`JSONEditor > render table mode 1`] = `
                   
                   
                   
+                  
                   <!--&lt;JSONValue&gt;-->
                   
                   
@@ -372,6 +375,7 @@ exports[`JSONEditor > render table mode 1`] = `
                   
                   
                   
+                  
                   <!--&lt;JSONValue&gt;-->
                   
                   
@@ -404,6 +408,7 @@ exports[`JSONEditor > render table mode 1`] = `
                   
                   
                   
+                  
                   <!--&lt;JSONValue&gt;-->
                   
                   
@@ -424,6 +429,7 @@ exports[`JSONEditor > render table mode 1`] = `
                   
                   
                   
+                  
                   <!--&lt;JSONValue&gt;-->
                   
                   
@@ -1649,6 +1655,7 @@ exports[`JSONEditor > render tree mode 1`] = `
                         
                         
                         
+                        
                         <!--&lt;JSONValue&gt;-->
                          
                       </div>
@@ -1825,6 +1832,7 @@ exports[`JSONEditor > render tree mode 1`] = `
                         
                         
                         
+                        
                         <!--&lt;JSONValue&gt;-->
                          
                       </div>
@@ -1888,6 +1896,7 @@ exports[`JSONEditor > render tree mode 1`] = `
                         
                         
                         
+                        
                         <!--&lt;JSONValue&gt;-->
                          
                       </div>
@@ -2064,6 +2073,7 @@ exports[`JSONEditor > render tree mode 1`] = `
                         
                         
                         
+                        
                         <!--&lt;JSONValue&gt;-->
                          
                       </div>

src/lib/components/modes/tablemode/JSONValue.svelte

@@ -7,6 +7,7 @@
     JSONSelection,
     SearchResultItem
   } from '$lib/types'
+  import { isSvelteActionRenderer } from '$lib/typeguards.js'
   import type { JSONPatchDocument, JSONPath } from 'immutable-json-patch'
   import { isEditingSelection, isValueSelection } from '$lib/logic/selection.js'
   import { createNestedValueOperations } from '$lib/logic/operations.js'
@@ -47,7 +48,20 @@
 </script>
 
 {#each renderers as renderer}
-  {#key renderer.component}
-    <svelte:component this={renderer.component} {...renderer.props} />
-  {/key}
+  {#if isSvelteActionRenderer(renderer)}
+    {@const action = renderer.action}
+    {#key renderer.action}
+      <div
+        role="button"
+        tabindex="-1"
+        class="jse-value jse-readonly-password"
+        data-type="selectable-value"
+        use:action={renderer.props}
+      />
+    {/key}
+  {:else}
+    {#key renderer.component}
+      <svelte:component this={renderer.component} {...renderer.props} />
+    {/key}
+  {/if}
 {/each}

src/lib/components/modes/treemode/JSONValue.svelte

@@ -4,6 +4,7 @@
   import type { JSONEditorContext, JSONSelection, SearchResultItem } from '$lib/types.js'
   import type { JSONPath } from 'immutable-json-patch'
   import { isEditingSelection, isValueSelection } from '$lib/logic/selection.js'
+  import { isSvelteActionRenderer } from '$lib/typeguards.js'
 
   export let path: JSONPath
   export let value: unknown
@@ -34,7 +35,20 @@
 </script>
 
 {#each renderers as renderer}
-  {#key renderer.component}
-    <svelte:component this={renderer.component} {...renderer.props} />
-  {/key}
+  {#if isSvelteActionRenderer(renderer)}
+    {@const action = renderer.action}
+    {#key renderer.action}
+      <div
+        role="button"
+        tabindex="-1"
+        class="jse-value jse-readonly-password"
+        data-type="selectable-value"
+        use:action={renderer.props}
+      />
+    {/key}
+  {:else}
+    {#key renderer.component}
+      <svelte:component this={renderer.component} {...renderer.props} />
+    {/key}
+  {/if}
 {/each}

src/lib/typeguards.ts

@@ -9,7 +9,9 @@ import type {
   MenuSeparator,
   MenuSpace,
   ValidationError,
-  NestedValidationError
+  NestedValidationError,
+  SvelteActionRenderer,
+  SvelteComponentRenderer
 } from './types.js'
 import { isObject } from '$lib/utils/typeUtils.js'
 
@@ -88,3 +90,11 @@ export function isValidationError(value: unknown): value is ValidationError {
 export function isNestedValidationError(value: unknown): value is NestedValidationError {
   return isObject(value) && isValidationError(value) && typeof value.isChildError === 'boolean'
 }
+
+export function isSvelteComponentRenderer(value: unknown): value is SvelteComponentRenderer {
+  return isObject(value) && 'component' in value && isObject(value.props)
+}
+
+export function isSvelteActionRenderer(value: unknown): value is SvelteActionRenderer {
+  return isObject(value) && typeof value.action === 'function' && isObject(value.props)
+}

src/lib/types.ts

@@ -1,6 +1,7 @@
 import type { JSONPatchDocument, JSONPath, JSONPointer } from 'immutable-json-patch'
 import type { SvelteComponent } from 'svelte'
 import type { IconDefinition } from '@fortawesome/free-solid-svg-icons'
+import type { Action } from 'svelte/action'
 
 export type TextContent = { text: string }
 
@@ -541,11 +542,18 @@ export interface DraggingState {
   didMoveItems: boolean
 }
 
-export interface RenderValueComponentDescription {
+export type RenderValueComponentDescription = SvelteComponentRenderer | SvelteActionRenderer
+
+export interface SvelteComponentRenderer {
   component: typeof SvelteComponent<RenderValuePropsOptional>
   props: Record<string, unknown>
 }
 
+export interface SvelteActionRenderer {
+  action: Action<HTMLElement, Record<string, unknown>>
+  props: Record<string, unknown>
+}
+
 export interface TransformModalOptions {
   id?: string
   rootPath?: JSONPath

src/routes/+page.svelte

@@ -33,7 +33,7 @@
       <a href="examples/custom_json_parser">Custom JSON Parser (Lossless JSON)</a>
     </li>
     <li>
-      <a href="examples/custom_value_renderer">Custom value renderer (password, enum)</a>
+      <a href="examples/custom_value_renderer">Custom value renderer (password, enum, action)</a>
     </li>
     <li>
       <a href="examples/json_schema_validation">JSON Schema validation</a>

src/routes/components/EvaluatorAction.ts

@@ -0,0 +1,58 @@
+import { createValueSelection, type OnJSONSelect } from 'svelte-jsoneditor'
+import type { Action } from 'svelte/action'
+import { type JSONPath } from 'immutable-json-patch'
+
+export interface EvaluatorActionProps {
+  value: unknown
+  path: JSONPath
+  readOnly: boolean
+  onSelect: OnJSONSelect
+}
+
+export const EvaluatorAction: Action<HTMLDivElement, Record<string, unknown>> = (
+  node,
+  initialProps
+) => {
+  let props = toEvaluatorProps(initialProps)
+
+  function updateResult() {
+    node.innerText = evaluate(String(props.value))
+  }
+
+  function handleValueDoubleClick(event: MouseEvent) {
+    if (!props.readOnly) {
+      event.preventDefault()
+      event.stopPropagation()
+
+      // open in edit mode
+      props.onSelect(createValueSelection(props.path, true))
+    }
+  }
+
+  node.addEventListener('dblclick', handleValueDoubleClick)
+  updateResult()
+
+  return {
+    update: (updatedProps) => {
+      props = toEvaluatorProps(updatedProps)
+      updateResult()
+    },
+    destroy: () => {
+      node.removeEventListener('dblclick', handleValueDoubleClick)
+    }
+  }
+}
+
+function evaluate(expr: string) {
+  const result = expr
+    .split('+')
+    .map((value) => parseFloat(value.trim()))
+    .reduce((a, b) => a + b)
+
+  return `The result of "${expr}" is "${result}" (double-click to edit)`
+}
+
+function toEvaluatorProps(props: Record<string, unknown>): EvaluatorActionProps {
+  // you can add validations and typeguards here if needed
+  return props as unknown as EvaluatorActionProps
+}

src/routes/examples/custom_value_renderer/+page.svelte

@@ -1,13 +1,21 @@
-<script>
-  import { EnumValue, JSONEditor, renderValue } from 'svelte-jsoneditor'
+<script lang="ts">
+  import {
+    EnumValue,
+    JSONEditor,
+    renderValue,
+    type RenderValueComponentDescription,
+    type RenderValueProps
+  } from 'svelte-jsoneditor'
   import ReadonlyPassword from '../../components/ReadonlyPassword.svelte'
+  import { EvaluatorAction } from '../../components/EvaluatorAction'
 
   let content = {
     text: undefined, // can be used to pass a stringified JSON document instead
     json: {
       username: 'John',
       password: 'secret...',
-      gender: 'male'
+      gender: 'male',
+      evaluate: '2 + 3'
     }
   }
 
@@ -18,7 +26,7 @@
     { value: 'other', text: 'Other' }
   ]
 
-  function onRenderValue(props) {
+  function onRenderValue(props: RenderValueProps): RenderValueComponentDescription[] {
     const { path, value, readOnly, parser, isEditing, selection, onSelect, onPatch } = props
 
     const key = props.path[props.path.length - 1]
@@ -53,24 +61,51 @@
       ]
     }
 
+    if (key === 'evaluate' && !isEditing) {
+      return [
+        {
+          action: EvaluatorAction,
+          props: {
+            value,
+            path,
+            readOnly,
+            onSelect
+          }
+        }
+      ]
+    }
+
     // fallback on the default render components
     return renderValue(props)
   }
 </script>
 
 <svelte:head>
-  <title>Custom value renderer (password, enum) | svelte-jsoneditor</title>
+  <title>Custom value renderer (password, enum, action) | svelte-jsoneditor</title>
 </svelte:head>
 
-<h1>Custom value renderer (password, enum)</h1>
+<h1>Custom value renderer (password, enum, action)</h1>
 
 <p>
-  Provide a custom <code>onRenderValue</code> method, which hides the value of all fields with the name
-  "password", and creates an enum for the fields with name "gender".
-</p>
-<p>
-  <i>EXPERIMENTAL! This API will most likely change in future versions.</i>
+  Provide a custom <code>onRenderValue</code> method, which demonstrates three things:
 </p>
+<ol>
+  <li>
+    It hides the value of all fields with the name "password" using a Svelte password component <code
+      >ReadonlyPassword</code
+    >
+  </li>
+  <li>
+    It creates an enum component for the fields with name "gender" using a Svelte component <code
+      >EnumValue</code
+    >.
+  </li>
+  <li>
+    The creates a custom component for the field named "evaluate" using a Svelte Action, which
+    evaluates the value as an expression containing an addition of two or more values. This solution
+    can be used when using svelte-jsoneditor in a Vanilla JS environment.
+  </li>
+</ol>
 
 <div class="editor">
   <JSONEditor bind:content {onRenderValue} />