@kognitivedev/json-editor 0.1.1

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+
+$ tsc

package/.turbo/turbo-test.log

@@ -0,0 +1,15 @@
+$ vitest run
+
+ RUN  v3.2.4 /Users/vserifsaglam/work/memory-experiment/packages/json-editor
+
+ ✓ src/__tests__/json-editor.test.tsx (6 tests) 3657ms
+   ✓ JsonEditor > renders a controlled JSON value and responds to external updates  695ms
+   ✓ JsonEditor > emits valid parse metadata for valid JSON edits  677ms
+   ✓ JsonEditor > emits invalid parse metadata for malformed JSON without crashing  798ms
+   ✓ JsonEditor > formats valid JSON and leaves invalid JSON untouched  1076ms
+
+ Test Files  1 passed (1)
+      Tests  6 passed (6)
+   Start at  12:40:03
+   Duration  6.28s (transform 183ms, setup 760ms, collect 665ms, tests 3.66s, environment 511ms, prepare 163ms)
+

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @kognitivedev/json-editor
+
+## 0.1.1
+
+### Patch Changes
+
+- release

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { JsonEditor, type JsonEditorProps, type JsonEditorChangeMeta, type JsonEditorToolbarAction, type JsonEditorToolbarActionContext, } from "./json-editor";

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonEditor = void 0;
+var json_editor_1 = require("./json-editor");
+Object.defineProperty(exports, "JsonEditor", { enumerable: true, get: function () { return json_editor_1.JsonEditor; } });

package/dist/json-editor.d.ts

@@ -0,0 +1,27 @@
+export type JsonEditorChangeMeta = {
+    isValidJson: boolean;
+    parsedValue?: unknown;
+    errorMessage?: string;
+};
+export type JsonEditorToolbarActionContext = {
+    value: string;
+    meta: JsonEditorChangeMeta;
+    replaceValue: (nextValue: string) => void;
+};
+export type JsonEditorToolbarAction = {
+    id: string;
+    label: string;
+    onAction: (context: JsonEditorToolbarActionContext) => void;
+    disabled?: boolean | ((context: JsonEditorToolbarActionContext) => boolean);
+    title?: string;
+};
+export type JsonEditorProps = {
+    value: string;
+    onChange?: (nextValue: string, meta: JsonEditorChangeMeta) => void;
+    readOnly?: boolean;
+    minHeight?: number;
+    placeholder?: string;
+    className?: string;
+    toolbarActions?: JsonEditorToolbarAction[];
+};
+export declare function JsonEditor({ value, onChange, readOnly, minHeight, placeholder, className, toolbarActions, }: JsonEditorProps): import("react/jsx-runtime").JSX.Element;

package/dist/json-editor.js

