json-schema-builder-react 0.0.3 → 0.0.5

package/README.md

@@ -6,14 +6,13 @@ A beautiful, interactive React component for building and editing JSON schemas v
 
 ## Features
 
-- 🎨 **Visual Editor** - Build JSON schemas with an intuitive drag-and-drop interface
+- 🎨 **Visual Editor** - Build JSON schemas with an intuitive interface
 - 📝 **Full JSON Schema Support** - Support for all JSON Schema types and constraints
 - 🎯 **Type-Safe** - Written in TypeScript with full type definitions
-- ✅ **Official JSON Schema Types** - Uses `@types/json-schema` for spec compliance
+- ✅ **Controlled Component** - Full control over state management
 - 🎨 **Customizable** - Flexible API with extensive customization options
-- 📦 **Headless Options** - Use just the hooks and utilities without UI
 - 🌗 **Theme Support** - Built-in dark mode support
-- ⚡ **Lightweight** - Tree-shakeable with minimal bundle size impact
+- ⚡ **Lightweight** - Minimal bundle size with focused API
 
 ## Installation
 
@@ -84,16 +83,20 @@ Add to your main CSS file (e.g., `src/index.css`):
 ### Basic Example
 
 ```tsx
+import { useState } from 'react';
 import { JsonSchemaBuilder } from 'json-schema-builder-react';
 
 function App() {
-  const handleSchemaChange = (schema) => {
-    console.log('Schema updated:', schema);
-  };
+  const [schema, setSchema] = useState({
+    type: 'object',
+    properties: {},
+    required: []
+  });
 
   return (
     <JsonSchemaBuilder 
-      onSchemaChange={handleSchemaChange}
+      schema={schema}
+      onChange={setSchema}
     />
   );
 }
@@ -102,24 +105,35 @@ function App() {
 ### With Initial Schema
 
 ```tsx
+import { useState } from 'react';
 import { JsonSchemaBuilder } from 'json-schema-builder-react';
 
