@proveanything/smartlinks-form-renderer/README.md

A flexible React component for rendering forms from JSON schema with conditional logic and storage configuration

# Schema Form Renderer

A flexible React component for rendering forms from JSON schema with conditional logic, table fields, and storage configuration.

## Installation

```bash
npm install @proveanything/smartlinks-form-renderer
```

## Usage

```tsx
import React from 'react';
import { SchemaFormRenderer, SchemaFormConfig } from '@proveanything/smartlinks-form-renderer';

const formConfig: SchemaFormConfig = {
  title: "Sample Form",
  description: "A sample form with conditional fields",
  schema: {
    type: "object",
    properties: {
      name: {
        type: "string",
        title: "Full Name"
      },
      email: {
        type: "string",
        format: "email",
        title: "Email Address"
      },
      subscribe: {
        type: "boolean",
        title: "Subscribe to newsletter"
      },
      preferences: {
        type: "string",
        format: "select",
        title: "Preferences",
        enum: ["daily", "weekly", "monthly"],
        enumNames: ["Daily", "Weekly", "Monthly"],
        conditions: [
          {
            targetFieldId: "subscribe",
            operator: "equals",
            value: true
          }
        ]
      }
    },
    required: ["name", "email"]
  },
  uiSchema: {
    name: {
      "ui:placeholder": "Enter your full name"
    },
    email: {
      "ui:placeholder": "Enter your email address"
    }
  },
  storage: {
    name: "public",
    email: "private",
    subscribe: "public",
    preferences: "public"
  },
  settings: {
    allowMultipleSubmissions: false,
    requireAuthentication: false,
    showProgressBar: false,
    submitButtonText: "Submit",
    successMessage: "Form submitted successfully!"
  },
  styling: {
    theme: "default",
    primaryColor: "#007bff",
    backgroundColor: "#ffffff"
  },
  fieldOrder: ["name", "email", "subscribe", "preferences"]
};

function MyForm() {
  const handleSubmit = (data: Record<string, any>) => {
    console.log('Form submitted:', data);
  };

  return (
    <SchemaFormRenderer
      config={formConfig}
      onSubmit={handleSubmit}
      isSubmitting={false}
      initialData={{ name: "John Doe" }} // Pre-populate form fields
    />
  );
}

export default MyForm;
```

## Props

### SchemaFormRenderer Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `config` | `SchemaFormConfig` | Required | The form configuration object |
| `onSubmit` | `(data: Record<string, any>) => void` | Required | Callback function called when form is submitted |
| `isSubmitting` | `boolean` | `false` | Whether the form is currently being submitted |
| `className` | `string` | `""` | Additional CSS classes to apply to the form container |
| `initialData` | `Record<string, any>` | `{}` | Initial data to populate form fields (takes precedence over schema defaults) |
| `components` | `object` | `{}` | Custom component overrides |

## Features

- **Conditional Logic**: Show/hide fields based on other field values
- **Multiple Field Types**: String, number, boolean, array, object, and table with various formats
- **Table Fields**: Dynamic table with customizable columns and row management
- **Storage Configuration**: Define privacy levels for each field
- **Custom Components**: Override default components with your own
- **Field Ordering**: Control the order of fields in the form
- **Initial Data**: Pre-populate form fields with existing data
- **TypeScript Support**: Full type definitions included

## Field Types and Formats

### String Fields
- `text` (default)
- `email`
- `textarea`
- `select`
- `radio`
- `checkboxes`
- `multiselect`
- `combobox`
- `file`
- `date`
- `date-time`

### Boolean Fields
- `checkbox` (default)
- `switch`

### Number/Integer Fields
- Standard number input with min/max validation

### Table Fields
- Dynamic table with customizable columns
- Support for string, number, boolean, and date column types
- Row management (add/remove rows)
- Configurable min/max rows

## Table Field Configuration

```tsx
{
  type: "table",
  title: "Items",
  columns: [
    {
      id: "name",
      title: "Item Name",
      type: "string",
      required: true
    },
    {
      id: "quantity",
      title: "Quantity",
      type: "number",
      required: true
    },
    {
      id: "active",
      title: "Active",
      type: "boolean"
    },
    {
      id: "date",
      title: "Date Added",
      type: "date"
    }
  ],
  minRows: 1,
  maxRows: 10
}
```

## Conditional Logic

Fields can be shown/hidden based on conditions:

```tsx
{
  type: "string",
  title: "Conditional Field",
  conditions: [
    {
      targetFieldId: "otherField",
      operator: "equals",
      value: "show"
    }
  ],
  showWhen: "all" // or "any" for multiple conditions
}
```

### Supported Operators
- `equals`
- `not_equals`
- `contains`
- `not_contains`
- `greater_than`
- `less_than`
- `is_empty`
- `is_not_empty`

## Field Ordering

Control the order of fields in your form:

```tsx
const formConfig: SchemaFormConfig = {
  // ... other config
  fieldOrder: ["name", "email", "phone", "address"]
};
```

If `fieldOrder` is not specified, fields will appear in the order they are defined in the schema properties.

## Initial Data

Pre-populate form fields with existing data:

```tsx
<SchemaFormRenderer
  config={formConfig}
  onSubmit={handleSubmit}
  initialData={{
    name: "John Doe",
    email: "john@example.com",
    preferences: ["daily", "weekly"]
  }}
/>
```

Initial data takes precedence over schema default values.

## Custom Components

You can override the default components:

```tsx
import { Button, Input } from './my-components';

<SchemaFormRenderer
  config={formConfig}
  onSubmit={handleSubmit}
  components={{
    Button,
    Input,
    TableInput: MyCustomTableComponent,
    // ... other components
  }}
/>
```

### Available Component Overrides
- `Button`
- `Input`
- `Textarea`
- `Select`
- `Checkbox`
- `RadioGroup`
- `Switch`
- `Label`
- `TableInput`

## Storage Configuration

Define privacy levels for each field:

```tsx
storage: {
  name: "public",      // Publicly visible
  email: "private",    // Private to user
  ssn: "proof",        // Cryptographic proof only
  notes: "personal"    // Personal notes
}
```

## Configuration Reference

### SchemaFormConfig

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Optional unique identifier |
| `title` | `string` | Form title |
| `description` | `string` | Form description |
| `schema` | `object` | JSON schema definition |
| `uiSchema` | `object` | UI configuration |
| `storage` | `object` | Storage configuration for each field |
| `settings` | `object` | Form behavior settings |
| `styling` | `object` | Theme and styling options |
| `fieldOrder` | `string[]` | Optional field ordering |

### Settings Object

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `allowMultipleSubmissions` | `boolean` | `false` | Allow multiple form submissions |
| `requireAuthentication` | `boolean` | `false` | Require user authentication |
| `showProgressBar` | `boolean` | `false` | Show form progress indicator |
| `submitButtonText` | `string` | `"Submit"` | Submit button text |
| `successMessage` | `string` | `"Form submitted successfully!"` | Success message |

### Styling Object

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `theme` | `"default" \| "modern" \| "minimal"` | `"default"` | Form theme |
| `primaryColor` | `string` | `"#007bff"` | Primary color |
| `backgroundColor` | `string` | `"#ffffff"` | Background color |

## TypeScript Support

The package includes comprehensive TypeScript definitions. Import types as needed:

```tsx
import {
  SchemaFormConfig,
  SchemaFormField,
  SchemaFormRendererProps,
  TableColumn,
  SchemaFormFieldCondition
} from '@proveanything/smartlinks-form-renderer';
```

## License

MIT