@@ -0,0 +1,217 @@
+"use strict";
+"use client";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonEditor = JsonEditor;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const state_1 = require("@codemirror/state");
+const language_1 = require("@codemirror/language");
+const lang_json_1 = require("@codemirror/lang-json");
+const view_1 = require("@codemirror/view");
+const commands_1 = require("@codemirror/commands");
+const codemirror_1 = require("codemirror");
+const react_1 = require("react");
+function cn(...values) {
+    return values.filter(Boolean).join(" ");
+}
+function parseJsonText(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return {
+            isValidJson: false,
+            errorMessage: "Enter a JSON object or array.",
+        };
+    }
+    try {
+        return {
+            isValidJson: true,
+            parsedValue: JSON.parse(value),
+        };
+    }
+    catch (error) {
+        return {
+            isValidJson: false,
+            errorMessage: error instanceof Error ? error.message : "Invalid JSON.",
+        };
+    }
+}
+function clampSelection(state, nextLength) {
+    return state_1.EditorSelection.create(state.selection.ranges.map((range) => {
+        const anchor = Math.min(range.anchor, nextLength);
+        const head = Math.min(range.head, nextLength);
+        return state_1.EditorSelection.range(anchor, head);
+    }), state.selection.mainIndex);
+}
+const editorTheme = view_1.EditorView.theme({
+    "&": {
+        backgroundColor: "transparent",
+        color: "inherit",
+        height: "100%",
+        fontFamily: "var(--font-geist-mono, var(--font-space-mono, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, monospace))",
+        fontSize: "12px",
+        lineHeight: "1.6",
+    },
+    ".cm-scroller": {
+        minHeight: "var(--json-editor-min-height, 240px)",
+        overflow: "auto",
+    },
+    ".cm-content": {
+        minHeight: "var(--json-editor-min-height, 240px)",
+        padding: "12px 0",
+        caretColor: "currentColor",
+    },
+    ".cm-line": {
+        padding: "0 12px",
+    },
+    ".cm-gutters": {
+        border: "none",
+        backgroundColor: "transparent",
+        color: "rgb(113 113 122)",
+    },
+    ".cm-activeLineGutter": {
+        backgroundColor: "transparent",
+    },
+    ".cm-activeLine": {
+        backgroundColor: "rgba(148, 163, 184, 0.08)",
+    },
+    ".cm-matchingBracket": {
+        backgroundColor: "rgba(59, 130, 246, 0.18)",
+        outline: "1px solid rgba(59, 130, 246, 0.35)",
+    },
+    ".cm-cursor, .cm-dropCursor": {
+        borderLeftColor: "currentColor",
+    },
+    ".cm-selectionBackground, ::selection": {
+        backgroundColor: "rgba(59, 130, 246, 0.28)",
+    },
+    ".cm-focused": {
+        outline: "none",
+    },
+    ".cm-placeholder": {
+        color: "rgb(113 113 122)",
+        fontStyle: "italic",
+    },
+});
+function JsonEditor({ value, onChange, readOnly = false, minHeight = 240, placeholder, className, toolbarActions = [], }) {
+    const containerRef = (0, react_1.useRef)(null);
+    const viewRef = (0, react_1.useRef)(null);
+    const onChangeRef = (0, react_1.useRef)(onChange);
+    const editableCompartmentRef = (0, react_1.useRef)(new state_1.Compartment());
+    const readOnlyCompartmentRef = (0, react_1.useRef)(new state_1.Compartment());
+    const placeholderCompartmentRef = (0, react_1.useRef)(new state_1.Compartment());
+    const [meta, setMeta] = (0, react_1.useState)(() => parseJsonText(value));
+    (0, react_1.useEffect)(() => {
+        onChangeRef.current = onChange;
+    }, [onChange]);
+    (0, react_1.useEffect)(() => {
+        if (!containerRef.current || viewRef.current)
+            return;
+        const state = state_1.EditorState.create({
+            doc: value,
+            extensions: [
+                codemirror_1.basicSetup,
+                (0, lang_json_1.json)(),
+                (0, language_1.bracketMatching)(),
+                (0, language_1.syntaxHighlighting)(language_1.defaultHighlightStyle, { fallback: true }),
+                view_1.keymap.of([commands_1.indentWithTab]),
+                view_1.EditorView.lineWrapping,
+                editorTheme,
+                editableCompartmentRef.current.of(view_1.EditorView.editable.of(!readOnly)),
+                readOnlyCompartmentRef.current.of(state_1.EditorState.readOnly.of(readOnly)),
+                placeholderCompartmentRef.current.of(placeholder ? (0, view_1.placeholder)(placeholder) : []),
+                view_1.EditorView.updateListener.of((update) => {
+                    var _a;
+                    if (!update.docChanged)
+                        return;
+                    const nextValue = update.state.doc.toString();
+                    const nextMeta = parseJsonText(nextValue);
+                    setMeta(nextMeta);
+                    (_a = onChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onChangeRef, nextValue, nextMeta);
+                }),
+            ],
+        });
+        viewRef.current = new view_1.EditorView({
+            state,
+            parent: containerRef.current,
+        });
+        return () => {
+            var _a;
+            (_a = viewRef.current) === null || _a === void 0 ? void 0 : _a.destroy();
+            viewRef.current = null;
+        };
+    }, [placeholder, readOnly, value]);
+    (0, react_1.useEffect)(() => {
+        const view = viewRef.current;
+        if (!view)
+            return;
+        const nextEditable = view_1.EditorView.editable.of(!readOnly);
+        const nextReadOnly = state_1.EditorState.readOnly.of(readOnly);
+        view.dispatch({
+            effects: [
+                editableCompartmentRef.current.reconfigure(nextEditable),
+                readOnlyCompartmentRef.current.reconfigure(nextReadOnly),
+            ],
+        });
+    }, [readOnly]);
+    (0, react_1.useEffect)(() => {
+        const view = viewRef.current;
+        if (!view)
+            return;
+        view.dispatch({
+            effects: placeholderCompartmentRef.current.reconfigure(placeholder ? (0, view_1.placeholder)(placeholder) : []),
+        });
+    }, [placeholder]);
+    (0, react_1.useEffect)(() => {
+        const nextMeta = parseJsonText(value);
+        setMeta(nextMeta);
+        const view = viewRef.current;
+        if (!view)
+            return;
+        if (view.state.doc.toString() === value)
+            return;
+        view.dispatch({
+            changes: {
+                from: 0,
+                to: view.state.doc.length,
+                insert: value,
+            },
+            selection: clampSelection(view.state, value.length),
+        });
+    }, [value]);
+    function replaceValue(nextValue) {
+        var _a;
+        const view = viewRef.current;
+        if (!view) {
+            const nextMeta = parseJsonText(nextValue);
+            setMeta(nextMeta);
+            (_a = onChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onChangeRef, nextValue, nextMeta);
+            return;
+        }
+        view.dispatch({
+            changes: {
+                from: 0,
+                to: view.state.doc.length,
+                insert: nextValue,
+            },
+            selection: clampSelection(view.state, nextValue.length),
+            scrollIntoView: true,
+        });
+    }
+    function handleFormatJson() {
+        if (readOnly || !meta.isValidJson)
+            return;
+        replaceValue(JSON.stringify(meta.parsedValue, null, 2));
+    }
+    const actionContext = (0, react_1.useMemo)(() => ({
+        value,
+        meta,
+        replaceValue,
+    }), [meta, value]);
+    return ((0, jsx_runtime_1.jsxs)("div", { className: cn("overflow-hidden rounded-[1rem] border border-zinc-200 bg-white text-zinc-950 shadow-sm dark:border-zinc-800 dark:bg-zinc-950 dark:text-zinc-100", className), children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex flex-wrap items-center justify-between gap-3 border-b border-zinc-200/80 px-3 py-2 dark:border-zinc-800/90", children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex min-w-0 items-center gap-2 text-[11px]", children: [(0, jsx_runtime_1.jsx)("span", { className: cn("rounded-full px-2 py-1 font-medium uppercase tracking-[0.14em]", meta.isValidJson
+                                    ? "bg-emerald-500/12 text-emerald-600 dark:bg-emerald-500/18 dark:text-emerald-300"
+                                    : "bg-amber-500/12 text-amber-700 dark:bg-amber-500/18 dark:text-amber-300"), children: meta.isValidJson ? "Valid JSON" : "Template / Invalid JSON" }), !meta.isValidJson && meta.errorMessage ? ((0, jsx_runtime_1.jsx)("span", { className: "truncate text-zinc-500 dark:text-zinc-400", children: meta.errorMessage })) : null] }), (0, jsx_runtime_1.jsxs)("div", { className: "flex flex-wrap items-center justify-end gap-2", children: [(0, jsx_runtime_1.jsx)("button", { type: "button", onClick: handleFormatJson, disabled: readOnly || !meta.isValidJson, className: "inline-flex items-center rounded-full border border-zinc-300 px-3 py-1.5 text-[11px] font-medium uppercase tracking-[0.14em] text-zinc-700 transition hover:border-zinc-400 hover:bg-zinc-100 disabled:cursor-not-allowed disabled:opacity-50 dark:border-zinc-700 dark:text-zinc-200 dark:hover:border-zinc-600 dark:hover:bg-zinc-900", children: "Format JSON" }), toolbarActions.map((action) => {
+                                const disabled = readOnly || (typeof action.disabled === "function"
+                                    ? action.disabled(actionContext)
+                                    : Boolean(action.disabled));
+                                return ((0, jsx_runtime_1.jsx)("button", { type: "button", title: action.title, onClick: () => action.onAction(actionContext), disabled: disabled, className: "inline-flex items-center rounded-full border border-zinc-300 px-3 py-1.5 text-[11px] font-medium uppercase tracking-[0.14em] text-zinc-700 transition hover:border-zinc-400 hover:bg-zinc-100 disabled:cursor-not-allowed disabled:opacity-50 dark:border-zinc-700 dark:text-zinc-200 dark:hover:border-zinc-600 dark:hover:bg-zinc-900", children: action.label }, action.id));
+                            })] })] }), (0, jsx_runtime_1.jsx)("div", { ref: containerRef, style: { "--json-editor-min-height": `${minHeight}px` } })] }));
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@kognitivedev/json-editor",
+  "version": "0.1.1",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w --noCheck",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@codemirror/lang-json": "^6.0.1",
+    "@codemirror/language": "^6.10.0",
+    "@codemirror/commands": "^6.8.1",
+    "@codemirror/state": "^6.5.2",
+    "@codemirror/view": "^6.38.6",
+    "codemirror": "^6.0.2"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^20.0.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "jsdom": "^26.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "description": "Reusable JSON editing surface for Kognitive apps",
+  "keywords": [
+    "json",
+    "editor",
+    "codemirror",
+    "react",
+    "kognitive"
+  ],
+  "license": "MIT"
+}