-const initialSchema = {
-  type: 'object',
-  properties: {
-    name: { type: 'string' },
-    age: { type: 'number' }
-  },
-  required: ['name']
-};
-
 function App() {
+  const [schema, setSchema] = useState({
+    type: 'object',
+    title: 'User Profile',
+    properties: {
+      name: { 
+        type: 'string',
+        minLength: 2,
+        maxLength: 50
+      },
+      age: { 
+        type: 'integer',
+        minimum: 0,
+        maximum: 120
+      }
+    },
+    required: ['name']
+  });
+
   return (
     <JsonSchemaBuilder 
-      initialSchema={initialSchema}
-      onSchemaChange={(schema) => {
+      schema={schema}
+      onChange={(newSchema) => {
+        setSchema(newSchema);
         // Save to backend, localStorage, etc.
-        console.log(schema);
+        localStorage.setItem('schema', JSON.stringify(newSchema));
       }}
     />
   );
@@ -129,14 +143,21 @@ function App() {
 ### Customized Layout
 
 ```tsx
+import { useState } from 'react';
 import { JsonSchemaBuilder } from 'json-schema-builder-react';
 
 function App() {
+  const [schema, setSchema] = useState({
+    type: 'object',
+    properties: {},
+    required: []
+  });
+
   return (
     <JsonSchemaBuilder
+      schema={schema}
+      onChange={setSchema}
       showMetadata={true}
-      showImport={false}
-      showClear={true}
       showOutput={true}
       className="h-[600px]"
       typeLabels={{
@@ -145,33 +166,130 @@ function App() {
         object: 'Form',
         array: 'List',
       }}
+      propertyLabel={{
+        singular: 'field',
+        plural: 'fields'
+      }}
+    />
+  );
+}
+```
+
+### With Undo/Redo
+
+Since the component is fully controlled, you can implement undo/redo easily:
+
+```tsx
+import { useState } from 'react';
+import { JsonSchemaBuilder } from 'json-schema-builder-react';
+
+function App() {
+  const [history, setHistory] = useState([{
+    type: 'object',
+    properties: {},
+    required: []
+  }]);
+  const [currentIndex, setCurrentIndex] = useState(0);
+
+  const currentSchema = history[currentIndex];
+
+  const handleChange = (newSchema) => {
+    const newHistory = history.slice(0, currentIndex + 1);
+    newHistory.push(newSchema);
+    setHistory(newHistory);
+    setCurrentIndex(currentIndex + 1);
+  };
+
+  const undo = () => {
+    if (currentIndex > 0) {
+      setCurrentIndex(currentIndex - 1);
+    }
+  };
+
+  const redo = () => {
+    if (currentIndex < history.length - 1) {
+      setCurrentIndex(currentIndex + 1);
+    }
+  };
+
+  return (
+    <div>
+      <div className="toolbar">
+        <button onClick={undo} disabled={currentIndex === 0}>
+          Undo
+        </button>
+        <button onClick={redo} disabled={currentIndex === history.length - 1}>
+          Redo
+        </button>
+      </div>
+      
+      <JsonSchemaBuilder
+        schema={currentSchema}
+        onChange={handleChange}
+      />
+    </div>
+  );
+}
+```
+
+### Editable Property Keys (Advanced)
+
+By default, property keys are **immutable after creation** to prevent breaking existing references in your codebase. However, you can enable key editing with the `keyEditable` prop:
+
+```tsx
+import { useState } from 'react';
+import { JsonSchemaBuilder } from 'json-schema-builder-react';
+
+function App() {
+  const [schema, setSchema] = useState({
+    type: 'object',
+    properties: {
+      user_name: {
+        type: 'string',
+        title: 'User Name'
+      }
+    },
+    required: []
+  });
+
+  return (
+    <JsonSchemaBuilder
+      schema={schema}
+      onChange={setSchema}
+      keyEditable={true} // ⚠️ Allows changing keys after creation
     />
   );
 }
 ```
 
+**⚠️ Warning:** Enabling `keyEditable` allows users to change property keys even after they've been created. This can break existing code that references these keys. Use with caution, primarily in development environments or when you have proper migration strategies in place.
+
 ## API Reference
 
 ### JsonSchemaBuilder Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `initialSchema` | `object` | `undefined` | Initial JSON schema to load |
-| `onSchemaChange` | `(schema: any) => void` | `undefined` | Callback when schema changes |
-| `showMetadata` | `boolean` | `true` | Show metadata fields (title, description, version) |
+| `schema` | `object` | **Required** | The JSON schema object (controlled) |
+| `onChange` | `(schema: any) => void` | **Required** | Callback when schema changes |
+| `showMetadata` | `boolean` | `false` | Show metadata fields (title, description, version) |
 | `showImport` | `boolean` | `true` | Show import button |
 | `showClear` | `boolean` | `true` | Show clear all button |
 | `showOutput` | `boolean` | `true` | Show JSON output panel |
-| `headerContent` | `ReactNode` | `undefined` | Custom header content |
+| `showHeader` | `boolean` | `true` | Show header with action buttons |
+| `showSummary` | `boolean` | `false` | Show summary at bottom |
+| `showRegex` | `boolean` | `false` | Show regex pattern field for strings |
+| `keyEditable` | `boolean` | `false` | Allow editing property keys after initialization (⚠️ may break references) |
 | `className` | `string` | `"h-screen"` | Custom className for container |
-| `typeLabels` | `TypeLabels` | Default labels | Custom labels for property types (e.g., `{ string: 'Text', boolean: 'Yes/No' }`) |
-| `propertyLabel` | `{ singular: string, plural: string }` | `{ singular: 'property', plural: 'properties' }` | Custom labels for top-level properties (e.g., `{ singular: 'input', plural: 'inputs' }`) |
+| `typeLabels` | `TypeLabels` | Default labels | Custom labels for property types |
+| `propertyLabel` | `{ singular: string, plural: string }` | `{ singular: 'property', plural: 'properties' }` | Custom labels for properties |
 
 ### Customizing Type Labels
 
 You can customize how property types are displayed to your users:
 
 ```tsx
+import { useState } from 'react';
 import { JsonSchemaBuilder } from 'json-schema-builder-react';
 import type { TypeLabels } from 'json-schema-builder-react';
 
@@ -186,10 +304,17 @@ const customLabels: TypeLabels = {
 };
 
 function App() {
+  const [schema, setSchema] = useState({
+    type: 'object',
+    properties: {},
+    required: []
+  });
+
   return (
     <JsonSchemaBuilder 
+      schema={schema}
+      onChange={setSchema}
       typeLabels={customLabels}
-      onSchemaChange={(schema) => console.log(schema)}
     />
   );
 }
@@ -209,132 +334,55 @@ This affects:
 - `array` - Default: "Array"
 - `null` - Default: "Null"
 
-## Headless Usage
-
-Use just the hooks and utilities without the UI components:
-
-```tsx
-import { useSchemaBuilder, generateSchema } from 'json-schema-builder-react';
-
-function MyCustomEditor() {
-  const {
-    properties,
-    metadata,
-    schema,
-    addProperty,
-    updateProperty,
-    deleteProperty,
-  } = useSchemaBuilder(true);
-
-  return (
-    <div>
-      {/* Build your own custom UI */}
-      <button onClick={() => {
-        const newProp = addProperty();
-        updateProperty(newProp.id, {
-          ...newProp,
-          key: 'myProperty',
-          type: 'string'
-        });
-      }}>
-        Add Property
-      </button>
-      
-      <pre>{JSON.stringify(schema, null, 2)}</pre>
-    </div>
-  );
-}
-```
-
 ## Available Exports
 
-### Components
-- `JsonSchemaBuilder` - Main builder component
-- `PropertyDocument` - Individual property card
-- `PropertyEditDialog` - Property edit modal
-- `JsonOutput` - JSON output display
-- `SchemaMetadataComponent` - Schema metadata fields
-
-### Hooks
-- `useSchemaBuilder` - Main schema builder logic
-- `usePropertyEditor` - Property editing logic
-
-### Utilities
-- `generateSchema` - Generate JSON schema from properties
-- `parseSchema` - Parse JSON schema into properties
-- `downloadJsonFile` - Download schema as JSON file
-- `importJsonFile` - Import schema from file
+### Component
+- `JsonSchemaBuilder` - Main builder component (controlled)
 
 ### Types
-- `PropertyData` - Internal UI representation of a JSON Schema property (extends JSON Schema fields)
-- `PropertyType` - JSON Schema type names (from `@types/json-schema`)
-- `SchemaMetadata` - Schema metadata structure
-- `JSONSchema7` - Official JSON Schema Draft 7 type (from `@types/json-schema`)
-- `JSONSchema7TypeName` - JSON Schema type names (from `@types/json-schema`)
+- `JsonSchemaBuilderProps` - Props for the main component
+- `TypeLabels` - Type for customizing property type labels
 
-**Note**: This library uses official JSON Schema types from `@types/json-schema` to ensure compatibility with the JSON Schema specification.
+## Advanced Usage
 
-## Examples
+### Integration with State Management
 
-### Using Individual Components
+The controlled component pattern makes it easy to integrate with any state management solution:
 
+#### Redux
 ```tsx
-import { 
-  PropertyDocument, 
-  useSchemaBuilder 
-} from 'json-schema-builder-react';
+import { useSelector, useDispatch } from 'react-redux';
+import { JsonSchemaBuilder } from 'json-schema-builder-react';
+import { updateSchema } from './schemaSlice';
 
-function CustomEditor() {
-  const { properties, updateProperty, deleteProperty } = useSchemaBuilder();
+function App() {
+  const schema = useSelector(state => state.schema);
+  const dispatch = useDispatch();
 
   return (
-    <div>
-      {properties.map(property => (
-        <PropertyDocument
-          key={property.id}
-          property={property}
-          onUpdate={(updated) => updateProperty(property.id, updated)}
-          onDelete={() => deleteProperty(property.id)}
-        />
-      ))}
-    </div>
+    <JsonSchemaBuilder
+      schema={schema}
+      onChange={(newSchema) => dispatch(updateSchema(newSchema))}
+    />
   );
 }
 ```
 
-### Programmatic Schema Generation
-
+#### Zustand
 ```tsx
-import { generateSchema } from 'json-schema-builder-react';
-import type { PropertyData } from 'json-schema-builder-react';
-
-const properties: PropertyData[] = [
-  {
-    id: '1',
-    key: 'username',
-    type: 'string',
-    required: true,
-    constraints: {
-      minLength: 3,
-      maxLength: 20
-    }
-  },
-  {
-    id: '2',
-    key: 'email',
-    type: 'string',
-    required: true,
-    constraints: {
-      pattern: '^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$'
-    }
-  }
-];
-
-const schema = generateSchema(
-  properties,
-  { title: 'User Schema', description: 'User registration', version: '1.0.0' },
-  true
-);
+import { useSchemaStore } from './store';
+import { JsonSchemaBuilder } from 'json-schema-builder-react';
+
+function App() {
+  const { schema, setSchema } = useSchemaStore();
+
+  return (
+    <JsonSchemaBuilder
+      schema={schema}
+      onChange={setSchema}
+    />
+  );
+}
 ```
 
 ## Development

package/dist-lib/components/JsonSchemaBuilder.d.ts

@@ -57,8 +57,13 @@ export interface JsonSchemaBuilderProps {
      * @default false
      */
     showRegex?: boolean;
+    /**
+     * Whether to allow editing property keys after initialization
+     * @default false
+     */
+    keyEditable?: boolean;
 }
 /**
  * A visual JSON Schema builder component that allows building JSON schemas interactively
  */
-export declare function JsonSchemaBuilder({ schema, onChange, showMetadata, showImport, showClear, showOutput, showHeader, className, showSummary, typeLabels, propertyLabel, showRegex, }: JsonSchemaBuilderProps): import("react/jsx-runtime").JSX.Element;
+export declare function JsonSchemaBuilder({ schema, onChange, showMetadata, showImport, showClear, showOutput, showHeader, className, showSummary, typeLabels, propertyLabel, showRegex, keyEditable, }: JsonSchemaBuilderProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/PropertyDocument.d.ts

@@ -6,6 +6,7 @@ interface PropertyDocumentProps {
     level?: number;
     isArrayItem?: boolean;
     showRegex?: boolean;
+    keyEditable?: boolean;
 }
-export default function PropertyDocument({ property, onUpdate, onDelete, level, isArrayItem, showRegex, }: PropertyDocumentProps): import("react/jsx-runtime").JSX.Element;
+export default function PropertyDocument({ property, onUpdate, onDelete, level, isArrayItem, showRegex, keyEditable, }: PropertyDocumentProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist-lib/components/PropertyEditDialog.d.ts

@@ -11,6 +11,7 @@ interface PropertyEditDialogProps {
         plural: string;
     };
     showRegex?: boolean;
+    keyEditable?: boolean;
 }
-export default function PropertyEditDialog({ property, open, onOpenChange, onUpdate, isArrayItem, isNewProperty, propertyLabel, showRegex, }: PropertyEditDialogProps): import("react/jsx-runtime").JSX.Element;
+export default function PropertyEditDialog({ property, open, onOpenChange, onUpdate, isArrayItem, isNewProperty, propertyLabel, showRegex, keyEditable, }: PropertyEditDialogProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist-lib/components/ui/button.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
     size?: "default" | "sm" | "lg" | "icon" | null | undefined;
 } & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {

package/dist-lib/components/ui/dialog.d.ts

@@ -16,4 +16,4 @@ declare const DialogFooter: {
 };
 declare const DialogTitle: React.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogTitleProps & React.RefAttributes<HTMLHeadingElement>, "ref"> & React.RefAttributes<HTMLHeadingElement>>;
 declare const DialogDescription: React.ForwardRefExoticComponent<Omit<DialogPrimitive.DialogDescriptionProps & React.RefAttributes<HTMLParagraphElement>, "ref"> & React.RefAttributes<HTMLParagraphElement>>;
-export { Dialog, DialogPortal, DialogOverlay, DialogClose, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, };
+export { Dialog, DialogPortal, DialogOverlay, DialogTrigger, DialogClose, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, };

package/dist-lib/hooks/useChildManager.d.ts

@@ -0,0 +1,60 @@
+import type { PropertyData } from "@/types/schema";
+export interface UseChildManagerReturn {
+    /**
+     * Add a new child property (opens dialog)
+     */
+    addChild: () => void;
+    /**
+     * Update an existing child property
+     */
+    updateChild: (childId: string, updated: PropertyData) => void;
+    /**
+     * Delete a child property
+     */
+    deleteChild: (childId: string) => void;
+    /**
+     * Dialog manager for adding new children
+     */
+    addChildDialog: {
+        isOpen: boolean;
+        data: PropertyData | null;
+        setIsOpen: (isOpen: boolean) => void;
+        confirm: (data: PropertyData) => void;
+    };
+}
+/**
+ * Hook for managing child properties (nested properties within an object).
+ * Handles adding, updating, and deleting children with dialog state management.
+ *
+ * @param property - The parent property that contains children
+ * @param onUpdate - Callback to update the parent property
+ *
+ * @example
+ * ```tsx
+ * const childManager = useChildManager(property, onUpdate);
+ *
+ * // Add child button
+ * <Button onClick={childManager.addChild}>Add Child</Button>
+ *
+ * // Render children
+ * {property.children?.map((child) => (
+ *   <PropertyDocument
+ *     key={child.id}
+ *     property={child}
+ *     onUpdate={(updated) => childManager.updateChild(child.id, updated)}
+ *     onDelete={() => childManager.deleteChild(child.id)}
+ *   />
+ * ))}
+ *
+ * // Add child dialog
+ * {childManager.addChildDialog.isOpen && childManager.addChildDialog.data && (
+ *   <PropertyEditDialog
+ *     property={childManager.addChildDialog.data}
+ *     open={childManager.addChildDialog.isOpen}
+ *     onOpenChange={childManager.addChildDialog.setIsOpen}
+ *     onUpdate={childManager.addChildDialog.confirm}
+ *   />
+ * )}
+ * ```
+ */
+export declare function useChildManager(property: PropertyData, onUpdate: (property: PropertyData) => void): UseChildManagerReturn;

package/dist-lib/hooks/useDialogManager.d.ts

@@ -0,0 +1,75 @@
+export interface UseDialogManagerReturn<T> {
+    /**
+     * Whether the dialog is currently open
+     */
+    isOpen: boolean;
+    /**
+     * The data associated with the dialog (e.g., the item being edited/created)
+     */
+    data: T | null;
+    /**
+     * Open the dialog with optional data
+     */
+    open: (data?: T) => void;
+    /**
+     * Close the dialog without saving
+     */
+    close: () => void;
+    /**
+     * Confirm and close the dialog (typically calls the onConfirm callback)
+     */
+    confirm: (data: T) => void;
+    /**
+     * Set the dialog open state directly
+     */
+    setIsOpen: (isOpen: boolean) => void;
+}
+export interface UseDialogManagerOptions<T> {
+    /**
+     * Callback when dialog is confirmed/saved
+     */
+    onConfirm?: (data: T) => void;
+    /**
+     * Callback when dialog is cancelled/closed without saving
+     */
+    onCancel?: () => void;
+    /**
+     * Factory function to create initial data when opening dialog
+     */
+    createInitialData?: () => T;
+}
+/**
+ * Generic hook for managing dialog state with associated data.
+ * Useful for dialogs that create/edit items with temporary state.
+ *
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * // For adding a new property
+ * const addDialog = useDialogManager<PropertyData>({
+ *   createInitialData: () => ({
+ *     id: generateId(),
+ *     key: "",
+ *     type: "string",
+ *     required: false
+ *   }),
+ *   onConfirm: (property) => {
+ *     updateProperty(property.id, property);
+ *   }
+ * });
+ *
+ * // Usage in JSX
+ * <Button onClick={() => addDialog.open()}>Add Property</Button>
+ *
+ * {addDialog.isOpen && addDialog.data && (
+ *   <PropertyEditDialog
+ *     property={addDialog.data}
+ *     open={addDialog.isOpen}
+ *     onOpenChange={addDialog.setIsOpen}
+ *     onUpdate={addDialog.confirm}
+ *   />
+ * )}
+ * ```
+ */
+export declare function useDialogManager<T>(options?: UseDialogManagerOptions<T>): UseDialogManagerReturn<T>;

package/dist-lib/hooks/useInlineEditor.d.ts

@@ -0,0 +1,71 @@
+export interface UseInlineEditorOptions {
+    /**
+     * Whether to allow empty values. If false, reverts to original value on blur when empty.
+     * @default false
+     */
+    allowEmpty?: boolean;
+    /**
+     * Callback when editing starts
+     */
+    onEditStart?: () => void;
+    /**
+     * Callback when editing is cancelled
+     */
+    onEditCancel?: () => void;
+}
+export interface UseInlineEditorReturn {
+    /**
+     * Whether the field is currently being edited
+     */
+    isEditing: boolean;
+    /**
+     * The current edited value
+     */
+    value: string;
+    /**
+     * Start editing mode
+     */
+    startEdit: () => void;
+    /**
+     * Handle value changes
+     */
+    handleChange: (newValue: string) => void;
+    /**
+     * Handle blur event - saves or reverts changes
+     */
+    handleBlur: () => void;
+    /**
+     * Handle keyboard events (Enter to save, Escape to cancel)
+     */
+    handleKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => void;
+}
+/**
+ * Hook for managing inline editing state and behavior.
+ * Handles common patterns like Enter/Escape keys, blur to save, and syncing with external value changes.
+ *
+ * @param initialValue - The initial/current value from props
+ * @param onSave - Callback when value should be saved (on blur or Enter)
+ * @param options - Optional configuration
+ *
+ * @example
+ * ```tsx
+ * const titleEditor = useInlineEditor(
+ *   property.title || "",
+ *   (newValue) => onUpdate({ ...property, title: newValue }),
+ *   { allowEmpty: false }
+ * );
+ *
+ * {titleEditor.isEditing ? (
+ *   <Input
+ *     value={titleEditor.value}
+ *     onChange={(e) => titleEditor.handleChange(e.target.value)}
+ *     onBlur={titleEditor.handleBlur}
+ *     onKeyDown={titleEditor.handleKeyDown}
+ *     autoFocus
+ *   />
+ * ) : (
+ *   <span onClick={titleEditor.startEdit}>{property.title}</span>
+ * )}
+ * ```
+ */
+export declare function useInlineEditor(initialValue: string, onSave: (value: string) => void, options?: UseInlineEditorOptions): UseInlineEditorReturn;