Protokol Components

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

Installation

npm install @ptkl/components

Usage

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 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

# 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

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

# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

Storybook

View and develop components in isolation:

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

// 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

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