package/src/__tests__/json-editor.test.tsx

@@ -0,0 +1,166 @@
+import { useState } from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import {
+    JsonEditor,
+    type JsonEditorChangeMeta,
+    type JsonEditorToolbarAction,
+} from "../index";
+
+function getEditable(container: HTMLElement) {
+    const editable = container.querySelector(".cm-content");
+    if (!(editable instanceof HTMLElement)) {
+        throw new Error("Unable to find CodeMirror editable content.");
+    }
+    return editable;
+}
+
+function Harness({
+    initialValue,
+    readOnly = false,
+    toolbarActions,
+    placeholder,
+}: {
+    initialValue: string;
+    readOnly?: boolean;
+    toolbarActions?: JsonEditorToolbarAction[];
+    placeholder?: string;
+}) {
+    const [value, setValue] = useState(initialValue);
+    const [meta, setMeta] = useState<JsonEditorChangeMeta | null>(null);
+
+    return (
+        <div>
+            <JsonEditor
+                value={value}
+                readOnly={readOnly}
+                placeholder={placeholder}
+                toolbarActions={toolbarActions}
+                onChange={(nextValue, nextMeta) => {
+                    setValue(nextValue);
+                    setMeta(nextMeta);
+                }}
+            />
+            <button type="button" onClick={() => setValue('{"external":true}')}>
+                Replace Externally
+            </button>
+            <pre data-testid="value">{value}</pre>
+            <pre data-testid="meta">{meta ? JSON.stringify(meta) : ""}</pre>
+        </div>
+    );
+}
+
+describe("JsonEditor", () => {
+    it("renders a controlled JSON value and responds to external updates", async () => {
+        const user = userEvent.setup();
+        const { container } = render(<Harness initialValue='{"count":1}' />);
+
+        expect(getEditable(container).textContent).toContain('{"count":1}');
+
+        await user.click(screen.getByRole("button", { name: "Replace Externally" }));
+
+        await waitFor(() => {
+            expect(getEditable(container).textContent).toContain('{"external":true}');
+        });
+    });
+
+    it("emits valid parse metadata for valid JSON edits", async () => {
+        const user = userEvent.setup();
+        render(
+            <Harness
+                initialValue=""
+                placeholder="{}"
+                toolbarActions={[{
+                    id: "inject-valid",
+                    label: "Inject Valid",
+                    onAction: ({ replaceValue }) => replaceValue('{"name":"Ada"}'),
+                }]}
+            />,
+        );
+
+        await user.click(screen.getByRole("button", { name: "Inject Valid" }));
+
+        await waitFor(() => {
+            expect(screen.getByTestId("meta")).toHaveTextContent('"isValidJson":true');
+            expect(screen.getByTestId("meta")).toHaveTextContent('"name":"Ada"');
+        });
+    });
+
+    it("emits invalid parse metadata for malformed JSON without crashing", async () => {
+        const user = userEvent.setup();
+        render(
+            <Harness
+                initialValue=""
+                toolbarActions={[{
+                    id: "inject-invalid",
+                    label: "Inject Invalid",
+                    onAction: ({ replaceValue }) => replaceValue("{"),
+                }]}
+            />,
+        );
+
+        await user.click(screen.getByRole("button", { name: "Inject Invalid" }));
+
+        await waitFor(() => {
+            expect(screen.getByTestId("meta")).toHaveTextContent('"isValidJson":false');
+            expect(screen.getByText("Template / Invalid JSON")).toBeInTheDocument();
+        });
+    });
+
+    it("formats valid JSON and leaves invalid JSON untouched", async () => {
+        const user = userEvent.setup();
+        render(<Harness initialValue='{"count":1,"items":[1,2]}' />);
+
+        await user.click(screen.getByRole("button", { name: "Format JSON" }));
+
+        await waitFor(() => {
+            expect(screen.getByTestId("value").textContent).toBe('{\n  "count": 1,\n  "items": [\n    1,\n    2\n  ]\n}');
+        });
+
+        render(<Harness initialValue="{" />);
+        await user.click(screen.getAllByRole("button", { name: "Format JSON" })[1]);
+
+        await waitFor(() => {
+            expect(screen.getAllByTestId("value")[1].textContent).toBe("{");
+        });
+    });
+
+    it("blocks edits in read-only mode", async () => {
+        const user = userEvent.setup();
+        const { container } = render(<Harness initialValue='{"count":1}' readOnly />);
+
+        const editable = getEditable(container);
+        expect(editable.getAttribute("contenteditable")).toBe("false");
+
+        await user.click(editable);
+        await user.keyboard("2");
+
+        expect(screen.getByTestId("value").textContent).toBe('{"count":1}');
+    });
+
+    it("supports custom toolbar actions without teaching the editor about schemas", async () => {
+        const user = userEvent.setup();
+        const actionSpy = vi.fn((context: { replaceValue: (nextValue: string) => void }) => {
+            context.replaceValue('{"reset":true}');
+        });
+
+        render(
+            <Harness
+                initialValue='{"count":1}'
+                toolbarActions={[{
+                    id: "reset",
+                    label: "Reset",
+                    onAction: actionSpy,
+                }]}
+            />,
+        );
+
+        await user.click(screen.getByRole("button", { name: "Reset" }));
+
+        expect(actionSpy).toHaveBeenCalledTimes(1);
+        await waitFor(() => {
+            expect(screen.getByTestId("value").textContent).toBe('{"reset":true}');
+        });
+    });
+});

