npm package: @ptkl/components
Description: A React component library for Protokol
Latest version: 0.11.0

# Protokol Components

A React component library built with TypeScript, featuring a powerful dynamic form builder with custom field management and validation.

## Installation

```bash
npm install @ptkl/components
```

## Usage

```typescript
import { Properties, usePropertiesForm, FieldRenderer } from '@ptkl/components';

const CustomForm = () => {
  const [fields, setFields] = useState<FieldDefinition[]>([]);
  const { formData, errors, updateField, validateForm } = usePropertiesForm(fields);

  return (
    <div>
      <Properties 
        fields={fields} 
        onFieldsChange={setFields}
        title="Custom Fields"
      />
      
      <div className="grid grid-cols-2 gap-4">
        {fields
          .filter(field => field.isActive)
          .map(field => (
            <FieldRenderer
              key={field.id}
              field={field}
              value={formData[field.name]}
              onChange={(value) => updateField(field.name, value)}
              errors={errors}
            />
          ))}
      </div>
    </div>
  );
};
```

## Components

### 📋 Properties

A comprehensive dynamic form builder for creating, managing, and validating custom fields.

See [Properties Documentation](./src/components/Properties/README.md) for detailed usage and examples.

#### Features

- 🎯 **Dynamic Field Creation** - 15+ field types (text, number, email, select, date, file, etc.)
- ✅ **Built-in Validation** - Comprehensive validation with custom patterns and rules
- 📋 **Field Management** - Add, edit, delete, duplicate, and reorder fields
- 💾 **Import/Export** - Save and load field configurations as JSON
- ⚡ **Custom onChange Logic** - Execute custom JavaScript with debouncing
- 👁️ **Live Preview** - See how fields appear in real-time
- 📊 **Field Statistics** - Overview of field usage and configuration
- 🎛️ **Rich Configuration** - Extensive options for each field type

#### Field Types

text, number, email, phone, textarea, select, multi-select, checkbox, radio, date, datetime, time, url, file, boolean

## Development

### Prerequisites

- Node.js 16+
- npm or yarn

### Setup

```bash
# Clone the repository
git clone <repository-url>
cd protokol-components

# Install dependencies
npm install
```

### Available Scripts

- `npm run build` - Build the library for production
- `npm run dev` - Start development server with watch mode
- `npm run test` - Run the test suite
- `npm run test:watch` - Run tests in watch mode
- `npm run storybook` - Start Storybook for component development
- `npm run build-storybook` - Build Storybook for deployment
- `npm run lint` - Run ESLint
- `npm run lint:fix` - Run ESLint with auto-fix
- `npm run type-check` - Run TypeScript type checking

### Building

```bash
npm run build
```

This will create the `dist` folder with:
- `index.js` - CommonJS build
- `index.esm.js` - ES modules build
- `index.d.ts` - TypeScript declarations

### Testing

```bash
# Run tests once
npm test

# Run tests in watch mode
npm run test:watch
```

### Storybook

View and develop components in isolation:

```bash
npm run storybook
```

This will start Storybook at `http://localhost:6006`.

## Project Structure

```
src/
  components/
    Properties/
      Properties.tsx      # Main form builder component
      PropertiesSection.tsx
      FieldEditor.tsx     # Field configuration editor
      FieldRenderer.tsx   # Field rendering component
      fields/             # Individual field type implementations
        TextField.tsx
        NumberField.tsx
        SelectField.tsx
        DateField.tsx
        ... (15+ field types)
      hooks/
        useApiData.ts     # API integration hook
      types.ts            # TypeScript type definitions
      utils.ts            # Utility functions
      README.md           # Detailed component documentation
      index.ts            # Component exports
    index.ts              # All component exports
  index.ts                # Main library export
dist/                     # Built library (generated)
.storybook/               # Storybook configuration
```

## TypeScript

This library is built with TypeScript and provides full type definitions. All components include comprehensive TypeScript interfaces for props and are fully typed.

### Available Exports

```typescript
// Components
import { 
  Properties,
  PropertiesSection,
  FieldEditor,
  FieldRenderer 
} from '@ptkl/components';

// Hooks
import { usePropertiesForm } from '@ptkl/components';

// Types
import type { 
  FieldDefinition,
  FieldType,
  FieldOption,
  FieldValidation,
  PropertiesProps,
  FormErrors,
  ValidationRule
} from '@ptkl/components';

// Utilities
import { 
  exportFieldsToJSON, 
  importFieldsFromJSON 
} from '@ptkl/components';
```

## Documentation

For detailed documentation on the Properties component, including:
- Complete API reference
- Advanced usage examples
- Custom validation rules
- Field configuration options
- Custom onChange logic
- Best practices

See [Properties Component Documentation](./src/components/Properties/README.md)

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add your component with tests and stories
4. Run the test suite
5. Submit a pull request

### Adding New Components

1. Create a new folder in `src/components/`
2. Add your component implementation with TypeScript
3. Write unit tests using Jest and React Testing Library
4. Create Storybook stories for documentation
5. Export your component from `src/components/index.ts`

## License

MIT