@tcn/ui-forms

A comprehensive form management system that provides field components, form validation, and layout management for building complex, accessible forms in React applications.

Overview

@tcn/ui-forms provides a complete solution for building forms with proper validation, error handling, and responsive layouts. The package includes field components, form presenters for state management, and layout utilities that work seamlessly with the Blackcat UI design system.

What's Included

Field Components

• Field: Responsive field container that adapts between horizontal and vertical layouts
• HField: Horizontal field layout with label and input side-by-side
• VField: Vertical field layout with label above input
• FormField: Specialized field for form-specific functionality
• FieldSet: Grouped fields with legends and optional adornments

Field Elements

• FieldLabel: Accessible label component with proper associations
• FieldDescription: Helpful text and instructions for form fields
• FieldError: Error message display with accessibility features
• FieldControl: Container for input components with consistent styling
• StatusInput: Input wrapper with status indicators

Form Management

• FieldPresenter: State management and validation for individual fields
• OptionsFieldPresenter: Specialized presenter for option-based fields
• Validation System: Built-in validation with custom validator support

Layout Features

• Responsive Design: Automatic layout switching based on container width
• Flexible Spacing: Consistent spacing using design system tokens
• Adornment Support: Start and end adornments for enhanced functionality

Key Features

• Responsive Layouts: Automatically switches between horizontal and vertical layouts
• Built-in Validation: Comprehensive validation system with custom validator support
• State Management: Integrated with Blackcat state management for reactive updates
• Accessibility First: ARIA attributes, proper labeling, and screen reader support
• Design System Integration: Seamlessly works with Blackcat UI themes and spacing
• TypeScript Support: Full type safety with excellent IntelliSense
• Performance Optimized: Efficient rendering with minimal re-renders

Usage

Basic Field

import { Field, FieldLabel, FieldControl } from '@tcn/ui-forms';
import { Input } from '@tcn/ui-inputs';

function MyForm() {
  return (
    <Field label="Email Address" description="We'll never share your email">
      <FieldLabel>Email</FieldLabel>
      <FieldControl>
        <Input type="email" placeholder="Enter your email" />
      </FieldControl>
    </Field>
  );
}

Field with Validation

import { useState } from 'react';
import { Field, FieldPresenter } from '@tcn/ui-forms';
import { useSignalValue } from '@tcn/state';

function ValidatedField() {
  const [presenter] = useState(() => new FieldPresenter('Username', '', {
    description: 'Choose a unique username',
    validate: async (value) => {
      if (value.length < 3) {
        throw new Error('Username must be at least 3 characters');
      }
      // Additional validation logic
    },
    validateOnChange: true
  }));

  const state = useSignalValue(presenter.stateBroadcast);

  return (
    <Field 
      label={state.label}
      description={state.description}
      error={state.error}
    >
      <FieldLabel>{state.label}</FieldLabel>
      <FieldControl>
        <Input 
          value={state.value}
          onChange={(value) => presenter.setValue(value)}
        />
      </FieldControl>
      {state.hasError && <FieldError>{state.error}</FieldError>}
    </Field>
  );
}

Field Groups

import { FieldSet, Field } from '@tcn/ui-forms';

function UserProfileForm() {
  return (
    <FieldSet legend="Personal Information">
      <Field label="First Name">
        <FieldLabel>First Name</FieldLabel>
        <FieldControl>
          <Input placeholder="Enter first name" />
        </FieldControl>
      </Field>
      
      <Field label="Last Name">
        <FieldLabel>Last Name</FieldLabel>
        <FieldControl>
          <Input placeholder="Enter last name" />
        </FieldControl>
      </Field>
    </FieldSet>
  );
}

Responsive Layout

import { Field } from '@tcn/ui-forms';

function ResponsiveForm() {
  return (
    <Field 
      label="Description"
      breakpointPixels={768} // Switch to vertical layout below 768px
      labelWidth="200px"     // Fixed label width in horizontal mode
    >
      <FieldLabel>Description</FieldLabel>
      <FieldControl>
        <Textarea placeholder="Enter description" />
      </FieldControl>
    </Field>
  );
}

Component Architecture

Field Component

The main field component that:

• Automatically switches between horizontal and vertical layouts
• Manages responsive behavior based on container width
• Provides consistent spacing and alignment
• Integrates with design system tokens

Field Presenter

State management component that:

• Handles field state (value, error, description)
• Manages validation logic and error states
• Provides reactive updates through signals
• Supports custom validation functions

Field Set

Grouping component that:

• Creates logical sections within forms
• Provides legends and optional adornments
• Maintains consistent spacing between fields
• Supports accessibility features

Design System Integration

All components automatically integrate with:

• Spacing Scale: Consistent margins, padding, and gaps
• Color System: Primary, secondary, and accent color schemes
• Typography: Font sizes and weights that match your design
• Scalar Support: Automatic scaling for different screen densities
• Theme Support: Light and dark theme compatibility

Accessibility Features

• ARIA Attributes: Proper labeling and state management
• Screen Reader Support: Semantic markup and descriptions
• Focus Management: Clear focus indicators and focus trapping
• Keyboard Navigation: Full keyboard support for all interactions
• High Contrast: Designed for various visual accessibility needs

When to Use

Choose @tcn/ui-forms when you need:

• Consistent form layouts across your application
• Built-in form validation and error handling
• Responsive form designs that adapt to different screen sizes
• Accessible form components with proper ARIA support
• Form state management integrated with your design system

Customization

Components support extensive customization through:

• CSS Custom Properties: Dynamic styling changes
• CSS Modules: Scoped styling with design system integration
• Props Interface: Flexible configuration through component props
• Theme Integration: Automatic adaptation to different themes
• Layout Options: Flexible arrangement and spacing controls

Performance

• Efficient Rendering: Minimal re-renders and optimized updates
• Bundle Optimization: Tree-shakeable components for smaller bundles
• Memory Management: Proper cleanup and event handling
• Lazy Loading: Support for on-demand component loading

License

Apache-2.0