package/src/index.ts

@@ -0,0 +1,7 @@
+export {
+    JsonEditor,
+    type JsonEditorProps,
+    type JsonEditorChangeMeta,
+    type JsonEditorToolbarAction,
+    type JsonEditorToolbarActionContext,
+} from "./json-editor";

package/src/json-editor.tsx

@@ -0,0 +1,344 @@
+"use client";
+
+import {
+    Compartment,
+    EditorSelection,
+    EditorState,
+    type Extension,
+} from "@codemirror/state";
+import {
+    bracketMatching,
+    defaultHighlightStyle,
+    syntaxHighlighting,
+} from "@codemirror/language";
+import { json } from "@codemirror/lang-json";
+import {
+    EditorView,
+    keymap,
+    placeholder as placeholderExtension,
+} from "@codemirror/view";
+import { indentWithTab } from "@codemirror/commands";
+import { basicSetup } from "codemirror";
+import {
+    useEffect,
+    useMemo,
+    useRef,
+    useState,
+    type CSSProperties,
+} from "react";
+
+export type JsonEditorChangeMeta = {
+    isValidJson: boolean;
+    parsedValue?: unknown;
+    errorMessage?: string;
+};
+
+export type JsonEditorToolbarActionContext = {
+    value: string;
+    meta: JsonEditorChangeMeta;
+    replaceValue: (nextValue: string) => void;
+};
+
+export type JsonEditorToolbarAction = {
+    id: string;
+    label: string;
+    onAction: (context: JsonEditorToolbarActionContext) => void;
+    disabled?: boolean | ((context: JsonEditorToolbarActionContext) => boolean);
+    title?: string;
+};
+
+export type JsonEditorProps = {
+    value: string;
+    onChange?: (nextValue: string, meta: JsonEditorChangeMeta) => void;
+    readOnly?: boolean;
+    minHeight?: number;
+    placeholder?: string;
+    className?: string;
+    toolbarActions?: JsonEditorToolbarAction[];
+};
+
+function cn(...values: Array<string | undefined | false | null>) {
+    return values.filter(Boolean).join(" ");
+}
+
+function parseJsonText(value: string): JsonEditorChangeMeta {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return {
+            isValidJson: false,
+            errorMessage: "Enter a JSON object or array.",
+        };
+    }
+
+    try {
+        return {
+            isValidJson: true,
+            parsedValue: JSON.parse(value),
+        };
+    } catch (error) {
+        return {
+            isValidJson: false,
+            errorMessage: error instanceof Error ? error.message : "Invalid JSON.",
+        };
+    }
+}
+
+function clampSelection(state: EditorState, nextLength: number) {
+    return EditorSelection.create(
+        state.selection.ranges.map((range) => {
+            const anchor = Math.min(range.anchor, nextLength);
+            const head = Math.min(range.head, nextLength);
+            return EditorSelection.range(anchor, head);
+        }),
+        state.selection.mainIndex,
+    );
+}
+
+const editorTheme = EditorView.theme({
+    "&": {
+        backgroundColor: "transparent",
+        color: "inherit",
+        height: "100%",
+        fontFamily: "var(--font-geist-mono, var(--font-space-mono, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, monospace))",
+        fontSize: "12px",
+        lineHeight: "1.6",
+    },
+    ".cm-scroller": {
+        minHeight: "var(--json-editor-min-height, 240px)",
+        overflow: "auto",
+    },
+    ".cm-content": {
+        minHeight: "var(--json-editor-min-height, 240px)",
+        padding: "12px 0",
+        caretColor: "currentColor",
+    },
+    ".cm-line": {
+        padding: "0 12px",
+    },
+    ".cm-gutters": {
+        border: "none",
+        backgroundColor: "transparent",
+        color: "rgb(113 113 122)",
+    },
+    ".cm-activeLineGutter": {
+        backgroundColor: "transparent",
+    },
+    ".cm-activeLine": {
+        backgroundColor: "rgba(148, 163, 184, 0.08)",
+    },
+    ".cm-matchingBracket": {
+        backgroundColor: "rgba(59, 130, 246, 0.18)",
+        outline: "1px solid rgba(59, 130, 246, 0.35)",
+    },
+    ".cm-cursor, .cm-dropCursor": {
+        borderLeftColor: "currentColor",
+    },
+    ".cm-selectionBackground, ::selection": {
+        backgroundColor: "rgba(59, 130, 246, 0.28)",
+    },
+    ".cm-focused": {
+        outline: "none",
+    },
+    ".cm-placeholder": {
+        color: "rgb(113 113 122)",
+        fontStyle: "italic",
+    },
+});
+
+export function JsonEditor({
+    value,
+    onChange,
+    readOnly = false,
+    minHeight = 240,
+    placeholder,
+    className,
+    toolbarActions = [],
+}: JsonEditorProps) {
+    const containerRef = useRef<HTMLDivElement | null>(null);
+    const viewRef = useRef<EditorView | null>(null);
+    const onChangeRef = useRef(onChange);
+    const editableCompartmentRef = useRef(new Compartment());
+    const readOnlyCompartmentRef = useRef(new Compartment());
+    const placeholderCompartmentRef = useRef(new Compartment());
+    const [meta, setMeta] = useState<JsonEditorChangeMeta>(() => parseJsonText(value));
+
+    useEffect(() => {
+        onChangeRef.current = onChange;
+    }, [onChange]);
+
+    useEffect(() => {
+        if (!containerRef.current || viewRef.current) return;
+
+        const state = EditorState.create({
+            doc: value,
+            extensions: [
+                basicSetup,
+                json(),
+                bracketMatching(),
+                syntaxHighlighting(defaultHighlightStyle, { fallback: true }),
+                keymap.of([indentWithTab]),
+                EditorView.lineWrapping,
+                editorTheme,
+                editableCompartmentRef.current.of(EditorView.editable.of(!readOnly)),
+                readOnlyCompartmentRef.current.of(EditorState.readOnly.of(readOnly)),
+                placeholderCompartmentRef.current.of(
+                    placeholder ? placeholderExtension(placeholder) : [],
+                ),
+                EditorView.updateListener.of((update) => {
+                    if (!update.docChanged) return;
+                    const nextValue = update.state.doc.toString();
+                    const nextMeta = parseJsonText(nextValue);
+                    setMeta(nextMeta);
+                    onChangeRef.current?.(nextValue, nextMeta);
+                }),
+            ] satisfies Extension[],
+        });
+
+        viewRef.current = new EditorView({
+            state,
+            parent: containerRef.current,
+        });
+
+        return () => {
+            viewRef.current?.destroy();
+            viewRef.current = null;
+        };
+    }, [placeholder, readOnly, value]);
+
+    useEffect(() => {
+        const view = viewRef.current;
+        if (!view) return;
+
+        const nextEditable = EditorView.editable.of(!readOnly);
+        const nextReadOnly = EditorState.readOnly.of(readOnly);
+
+        view.dispatch({
+            effects: [
+                editableCompartmentRef.current.reconfigure(nextEditable),
+                readOnlyCompartmentRef.current.reconfigure(nextReadOnly),
+            ],
+        });
+    }, [readOnly]);
+
+    useEffect(() => {
+        const view = viewRef.current;
+        if (!view) return;
+
+        view.dispatch({
+            effects: placeholderCompartmentRef.current.reconfigure(
+                placeholder ? placeholderExtension(placeholder) : [],
+            ),
+        });
+    }, [placeholder]);
+
+    useEffect(() => {
+        const nextMeta = parseJsonText(value);
+        setMeta(nextMeta);
+
+        const view = viewRef.current;
+        if (!view) return;
+        if (view.state.doc.toString() === value) return;
+
+        view.dispatch({
+            changes: {
+                from: 0,
+                to: view.state.doc.length,
+                insert: value,
+            },
+            selection: clampSelection(view.state, value.length),
+        });
+    }, [value]);
+
+    function replaceValue(nextValue: string) {
+        const view = viewRef.current;
+        if (!view) {
+            const nextMeta = parseJsonText(nextValue);
+            setMeta(nextMeta);
+            onChangeRef.current?.(nextValue, nextMeta);
+            return;
+        }
+
+        view.dispatch({
+            changes: {
+                from: 0,
+                to: view.state.doc.length,
+                insert: nextValue,
+            },
+            selection: clampSelection(view.state, nextValue.length),
+            scrollIntoView: true,
+        });
+    }
+
+    function handleFormatJson() {
+        if (readOnly || !meta.isValidJson) return;
+        replaceValue(JSON.stringify(meta.parsedValue, null, 2));
+    }
+
+    const actionContext = useMemo<JsonEditorToolbarActionContext>(() => ({
+        value,
+        meta,
+        replaceValue,
+    }), [meta, value]);
+
+    return (
+        <div
+            className={cn(
+                "overflow-hidden rounded-[1rem] border border-zinc-200 bg-white text-zinc-950 shadow-sm dark:border-zinc-800 dark:bg-zinc-950 dark:text-zinc-100",
+                className,
+            )}
+        >
+            <div className="flex flex-wrap items-center justify-between gap-3 border-b border-zinc-200/80 px-3 py-2 dark:border-zinc-800/90">
+                <div className="flex min-w-0 items-center gap-2 text-[11px]">
+                    <span
+                        className={cn(
+                            "rounded-full px-2 py-1 font-medium uppercase tracking-[0.14em]",
+                            meta.isValidJson
+                                ? "bg-emerald-500/12 text-emerald-600 dark:bg-emerald-500/18 dark:text-emerald-300"
+                                : "bg-amber-500/12 text-amber-700 dark:bg-amber-500/18 dark:text-amber-300",
+                        )}
+                    >
+                        {meta.isValidJson ? "Valid JSON" : "Template / Invalid JSON"}
+                    </span>
+                    {!meta.isValidJson && meta.errorMessage ? (
+                        <span className="truncate text-zinc-500 dark:text-zinc-400">{meta.errorMessage}</span>
+                    ) : null}
+                </div>
+
+                <div className="flex flex-wrap items-center justify-end gap-2">
+                    <button
+                        type="button"
+                        onClick={handleFormatJson}
+                        disabled={readOnly || !meta.isValidJson}
+                        className="inline-flex items-center rounded-full border border-zinc-300 px-3 py-1.5 text-[11px] font-medium uppercase tracking-[0.14em] text-zinc-700 transition hover:border-zinc-400 hover:bg-zinc-100 disabled:cursor-not-allowed disabled:opacity-50 dark:border-zinc-700 dark:text-zinc-200 dark:hover:border-zinc-600 dark:hover:bg-zinc-900"
+                    >
+                        Format JSON
+                    </button>
+
+                    {toolbarActions.map((action) => {
+                        const disabled = readOnly || (typeof action.disabled === "function"
+                            ? action.disabled(actionContext)
+                            : Boolean(action.disabled));
+
+                        return (
+                            <button
+                                key={action.id}
+                                type="button"
+                                title={action.title}
+                                onClick={() => action.onAction(actionContext)}
+                                disabled={disabled}
+                                className="inline-flex items-center rounded-full border border-zinc-300 px-3 py-1.5 text-[11px] font-medium uppercase tracking-[0.14em] text-zinc-700 transition hover:border-zinc-400 hover:bg-zinc-100 disabled:cursor-not-allowed disabled:opacity-50 dark:border-zinc-700 dark:text-zinc-200 dark:hover:border-zinc-600 dark:hover:bg-zinc-900"
+                            >
+                                {action.label}
+                            </button>
+                        );
+                    })}
+                </div>
+            </div>
+
+            <div
+                ref={containerRef}
+                style={{ "--json-editor-min-height": `${minHeight}px` } as CSSProperties}
+            />
+        </div>
+    );
+}

