@ht-rnd/json-schema-editor 2.0.1 → 2.0.3

package/README.md

@@ -1,13 +1,19 @@
 # @ht-rnd/json-schema-editor
 
-A headless JSON Schema editor library for React. This package provides the core logic, hooks, and utilities for building JSON Schema editors, while allowing complete control over the UI.
+A powerful **headless** JSON Schema editor for React. Build fully customized editors with complete UI control while leveraging battle-tested logic, validation, and state management.
 
-## Architecture
+> **Headless Architecture**: Core logic via npm + optional copy-paste UI components. Use our pre-built Shadcn/ui components or build your own interface.
 
-This library follows the **headless UI pattern**:
+## Features
 
-- **NPM Package**: Contains only the headless core - hooks, types, validation, and utilities
-- **Components Folder**: Contains copy-paste shadcn-style React components for the UI
+- **JSON Schema Draft 2020-12** - Full specification support
+- **All Types** - string, number, integer, boolean, object, array, $ref
+- **Nested Schemas** - Unlimited depth for objects and arrays
+- **$defs Support** - Reusable definitions with `$ref`
+- **Validation** - AJV-powered real-time validation
+- **Combinators** - allOf, anyOf, oneOf, not
+- **TypeScript** - Full type safety
+- **Headless** - Zero UI dependencies in core
 
 ## Installation
 
@@ -15,170 +21,47 @@ This library follows the **headless UI pattern**:
 npm install @ht-rnd/json-schema-editor
 ```
 
-### For UI Components
-
-Copy the `components/json-schema-editor/` folder from this repository into your project. These components are designed to be customized and follow [shadcn/ui](https://ui.shadcn.com/) principles.
-
-**Required peer dependencies for UI components:**
-
-```bash
-npm install @radix-ui/react-alert-dialog @radix-ui/react-checkbox @radix-ui/react-dialog \
-  @radix-ui/react-label @radix-ui/react-radio-group @radix-ui/react-select \
-  @radix-ui/react-separator @radix-ui/react-slot @radix-ui/react-tooltip \
-  class-variance-authority clsx lucide-react tailwind-merge tailwindcss-animate
-```
-
-## Features
-
-### Core Capabilities
-
-- **JSON Schema 2020-12** - Full support for draft 2020-12 specification
-- **Multiple Data Types** - string, number, integer, boolean, object, array, and $ref
-- **Nested Schemas** - Support for nested objects and arrays with unlimited depth
-- **Definitions ($defs)** - Create reusable schema definitions with $ref support
-- **Validation Constraints** - min/max, length, format, pattern, enum, and more
-- **Boolean Combinators** - allOf, anyOf, oneOf, not for complex schema logic
-- **Real-time Validation** - AJV-based validation with inline error messages
-- **Type Safety** - Full TypeScript support with comprehensive type definitions
-
-### UI Features (Pre-built Components)
-
-- **Responsive Layout** - Configurable form and output positioning (top/bottom/left/right)
-- **Customizable Sizing** - Flexible width and height options (sm/md/lg/full)
-- **Dark Mode Ready** - Theme prop support for dark/light mode
-- **Read-only Mode** - View-only mode for displaying schemas
-- **Settings Dialogs** - Rich settings for each field type with type-specific options
-- **Inline Editing** - Direct field manipulation with instant feedback
-
-## Usage
-
-### Option 1: Using the Headless Hook (Full Control)
-
-Use the `useJsonSchemaEditor` hook directly for complete control over the UI:
-
-```tsx
-import { useJsonSchemaEditor } from "@ht-rnd/json-schema-editor";
-import { FormProvider } from "react-hook-form";
-
-function MyCustomEditor() {
-  const editor = useJsonSchemaEditor({
-    rootType: "object",
-    onChange: (schema) => console.log("Schema changed:", schema),
-  });
-
-  return (
-    <FormProvider {...editor.form}>
-      <div>
-        {/* Your custom UI here */}
-        <pre>{JSON.stringify(editor.schema, null, 2)}</pre>
-        
-        <button onClick={editor.addField}>Add Field</button>
-        <button onClick={editor.addDefinition}>Add Definition</button>
-        
-        {editor.fields.map((field, index) => (
-          <div key={field.id}>
-            {/* Render your custom field UI */}
-            <input value={field.key} />
-            <button onClick={() => editor.removeField(index)}>Remove</button>
-            <button onClick={() => editor.openSettings(`properties.${index}`)}>Settings</button>
-          </div>
-        ))}
-
-        {editor.definitions.map((def, index) => (
-          <div key={def.id}>
-            <input value={def.key} />
-            <button onClick={() => editor.removeDefinition(index)}>Remove</button>
-          </div>
-        ))}
-
-        {editor.errors && (
-          <div>
-            {editor.errors.map((error, i) => (
-              <p key={i}>{error.message}</p>
-            ))}
-          </div>
-        )}
-      </div>
-    </FormProvider>
-  );
-}
-```
+**Optional UI components**: Copy `components/ui/` from this repo to your project. Requires Radix UI and Tailwind CSS.
 
-### Option 2: Using the Pre-built Components
+## Quick Start
 
-Copy the components from `components/json-schema-editor/` and use them directly:
+### Option 1: Pre-built Components
 
 ```tsx
