forus-forms

Custom form components for FORUS applications using forms-js

Overview

forus-forms is a TypeScript package that provides custom form components designed specifically for FORUS applications. Built on top of @bpmn-io/form-js, it offers a registry-based system for creating and using reusable form components.

Features

• 🎯 Type-Safe Components - Full TypeScript support with strict typing
• 🔧 Component Registry - Plugin-style architecture for easy component addition
• 🎨 forms-js Integration - Seamless integration with @bpmn-io/form-js
• 🔒 Context-Aware - Automatic injection of FORUS application context
• ✅ Built-in Validation - Comprehensive validation system with custom validators
• 📦 Tree-Shakeable - ES modules with optimized bundle splitting

Installation

npm install forus-forms

Peer Dependencies:

npm install react react-dom

Quick Start

1. Import and Use Components

import { TestField, registerComponent, componentRegistry } from 'forus-forms';

// Components are automatically registered when imported
console.log(componentRegistry.getAll()); // Shows registered components

2. Create Custom Components

import React from 'react';
import { ForusFormFieldProps, registerComponent } from 'forus-forms';

const EmailField: React.FC<ForusFormFieldProps> = ({
  field,
  value,
  onChange,
  errors
}) => (
  <div>
    <input
      type="email"
      value={value || ''}
      onChange={(e) => onChange(e.target.value)}
      placeholder={field.placeholder}
    />
    {errors?.map((error, index) => (
      <div key={index} className="error">{error}</div>
    ))}
  </div>
);

// Register the component
registerComponent('email-field', {
  config: {
    type: 'email-field',
    label: 'Email Address',
    group: 'input',
    description: 'Email input with validation'
  },
  renderer: EmailField,
  validator: (value: string) => {
    if (!value) return null;
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return emailRegex.test(value) ? null : 'Invalid email address';
  }
});

3. Use with FORUS Context

import { ForusFormProvider } from 'forus-forms';

function App() {
  return (
    <ForusFormProvider
      context={{
        networkId: 'network-123',
        organizationId: 'org-456',
        userId: 'user-789'
      }}
    >
      {/* Your form components will have access to this context */}
      <YourFormComponents />
    </ForusFormProvider>
  );
}

Component Development

Component Interface

All custom components must implement the ForusFormFieldProps interface:

interface ForusFormFieldProps {
  // forms-js standard props
  field: FormField;
  value: any;
  onChange: (value: any) => void;
  onBlur?: () => void;

  // FORUS application context
  networkId?: string;
  organizationId?: string;
  userId?: string;

  // Component state
  disabled?: boolean;
  readonly?: boolean;
  errors?: string[];

  // Custom configuration
  config?: Record<string, any>;
}

Component Groups

Components are organized into logical groups:

• input - Text inputs, numbers, dates, etc.
• selection - Dropdowns, radios, checkboxes
• display - Labels, dividers, images
• layout - Columns, groups, tabs
• custom - FORUS-specific components

Built-in Validators

The package includes common validation functions:

import { validators } from 'forus-forms';

// Available validators
validators.required(value)           // Required field validation
validators.email(value)              // Email format validation
validators.minLength(5)(value)       // Minimum length validation
validators.maxLength(100)(value)     // Maximum length validation
validators.pattern(regex, msg)(value) // Custom regex validation
validators.number(value)             // Number validation
validators.integer(value)            // Integer validation
validators.min(0)(value)             // Minimum value validation
validators.max(100)(value)           // Maximum value validation
validators.url(value)                // URL format validation
validators.phone(value)              // Phone number validation

API Reference

Registry Functions

import { componentRegistry, registerComponent } from 'forus-forms';

// Register a component
registerComponent(name: string, component: FormComponent): void

// Get a specific component
componentRegistry.get(name: string): FormComponent | undefined

// Get all components
componentRegistry.getAll(): Map<string, FormComponent>

// Get components by group
componentRegistry.getByGroup(group: ComponentGroup): Map<string, FormComponent>

// Debug helper
componentRegistry.debug(): void

Context Hook

import { useForusContext } from 'forus-forms';

function MyComponent() {
  const { networkId, organizationId, userId } = useForusContext();
  // Use context values...
}

Development

Building the Package

# Install dependencies
npm install

# Build the package
npm run build

# Watch for changes during development
npm run dev

# Type checking
npm run type-check

# Clean build artifacts
npm run clean

Package Structure

src/
├── components/          # Custom form components
├── registry/           # Component registration system
├── types/              # TypeScript type definitions
├── utils/              # Utility functions and validators
└── index.ts            # Main package exports

Contributing

1. Create new components in src/components/
2. Ensure components implement ForusFormFieldProps
3. Add component registration call
4. Include validation function if applicable
5. Add to component exports in src/components/index.ts

License

MIT License - see LICENSE file for details

Related Projects

• @bpmn-io/form-js - The underlying form engine
• FORUS Digital - The FORUS ecosystem

Part of the FORUS Digital ecosystem for network activation and value creation.