package/src/test/setup.ts

@@ -0,0 +1,44 @@
+import "@testing-library/jest-dom/vitest";
+import { cleanup } from "@testing-library/react";
+import { afterEach, vi } from "vitest";
+
+afterEach(() => {
+    cleanup();
+});
+
+class ResizeObserverMock {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+}
+
+const emptyDomRect = {
+    x: 0,
+    y: 0,
+    width: 0,
+    height: 0,
+    top: 0,
+    right: 0,
+    bottom: 0,
+    left: 0,
+    toJSON() {
+        return this;
+    },
+};
+
+if (!globalThis.ResizeObserver) {
+    vi.stubGlobal("ResizeObserver", ResizeObserverMock);
+}
+
+if (typeof Range !== "undefined") {
+    if (!Range.prototype.getBoundingClientRect) {
+        Range.prototype.getBoundingClientRect = () => emptyDomRect as DOMRect;
+    }
+    if (!Range.prototype.getClientRects) {
+        Range.prototype.getClientRects = () => ({
+            item: () => null,
+            length: 0,
+            [Symbol.iterator]: function* iterator() {},
+        }) as DOMRectList;
+    }
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "noEmit": false,
+    "incremental": false,
+    "jsx": "react-jsx"
+  },
+  "include": [
+    "src"
+  ],
+  "exclude": [
+    "src/__tests__",
+    "src/test"
+  ]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: "jsdom",
+        setupFiles: ["./src/test/setup.ts"],
+    },
+});