modern-json-react 1.0.0

package/dist/index.d.ts

@@ -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 };