modern-json-react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dileep Pandey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# modern-json-react
+
+A production-grade, fully-featured JSON editor React component. Combines code editing, tree view navigation, JSON Schema validation, and accessibility-first design in a single, zero-config package.
+
+## Screenshots
+
+### Code Mode (Light)
+
+Syntax-highlighted editor with line numbers, bracket matching, and real-time validation:
+
+![Code Mode - Light Theme](docs/screenshots/code-mode-light.svg)
+
+### Tree Mode (Light)
+
+Collapsible tree view with inline editing, type badges, and hover actions:
+
+![Tree Mode - Light Theme](docs/screenshots/tree-mode-light.svg)
+
+### Code Mode (Dark)
+
+Full dark theme support with VS Code-inspired color palette:
+
+![Code Mode - Dark Theme](docs/screenshots/code-mode-dark.svg)
+
+## Features
+
+- **Dual editing modes** — Syntax-highlighted code editor, collapsible tree view, or side-by-side split mode
+- **JSON Schema validation** — Built-in Draft-07 support with real-time error markers and human-readable messages
+- **Tree view editing** — Inline value editing, type changing, key renaming, drag-drop reordering, and node deletion
+- **Undo / Redo** — Full history stack with time-based action grouping and keyboard shortcuts
+- **Search** — Full-text search across keys and values with regex support and match highlighting
+- **Theming** — Light and dark presets with 22 CSS custom properties for full customization
+- **Formatting** — Pretty-print, minify, sort keys (ascending, descending, or custom comparator)
+- **Accessibility** — WCAG 2.1 AA compliant with full keyboard navigation, ARIA roles, and screen reader announcements
+- **TypeScript** — Complete type definitions with JSDoc comments
+- **Zero peer dependencies** — Only requires React 18+
+
+## Installation
+
+```bash
+npm install modern-json-react
+```
+
+## Quick Start
+
+```tsx
+import { JsonEditor } from 'modern-json-react';
+
+function App() {
+  const [data, setData] = useState({ name: "John", age: 30 });
+
+  return (
+    <JsonEditor
+      value={data}
+      onChange={(value) => setData(value)}
+      height={500}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `unknown` | — | JSON value (object, array, string, etc.) or raw JSON string |
+| `onChange` | `(value, rawText) => void` | — | Called when the JSON value changes |
+| `mode` | `'code' \| 'tree' \| 'split'` | `'code'` | Active editing mode |
+| `onModeChange` | `(mode) => void` | — | Called when the user switches modes |
+| `schema` | `JSONSchema` | — | JSON Schema for validation (Draft-07, 2019-09, 2020-12) |
+| `validators` | `CustomValidator[]` | — | Custom validation functions |
+| `validationMode` | `'onChange' \| 'onBlur' \| 'onSubmit' \| 'manual'` | `'onChange'` | When to trigger validation |
+| `onValidate` | `(errors) => void` | — | Called when validation completes |
+| `theme` | `'light' \| 'dark' \| 'auto' \| ThemeConfig` | `'light'` | Theme preset or custom config |
+| `height` | `string \| number` | `400` | Editor height (CSS value or pixels) |
+| `readOnly` | `boolean` | `false` | Disable editing |
+| `searchable` | `boolean` | `true` | Show search bar |
+| `sortable` | `boolean` | `true` | Enable key sorting |
+| `indentation` | `2 \| 4 \| 'tab'` | `2` | Indentation style |
+| `lineNumbers` | `boolean` | `true` | Show line numbers in code mode |
+| `className` | `string` | — | Additional CSS class |
+
+## Schema Validation
+
+Pass a JSON Schema to get real-time validation with inline error markers:
+
+```tsx
+const schema = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', minLength: 1 },
+    age: { type: 'number', minimum: 0 },
+    email: { type: 'string', format: 'email' },
+  },
+  required: ['name', 'email'],
+};
+
+<JsonEditor
+  value={data}
+  onChange={setData}
+  schema={schema}
+  onValidate={(errors) => console.log(errors)}
+/>
+```
+
+## Custom Validators
+
+Add your own validation rules alongside schema validation:
+
+```tsx
+const noEmptyArrays = (value, path) => {
+  if (Array.isArray(value) && value.length === 0) {
+    return [{ message: 'Array must not be empty', path, severity: 'warning' }];
+  }
+  return [];
+};
+
+<JsonEditor value={data} validators={[noEmptyArrays]} />
+```
+
+## Theming
+
+Use a preset or provide a full custom theme:
+
+```tsx
+// Preset
+<JsonEditor theme="dark" />
+
+// Auto (follows OS preference)
+<JsonEditor theme="auto" />
+
+// Custom theme
+<JsonEditor theme={{
+  name: 'ocean',
+  bg: '#0d1b2a',
+  fg: '#e0e1dd',
+  border: '#1b263b',
+  keyColor: '#48cae4',
+  stringColor: '#90e0ef',
+  numberColor: '#ade8f4',
+  // ... see ThemeConfig for all 22 properties
+}} />
+```
+
+Override individual tokens with CSS custom properties:
+
+```css
+.my-editor {
+  --mjr-bg: #fafafa;
+  --mjr-key: #d63384;
+  --mjr-string: #198754;
+}
+```
+
+## Exported Utilities
+
+The package also exports core utilities for advanced use cases:
+
+```tsx
+import {
+  // Parsing
+  parseJson, stringifyJson, isValidJson,
+
+  // Validation
+  validateSchema, runCustomValidators,
+
+  // Formatting
+  formatJson, minifyJson, sortJsonKeys, computeStats,
+
+  // Path operations (immutable)
+  getByPath, setByPath, deleteByPath, parsePath,
+
+  // Hooks (for building custom editors)
+  useJsonParser, useUndoRedo, useSearch,
+
+  // Themes
+  lightTheme, darkTheme,
+} from 'modern-json-react';
+```
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl/Cmd + Z` | Undo |
+| `Ctrl/Cmd + Shift + Z` | Redo |
+| `Ctrl/Cmd + F` | Open search |
+| `Escape` | Close search |
+| `Tab` | Indent (code mode) |
+| `Enter` | Edit selected node (tree mode) |
+| `Delete` | Delete selected node (tree mode) |
+| Arrow keys | Navigate tree nodes |
+
+## Browser Support
+
+Chrome/Edge 90+, Firefox 90+, Safari 15+. Requires React 18 or later.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Type checking
+npm run typecheck
+
+# Build for production
+npm run build
+
+# Open interactive demo
+open demo/index.html
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts                 # Public API exports
+├── JsonEditor.tsx           # Root component
+├── components/
+│   ├── CodeEditor/          # Syntax-highlighted text editor
+│   ├── TreeEditor/          # Collapsible tree with inline editing
+│   ├── Toolbar/             # Mode switcher, search, actions
+│   └── StatusBar/           # Validation status, cursor position, stats
+├── hooks/
+│   ├── useJsonParser.ts     # Parse + validate
+│   ├── useUndoRedo.ts       # History management
+│   └── useSearch.ts         # Search state + matching
+├── core/
+│   ├── parser.ts            # JSON parsing with error locations
+│   ├── validator.ts         # JSON Schema validation engine
+│   ├── formatter.ts         # Format, minify, sort, stats
+│   └── path.ts              # JSONPath get/set/delete (immutable)
+├── themes/                  # Light + dark presets
+└── types/                   # TypeScript interfaces
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,440 @@
+import React$1 from 'react';
+
+/** Severity level for validation messages */
+type ValidationSeverity = 'error' | 'warning' | 'info';
+/** A validation error/warning with location and context */
+interface ValidationError {
+    /** Human-readable error message */
+    message: string;
+    /** JSONPath to the offending value (e.g., "$.address.zip") */
+    path: string;
+    /** Severity level */
+    severity: ValidationSeverity;
+    /** Line number in the raw text (1-based, if available) */
+    line?: number;
+    /** Column number in the raw text (1-based, if available) */
+    column?: number;
+    /** The JSON Schema keyword that failed (e.g., "minimum", "required") */
+    schemaKeyword?: string;
+    /** The schema rule that was violated */
+    schemaRule?: unknown;
+    /** The actual value that failed validation */
+    actualValue?: unknown;
+}
+/** JSON Schema type — kept intentionally loose for broad draft support */
+type JSONSchema = Record<string, unknown> & {
+    type?: string | string[];
+    properties?: Record<string, JSONSchema>;
+    items?: JSONSchema | JSONSchema[];
+    required?: string[];
+    $ref?: string;
+    $schema?: string;
+};
+/** Custom validator function — returns an array of errors (empty = valid) */
+type CustomValidator = (value: unknown, path: string) => ValidationError[] | Promise<ValidationError[]>;
+/** Result from the validation engine */
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+
+/** Full theme configuration using CSS custom property values */
+interface ThemeConfig {
+    /** Theme name identifier */
+    name: string;
+    /** Editor background */
+    bg: string;
+    /** Default text color */
+    fg: string;
+    /** Borders and dividers */
+    border: string;
+    /** Line number gutter background */
+    gutterBg: string;
+    /** Line number text */
+    gutterFg: string;
+    /** Text selection background */
+    selection: string;
+    /** Cursor color */
+    cursor: string;
+    /** Syntax: object keys */
+    keyColor: string;
+    /** Syntax: string values */
+    stringColor: string;
+    /** Syntax: number values */
+    numberColor: string;
+    /** Syntax: booleans */
+    booleanColor: string;
+    /** Syntax: null */
+    nullColor: string;
+    /** Syntax: brackets and braces */
+    bracketColor: string;
+    /** Matching bracket highlight */
+    bracketMatchBg: string;
+    /** Error indicator color */
+    errorColor: string;
+    /** Warning indicator color */
+    warningColor: string;
+    /** Success indicator color */
+    successColor: string;
+    /** Tree connector lines */
+    treeLine: string;
+    /** Tree hovered node background */
+    treeHover: string;
+    /** Tree selected node background */
+    treeSelected: string;
+    /** Type badge background */
+    typeBadgeBg: string;
+}
+
+/** Editing mode for the JSON editor */
+type EditorMode = 'code' | 'tree' | 'split';
+/** When to trigger validation */
+type ValidationMode = 'onChange' | 'onBlur' | 'onSubmit' | 'manual';
+/** Indentation configuration */
+type IndentationType = 2 | 4 | 'tab';
+/** Props for the root JsonEditor component */
+interface JsonEditorProps {
+    /** The JSON value — can be a parsed object or a raw JSON string */
+    value?: unknown;
+    /** Called when the JSON value changes */
+    onChange?: (value: unknown, rawText: string) => void;
+    /** Active editing mode */
+    mode?: EditorMode;
+    /** Called when the user switches modes */
+    onModeChange?: (mode: EditorMode) => void;
+    /** JSON Schema for validation (Draft-07, 2019-09, 2020-12) */
+    schema?: JSONSchema;
+    /** Custom validator functions */
+    validators?: CustomValidator[];
+    /** When to run validation */
+    validationMode?: ValidationMode;
+    /** Called when validation completes */
+    onValidate?: (errors: ValidationError[]) => void;
+    /** Theme: preset name, "auto" (follows OS), or custom config */
+    theme?: 'light' | 'dark' | 'auto' | ThemeConfig;
+    /** Editor height — CSS value or pixel number */
+    height?: string | number;
+    /** If true, editor is read-only */
+    readOnly?: boolean;
+    /** Enable search bar */
+    searchable?: boolean;
+    /** Enable key sorting */
+    sortable?: boolean;
+    /** Indentation style */
+    indentation?: IndentationType;
+    /** Show line numbers in code mode */
+    lineNumbers?: boolean;
+    /** Enable bracket matching */
+    bracketMatching?: boolean;
+    /** Max document size in bytes — shows warning above this */
+    maxSize?: number;
+    /** Enable virtual scrolling ("auto" enables for large docs) */
+    virtualize?: boolean | 'auto';
+    /** Called on parse/render errors */
+    onError?: (error: Error) => void;
+    /** Called when editor gains focus */
+    onFocus?: () => void;
+    /** Called when editor loses focus */
+    onBlur?: () => void;
+    /** Additional CSS class on the root element */
+    className?: string;
+    /** Inline styles on the root element */
+    style?: React.CSSProperties;
+    /** Accessible label for the editor */
+    'aria-label'?: string;
+}
+/** Internal editor state shared across sub-components */
+interface EditorState {
+    /** The raw JSON text */
+    text: string;
+    /** The parsed value (undefined if parse error) */
+    parsedValue: unknown;
+    /** Current parse error, if any */
+    parseError: ParseError | null;
+    /** Schema validation errors */
+    validationErrors: ValidationError[];
+    /** Current cursor position */
+    cursor: CursorPosition;
+    /** Current selection range */
+    selection: SelectionRange | null;
+    /** Whether the document has been modified */
+    isDirty: boolean;
+}
+/** Position in the text */
+interface CursorPosition {
+    line: number;
+    column: number;
+    offset: number;
+}
+/** A range of selected text */
+interface SelectionRange {
+    start: CursorPosition;
+    end: CursorPosition;
+}
+/** A JSON parse error with location info */
+interface ParseError {
+    message: string;
+    line: number;
+    column: number;
+    offset: number;
+}
+
+/**
+ * A production-grade JSON editor React component.
+ *
+ * Supports code editing, tree editing, split view, JSON Schema validation,
+ * undo/redo, search, theming, and full keyboard accessibility.
+ */
+declare const JsonEditor: React$1.FC<JsonEditorProps>;
+
+/** The type of a JSON value node */
+type JsonNodeType = 'string' | 'number' | 'boolean' | 'null' | 'object' | 'array';
+/** A node in the JSON tree representation */
+interface TreeNode {
+    /** Unique identifier for this node */
+    id: string;
+    /** The key name (for object properties) or index (for array items) */
+    key: string | number;
+    /** The value at this node */
+    value: unknown;
+    /** The type of the value */
+    type: JsonNodeType;
+    /** JSONPath from root (e.g., "$.address.city") */
+    path: string;
+    /** Depth in the tree (0 = root) */
+    depth: number;
+    /** Whether this node is expanded (for objects/arrays) */
+    expanded: boolean;
+    /** Child nodes (for objects/arrays) */
+    children: TreeNode[];
+    /** Number of descendant nodes (for display purposes) */
+    descendantCount: number;
+    /** Parent node ID (null for root) */
+    parentId: string | null;
+}
+/** Action types for tree editing operations */
+type TreeAction = {
+    type: 'SET_VALUE';
+    nodeId: string;
+    value: unknown;
+} | {
+    type: 'SET_KEY';
+    nodeId: string;
+    key: string;
+} | {
+    type: 'SET_TYPE';
+    nodeId: string;
+    newType: JsonNodeType;
+} | {
+    type: 'DELETE_NODE';
+    nodeId: string;
+} | {
+    type: 'ADD_CHILD';
+    parentId: string;
+    key: string;
+    value: unknown;
+} | {
+    type: 'MOVE_NODE';
+    nodeId: string;
+    targetParentId: string;
+    targetIndex: number;
+} | {
+    type: 'DUPLICATE_NODE';
+    nodeId: string;
+} | {
+    type: 'TOGGLE_EXPAND';
+    nodeId: string;
+} | {
+    type: 'EXPAND_ALL';
+} | {
+    type: 'COLLAPSE_ALL';
+};
+/** Context menu item definition */
+interface ContextMenuItem {
+    label: string;
+    icon?: string;
+    shortcut?: string;
+    action: () => void;
+    disabled?: boolean;
+    separator?: boolean;
+}
+
+declare const lightTheme: ThemeConfig;
+
+declare const darkTheme: ThemeConfig;
+
+/** Result of a JSON parse attempt */
+interface ParseResult {
+    value: unknown;
+    error: ParseError | null;
+}
+/**
+ * Parse a JSON string with detailed error location info.
+ * Uses native JSON.parse but enhances error messages with line/column.
+ */
+declare function parseJson(text: string): ParseResult;
+/**
+ * Stringify a value to formatted JSON text.
+ */
+declare function stringifyJson(value: unknown, indent?: number | string): string;
+/**
+ * Check if a string is valid JSON without returning the parsed value.
+ */
+declare function isValidJson(text: string): boolean;
+
+/**
+ * Validate a parsed JSON value against a JSON Schema (Draft-07 compatible subset).
+ * This is a built-in lightweight validator — for full draft support, users can
+ * supply an Ajv-based CustomValidator.
+ */
+declare function validateSchema(value: unknown, schema: JSONSchema, path?: string): ValidationResult;
+/**
+ * Run custom validators on a value.
+ */
+declare function runCustomValidators(value: unknown, validators: CustomValidator[], path?: string): Promise<ValidationError[]>;
+
+/**
+ * Pretty-print JSON text with the given indentation.
+ * Returns the original text if it cannot be parsed.
+ */
+declare function formatJson(text: string, indent?: IndentationType): string;
+/**
+ * Minify JSON text (remove all whitespace).
+ */
+declare function minifyJson(text: string): string;
+/**
+ * Sort object keys in JSON text.
+ * @param order - "asc" for ascending, "desc" for descending, or a custom comparator.
+ */
+declare function sortJsonKeys(text: string, order?: 'asc' | 'desc' | ((a: string, b: string) => number), indent?: IndentationType): string;
+/**
+ * Compute document statistics from a JSON value.
+ */
+interface JsonStats {
+    properties: number;
+    arrays: number;
+    totalNodes: number;
+    maxDepth: number;
+    byteSize: number;
+}
+declare function computeStats(value: unknown, text?: string): JsonStats;
+
+/**
+ * JSONPath and dot-notation utilities.
+ */
+/**
+ * Get a value from a nested object using a dot-notation path.
+ * Supports array indexing: "items[0].name" or "items.0.name"
+ */
+declare function getByPath(obj: unknown, path: string): unknown;
+/**
+ * Set a value in a nested object using a dot-notation path.
+ * Returns a new object (immutable operation).
+ */
+declare function setByPath(obj: unknown, path: string, value: unknown): unknown;
+/**
+ * Delete a key from a nested object by path.
+ * Returns a new object (immutable operation).
+ */
+declare function deleteByPath(obj: unknown, path: string): unknown;
+/**
+ * Parse a JSONPath or dot-notation string into segments.
+ * "$." prefix is stripped. Brackets are converted to dot notation.
+ * E.g., "$.store.book[0].author" → ["store", "book", "0", "author"]
+ */
+declare function parsePath(path: string): string[];
+/**
+ * Build a JSONPath string from segments.
+ */
+declare function buildPath(segments: (string | number)[]): string;
+
+interface UseJsonParserOptions {
+    /** JSON Schema for validation */
+    schema?: JSONSchema;
+    /** Custom validators */
+    validators?: CustomValidator[];
+    /** Debounce interval in ms */
+    debounce?: number;
+}
+interface UseJsonParserResult {
+    /** The current raw text */
+    text: string;
+    /** The parsed value (undefined if invalid) */
+    parsedValue: unknown;
+    /** Parse error, if any */
+    parseError: ParseError | null;
+    /** Validation errors from schema + custom validators */
+    validationErrors: ValidationError[];
+    /** Whether the text is valid JSON */
+    isValid: boolean;
+    /** Update the raw text */
+    setText: (text: string) => void;
+    /** Update from a parsed value */
+    setValue: (value: unknown) => void;
+    /** Format the current text */
+    format: (indent?: number | string) => void;
+}
+/**
+ * Hook that manages JSON parsing and validation state.
+ */
+declare function useJsonParser(initialValue?: unknown, options?: UseJsonParserOptions): UseJsonParserResult;
+
+interface UndoRedoOptions {
+    /** Maximum number of history entries */
+    maxHistory?: number;
+    /** Time window (ms) for grouping consecutive actions */
+    groupingInterval?: number;
+}
+interface UndoRedoState<T> {
+    current: T;
+    canUndo: boolean;
+    canRedo: boolean;
+    historyLength: number;
+    set: (value: T) => void;
+    undo: () => void;
+    redo: () => void;
+    reset: (value: T) => void;
+}
+/**
+ * A hook providing undo/redo history management with time-based grouping.
+ */
+declare function useUndoRedo<T>(initialValue: T, options?: UndoRedoOptions): UndoRedoState<T>;
+
+interface SearchMatch {
+    /** Line number (1-based) */
+    line: number;
+    /** Column start (0-based) */
+    columnStart: number;
+    /** Column end (0-based) */
+    columnEnd: number;
+    /** The matched text */
+    matchText: string;
+    /** JSONPath if in tree mode */
+    path?: string;
+}
+interface UseSearchOptions {
+    caseSensitive?: boolean;
+    useRegex?: boolean;
+    searchKeys?: boolean;
+    searchValues?: boolean;
+}
+interface UseSearchResult {
+    query: string;
+    setQuery: (q: string) => void;
+    matches: SearchMatch[];
+    currentMatchIndex: number;
+    totalMatches: number;
+    goToNext: () => void;
+    goToPrevious: () => void;
+    options: UseSearchOptions;
+    setOptions: (opts: Partial<UseSearchOptions>) => void;
+    isActive: boolean;
+    open: () => void;
+    close: () => void;
+}
+/**
+ * Hook for managing search state across the editor.
+ */
+declare function useSearch(text: string): UseSearchResult;
+
+export { type ContextMenuItem, type CursorPosition, type CustomValidator, type EditorMode, type EditorState, type IndentationType, type JSONSchema, JsonEditor, type JsonEditorProps, type JsonNodeType, type ParseError, type SelectionRange, type ThemeConfig, type TreeAction, type TreeNode, type ValidationError, type ValidationMode, type ValidationResult, type ValidationSeverity, buildPath, computeStats, darkTheme, deleteByPath, formatJson, getByPath, isValidJson, lightTheme, minifyJson, parseJson, parsePath, runCustomValidators, setByPath, sortJsonKeys, stringifyJson, useJsonParser, useSearch, useUndoRedo, validateSchema };