-import { JsonSchemaEditor } from "@/components/json-schema-editor";
+import { JsonSchemaEditor } from "@/components/ui/json-schema-editor";
 
 function App() {
   return (
     <JsonSchemaEditor
       rootType="object"
-      theme="light"
-      readOnly={false}
-      showOutput={true}
       onChange={(schema) => console.log(schema)}
-      styles={{
-        form: { width: "full", height: "md" },
-        output: { position: "bottom", showJson: true, width: "full", height: "md" },
-        settings: { width: "md" },
-        spacing: "md",
-      }}
     />
   );
 }
 ```
 
-### Option 3: Mix and Match
-
-Use the headless hook with some pre-built components:
+### Option 2: Headless Hook
 
 ```tsx
 import { useJsonSchemaEditor } from "@ht-rnd/json-schema-editor";
-import { Root, FieldList, SettingsDialog } from "@/components/json-schema-editor";
 import { FormProvider } from "react-hook-form";
 
-function HybridEditor() {
-  const editor = useJsonSchemaEditor({ rootType: "object" });
+function App() {
+  const editor = useJsonSchemaEditor({
+    rootType: "object",
+    onChange: (schema) => console.log(schema),
+  });
 
   return (
     <FormProvider {...editor.form}>
-      <div className="space-y-4">
-        <Root
-          rootType="object"
-          onAddField={editor.addField}
-          onOpenSettings={editor.openSettings}
-        />
-        
-        <FieldList
-          fields={editor.fields}
-          onRemove={editor.removeField}
-          onOpenSettings={editor.openSettings}
-        />
-
-        {/* Add definitions support */}
-        {editor.definitions.length > 0 && (
-          <div className="mt-4">
-            <h3>Definitions ($defs)</h3>
-            {editor.definitions.map((def, index) => (
-              <div key={def.id}>
-                <span>{def.key}</span>
-                <button onClick={() => editor.removeDefinition(index)}>Remove</button>
-              </div>
-            ))}
-          </div>
-        )}
-
-        {/* Your custom JSON output */}
-        <textarea value={JSON.stringify(editor.schema, null, 2)} readOnly />
-
-        <SettingsDialog
-          isOpen={editor.settingsState.isOpen}
-          fieldPath={editor.settingsState.fieldPath}
-          onClose={editor.closeSettings}
-        />
-      </div>
+      <button onClick={editor.addField}>Add Field</button>
+      {editor.fields.map((field, index) => (
+        <div key={field.id}>
+          <input value={field.key} />
+          <button onClick={() => editor.removeField(index)}>Remove</button>
+        </div>
+      ))}
+      <pre>{JSON.stringify(editor.schema, null, 2)}</pre>
     </FormProvider>
   );
 }
@@ -186,71 +69,53 @@ function HybridEditor() {
 
 ## API Reference
 
-### `JsonSchemaEditor` Component (Pre-built)
-
-The pre-built React component with full UI implementation.
-
-#### Props
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `rootType` | `"object" \| "array"` | `"object"` | Root schema type |
-| `defaultValue` | `JSONSchema` | - | Initial schema value |
-| `onChange` | `(schema: JSONSchema) => void` | - | Callback when schema changes |
-| `readOnly` | `boolean` | `false` | Make all inputs read-only |
-| `showOutput` | `boolean` | `true` | Show/hide output panel |
-| `theme` | `string` | `"light"` | Theme class for styling |
-| `styles` | `Partial<Styles>` | - | Layout and sizing configuration |
-| `className` | `string` | - | Additional CSS classes |
+### `useJsonSchemaEditor(options)`
 
-#### Styles Configuration
+Main hook for editor state management.
 
+**Options:**
 ```typescript
-interface Styles {
-  form: { width: "sm" | "md" | "lg" | "full"; height: "sm" | "md" | "lg" | "full" };
-  output: {
-    position: "top" | "bottom" | "left" | "right";
-    showJson: boolean;
-    width: "sm" | "md" | "lg" | "full";
-    height: "sm" | "md" | "lg" | "full";
-  };
-  settings: { width: "sm" | "md" | "lg" | "full" };
-  spacing: "sm" | "md" | "lg";
+{
+  rootType?: "object" | "array";  // Default: "object"
+  defaultValue?: JSONSchema;       // Load existing schema
+  onChange?: (schema: JSONSchema) => void;
 }
 ```
 
-### `useJsonSchemaEditor(options)`
-
-The main headless hook for managing JSON Schema editor state.
+**Returns:**
+```typescript
+{
+  // State
+  schema: JSONSchema;
+  errors: ErrorObject[] | null;
+  fields: FieldItem[];
+  definitions: DefinitionItem[];
+  form: UseFormReturn;
+  settingsState: { isOpen: boolean; fieldPath: string | null };
+  
+  // Actions
+  addField: () => void;
+  removeField: (index: number) => void;
+  addDefinition: () => void;
+  removeDefinition: (index: number) => void;
+  openSettings: (path: string) => void;
+  closeSettings: () => void;
+  handleTypeChange: (path: string, type: string) => void;
+  addNestedField: (parentPath: string) => void;
+  reset: () => void;
+}
+```
 
-#### Options
+### `JsonSchemaEditor` Component Props
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
 | `rootType` | `"object" \| "array"` | `"object"` | Root schema type |
-| `defaultValue` | `JSONSchema` | - | Initial schema value |
-| `onChange` | `(schema: JSONSchema) => void` | - | Callback when schema changes |
-
-#### Returns
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `schema` | `JSONSchema` | Current JSON Schema output |
-| `errors` | `ErrorObject[] \| null` | AJV validation errors |
-| `fields` | `FieldItem[]` | Field array for iteration |
-| `definitions` | `DefinitionItem[]` | Definition array for $defs |
-| `form` | `UseFormReturn` | React Hook Form methods |
-| `settingsState` | `{ isOpen, fieldPath }` | Settings dialog state |
-| `addField()` | `() => void` | Add a new field |
-| `removeField(index)` | `(index: number) => void` | Remove field by index |
-| `addDefinition()` | `() => void` | Add a new definition to $defs |
-| `removeDefinition(index)` | `(index: number) => void` | Remove definition by index |
-| `updateReferences(oldKey, newKey)` | `(oldKey: string, newKey: string \| null) => void` | Update $ref references when definition key changes |
-| `openSettings(path)` | `(path: string) => void` | Open settings for a field |
-| `closeSettings()` | `() => void` | Close settings dialog |
-| `handleTypeChange(path, type)` | `(path: string, type: string) => void` | Change field type |
-| `addNestedField(parentPath)` | `(parentPath: string) => void` | Add a nested field to an object |
-| `reset()` | `() => void` | Reset to default state |
+| `defaultValue` | `JSONSchema` | - | Initial schema to load |
+| `onChange` | `(schema) => void` | - | Callback on schema change |
+| `readOnly` | `boolean` | `false` | View-only mode |
+| `showOutput` | `boolean` | `true` | Show/hide JSON output |
+| `className` | `string` | - | Additional CSS classes |
 
 ### Exports
 
@@ -259,124 +124,70 @@ The main headless hook for managing JSON Schema editor state.
 export { useJsonSchemaEditor } from "@ht-rnd/json-schema-editor";
 
 // Types
-export type {
-  JSONSchema,
-  FormSchema,
-  JsonSchemaEditorOptions,
-  SettingsState,
-  FieldItem,
-  DefinitionItem,
-  SchemaType,
-  SchemaTypeValue,
-  SchemaTypeWithRefValue,
-  UseJsonSchemaEditorReturn,
-} from "@ht-rnd/json-schema-editor";
-
-// Validation
-export { validateSchema } from "@ht-rnd/json-schema-editor";
-export { jsonSchemaZod } from "@ht-rnd/json-schema-editor";
+export type { JSONSchema, FieldItem, DefinitionItem, UseJsonSchemaEditorReturn };
+
+// Utilities
+export { validateSchema, formToSchema, schemaToForm };
 
 // Constants
-export {
-  SCHEMA_TYPES,
-  SCHEMA_TYPES_WITH_REF,
-  INTEGER_FORMATS,
-  NUMBER_FORMATS,
-  STRING_FORMATS,
-  DEFAULT_SCHEMA_URI,
-} from "@ht-rnd/json-schema-editor";
-
-// Transforms and utilities
-export { formToSchema, schemaToForm } from "@ht-rnd/json-schema-editor";
-export {
-  createDefaultObjectSchema,
-  createDefaultArraySchema,
-  createDefaultField,
-} from "@ht-rnd/json-schema-editor";
+export { SCHEMA_TYPES, STRING_FORMATS, NUMBER_FORMATS, INTEGER_FORMATS };
 ```
 
-## Component Architecture
+## Examples
 
-### Available Components
+### Load Existing Schema
 
-The `components/json-schema-editor/` folder includes these ready-to-use components:
-
-#### Form Components
-- `JsonSchemaEditor` - Complete editor with form and output
-- `Root` - Root field component with type selector
-- `FieldList` - List of field rows
-- `FieldRow` - Individual field row with controls
-- `Field` - Recursive field component for nested schemas
-
-#### Settings Components
-- `SettingsDialog` - Modal dialog for field settings
-- `Settings` - Main settings router component
-- `StringSettings`, `NumberSettings`, `IntegerSettings`, `BooleanSettings` - Type-specific settings
-- `ObjectSettings`, `ArraySettings` - Complex type settings
-- `BoolCombSettings` - allOf/anyOf/oneOf/not settings
-- `DefinitionsSettings` - $defs management
-- `RootSettings` - Root schema settings
-
-#### UI Primitives
-All based on [shadcn/ui](https://ui.shadcn.com/): `Button`, `Input`, `Select`, `Checkbox`, `Dialog`, `Badge`, `Tooltip`, etc.
-
-## Customizing Components
+```tsx
+const editor = useJsonSchemaEditor({
+  rootType: "object",
+  defaultValue: {
+    type: "object",
+    properties: {
+      username: { type: "string", minLength: 3 },
+      email: { type: "string", format: "email" },
+      age: { type: "integer", minimum: 18 }
+    },
+    required: ["username", "email"]
+  }
+});
+```
 
-The components in `components/json-schema-editor/` follow shadcn/ui patterns:
+### Validate Data Against Schema
 
-1. **`cn()` utility**: All components use the `cn()` function to merge Tailwind classes
-2. **`className` prop**: Every component accepts a `className` prop for customization
-3. **`forwardRef`**: Components forward refs for DOM access
-4. **Composable**: Use individual components or compose your own
-5. **Copy & Modify**: Copy components into your project and customize as needed
+```tsx
+import Ajv from "ajv";
 
-### Example: Customizing the FieldRow
+const ajv = new Ajv();
+const validate = ajv.compile(editor.schema);
+const valid = validate({ username: "john", email: "john@example.com" });
 
-```tsx
-import { FieldRow } from "@/components/json-schema-editor";
-
-<FieldRow
-  className="bg-slate-50 dark:bg-slate-900 rounded-lg"
-  fieldPath="properties.0"
-  theme="dark"
-  // ... other props
-/>
+if (!valid) console.log(validate.errors);
 ```
 
-### Example: Creating a Custom Field Component
+### Persist Schema Changes
 
 ```tsx
-import * as React from "react";
-import { Controller, useFormContext } from "react-hook-form";
-import { cn } from "./lib/utils";
-import { Input } from "./ui/input";
+const editor = useJsonSchemaEditor({
+  onChange: (schema) => {
+    localStorage.setItem("schema", JSON.stringify(schema));
+    // Or send to API
+  }
+});
+```
 
-interface MyCustomFieldProps extends React.HTMLAttributes<HTMLDivElement> {
-  fieldPath: string;
-}
+## Contributing
 
-const MyCustomField = React.forwardRef<HTMLDivElement, MyCustomFieldProps>(
-  ({ className, fieldPath, ...props }, ref) => {
-    const { control } = useFormContext();
-
-    return (
-      <div ref={ref} className={cn("flex gap-2", className)} {...props}>
-        <Controller
-          control={control}
-          name={`${fieldPath}.key`}
-          render={({ field }) => (
-            <Input {...field} placeholder="Field name" />
-          )}
-        />
-      </div>
-    );
-  }
-);
-MyCustomField.displayName = "MyCustomField";
+Contributions welcome! See [GitHub](https://github.com/ht-rnd/json-schema-editor) for issues and PRs.
 
-export { MyCustomField };
+```bash
+git clone https://github.com/ht-rnd/json-schema-editor.git
+npm install
+npm test
+npm run demo
 ```
 
 ## License
 
-Apache-2.0
+Apache-2.0 © [HT-RND]
+
+See [LICENSE](./LICENSE) for more details.