@ticatec/uniface-flexi-module 0.0.2

package/FLEXIFORM_GUIDE.md

@@ -0,0 +1,1068 @@
+# FlexiForm Complete Usage Guide
+
+A comprehensive guide to using FlexiForm for building dynamic, flexible forms in Svelte applications.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Basic Usage](#basic-usage)
+3. [Schema Structure](#schema-structure)
+4. [Field Types](#field-types)
+5. [Layout and Arrangement](#layout-and-arrangement)
+6. [Dynamic Form Generation](#dynamic-form-generation)
+7. [Events and Interactions](#events-and-interactions)
+8. [Extending FlexiForm](#extending-flexiform)
+9. [Advanced Patterns](#advanced-patterns)
+10. [Best Practices](#best-practices)
+
+## Overview
+
+FlexiForm is a powerful form framework that generates dynamic forms from JSON schemas. It supports multiple layout modes, various field types, and provides extensible architecture for custom components.
+
+### Key Features
+
+- **Dynamic Schema-Based**: Generate forms from JSON configurations
+- **Flexible Layouts**: Support for flex and grid layouts
+- **Extensible Field Types**: Built-in fields + custom field support
+- **Event System**: Rich event handling for form interactions
+- **Type Safety**: Full TypeScript support
+- **Modular Architecture**: Plug-and-play components
+
+## Basic Usage
+
+### 1. Installation and Setup
+
+```typescript
+import { FlexiFormPage, registerFormFieldBuilder } from '@ticatec/uniface-flexi-form/flexi-form';
+import '@ticatec/uniface-flexi-form/uniface-flexi-form.css';
+
+// Register all field builders (required)
+registerFormFieldBuilder();
+```
+
+### 2. Simple Form Example
+
+```svelte
+<!-- SimpleForm.svelte -->
+<script lang="ts">
+  import { FlexiFormPage } from '@ticatec/uniface-flexi-form/flexi-form';
+  
+  // Form data
+  let userData = {
+    name: '',
+    email: '',
+    age: null,
+    birthDate: null
+  };
+  
+  // Form schema
+  const userFormSchema = {
+    mode: 'flex',
+    arrangement: 'vertical',
+    variant: 'outlined',
+    elements: {
+      'user-info': {
+        title: 'User Information',
+        fields: [
+          {
+            type: 'text-editor',
+            keyField: 'name',
+            name: 'name',
+            label: 'Full Name',
+            required: true,
+            props: {
+              placeholder: 'Enter your full name'
+            }
+          },
+          {
+            type: 'text-editor',
+            keyField: 'email',
+            name: 'email',
+            label: 'Email Address',
+            required: true,
+            props: {
+              type: 'email',
+              placeholder: 'Enter your email'
+            }
+          },
+          {
+            type: 'number-editor',
+            keyField: 'age',
+            name: 'age',
+            label: 'Age',
+            props: {
+              min: 0,
+              max: 120
+            }
+          },
+          {
+            type: 'date-picker',
+            keyField: 'birthDate',
+            name: 'birthDate',
+            label: 'Birth Date'
+          }
+        ]
+      }
+    }
+  };
+  
+  function handleFormChange(event) {
+    console.log('Form data changed:', event.detail);
+  }
+  
+  function handleSubmit() {
+    console.log('Submitting form:', userData);
+  }
+</script>
+
+<FlexiFormPage 
+  schema={userFormSchema}
+  bind:data={userData}
+  on:change={handleFormChange}
+/>
+
+<button on:click={handleSubmit}>Submit</button>
+```
+
+## Schema Structure
+
+### FlexiFormSchema
+
+```typescript
+interface FlexiFormSchema {
+  mode?: 'flex' | 'grid';           // Layout mode
+  arrangement?: 'vertical' | 'horizontal'; // Layout direction
+  props?: any;                      // Layout-specific properties
+  elements: FormElements;           // Form cards/sections
+  label$style?: string;             // Label styling
+  variant?: 'filled' | 'outlined' | ''; // Field variant
+  actions?: Array<FormActionSchema>; // Form actions
+  style?: string;                   // Custom CSS
+}
+
+type FormElements = {
+  [cardKey: string]: FlexiCardSchema | FlexiBlockSchema;
+}
+```
+
+### FlexiCardSchema
+
+```typescript
+interface FlexiCardSchema {
+  title?: string;                   // Card title
+  mode?: 'flex' | 'grid';          // Card layout mode
+  props?: any;                      // Layout properties
+  arrangement?: 'vertical' | 'horizontal'; // Layout direction
+  fields: Array<FlexiFieldSchema>; // Fields in this card
+  readonly?: boolean;               // Make card readonly
+  disabled?: boolean;               // Disable card
+  variant?: 'filled' | 'outlined' | ''; // Field variant
+  foldable?: boolean;               // Allow collapsing
+  actions?: Array<ActionSchema>;    // Card actions
+}
+```
+
+### FlexiCompositeSchema
+
+```typescript
+interface FlexiCompositeSchema {
+  type?: 'block';                   // Type identifier for blocks
+  title?: string;                   // Block title
+  fields: Array<FlexiFieldSchema>; // Fields in this composite block
+  readonly?: boolean;               // Make block readonly
+  disabled?: boolean;               // Disable block
+  label$style?: string;             // Label styling
+  variant?: string;                 // Field variant
+  mode?: LayoutMode;                // Layout mode
+  props?: any;                      // Layout properties
+  arrangement?: Arrangement;        // Layout direction
+}
+```
+
+### FlexiCompositeFieldSchema
+
+```typescript
+interface FlexiCompositeFieldSchema {
+  type: "composite";                // Type identifier
+  keyField?: string;                // Data binding path for nested object
+  name: string;                     // Field name
+  composite: string;                // Reference to composite schema name
+  cell?: any;                       // Cell properties
+}
+```
+
+### FlexiFieldSchema
+
+```typescript
+interface FlexiFieldSchema {
+  type: string;                     // Field type identifier
+  keyField: string;                 // Data binding path
+  name: string;                     // Field name
+  label: string;                    // Display label
+  dictName?: string;                // Dictionary for options
+  variant?: 'filled' | 'outlined' | ''; // Field variant
+  readonly?: boolean;               // Field readonly state
+  disabled?: boolean;               // Field disabled state
+  required?: boolean;               // Field required state
+  events?: Record<string, string>;  // Event handlers
+  cell?: any;                       // Cell properties
+  props?: any;                      // Field-specific properties
+}
+```
+
+## Field Types
+
+### Built-in Field Types
+
+| Type | Description | Common Props |
+|------|-------------|--------------|
+| `text-editor` | Single-line text input | `placeholder`, `maxLength`, `pattern` |
+| `memo-editor` | Multi-line text area | `rows`, `placeholder`, `maxLength` |
+| `number-editor` | Numeric input | `min`, `max`, `step`, `precision` |
+| `unit-number-editor` | Number input with units | `min`, `max`, `step`, `unit`, `precision` |
+| `date-picker` | Date selection | `min`, `max`, `format` |
+| `datetime-picker` | Date and time selection | `min`, `max`, `format` |
+| `options-selector` | Single select dropdown | `dictName`, `placeholder` |
+| `options-multi-selector` | Multi-select dropdown | `dictName`, `maxSelections` |
+| `cascade-options-selector` | Cascading select | `dictName`, `levels` |
+| `input-options-selector` | Searchable select | `getOptions`, `minLength` |
+| `-` | Break line/separator | Visual separator |
+
+### Field Examples
+
+```typescript
+// Text field with validation
+{
+  type: 'text-editor',
+  keyField: 'username',
+  name: 'username',
+  label: 'Username',
+  required: true,
+  props: {
+    placeholder: 'Enter username',
+    maxLength: 50,
+    pattern: '^[a-zA-Z0-9_]+$'
+  }
+}
+
+// Number field with range
+{
+  type: 'number-editor',
+  keyField: 'price',
+  name: 'price',
+  label: 'Price',
+  props: {
+    min: 0,
+    max: 9999.99,
+    step: 0.01,
+    prefix: '$'
+  }
+}
+
+// Date field with constraints
+{
+  type: 'date-picker',
+  keyField: 'startDate',
+  name: 'startDate',
+  label: 'Start Date',
+  props: {
+    min: '2024-01-01',
+    max: '2024-12-31',
+    format: 'YYYY-MM-DD'
+  }
+}
+
+// Select field with dictionary
+{
+  type: 'options-selector',
+  keyField: 'category',
+  name: 'category',
+  label: 'Category',
+  dictName: 'product-categories',
+  required: true,
+  props: {
+    placeholder: 'Select a category'
+  }
+}
+```
+
+## Layout and Arrangement
+
+### Flex Layout
+
+```typescript
+const flexFormSchema = {
+  mode: 'flex',
+  arrangement: 'vertical',
+  elements: {
+    'main-card': {
+      mode: 'flex',
+      arrangement: 'horizontal', // Fields side by side
+      fields: [
+        {
+          type: 'text-editor',
+          keyField: 'firstName',
+          name: 'firstName',
+          label: 'First Name',
+          cell: { flex: 1 } // Equal width
+        },
+        {
+          type: 'text-editor',
+          keyField: 'lastName',
+          name: 'lastName',
+          label: 'Last Name',
+          cell: { flex: 1 } // Equal width
+        }
+      ]
+    }
+  }
+};
+```
+
+### Grid Layout
+
+```typescript
+const gridFormSchema = {
+  mode: 'grid',
+  props: {
+    columns: 3, // 3-column grid
+    gap: '16px'
+  },
+  elements: {
+    'contact-info': {
+      mode: 'grid',
+      props: {
+        columns: 2 // 2-column grid for this card
+      },
+      fields: [
+        {
+          type: 'text-editor',
+          keyField: 'email',
+          name: 'email',
+          label: 'Email',
+          cell: { colspan: 2 } // Span 2 columns
+        },
+        {
+          type: 'text-editor',
+          keyField: 'phone',
+          name: 'phone',
+          label: 'Phone'
+        },
+        {
+          type: 'text-editor',
+          keyField: 'mobile',
+          name: 'mobile',
+          label: 'Mobile'
+        }
+      ]
+    }
+  }
+};
+```
+
+## Dynamic Form Generation
+
+### Loading Schema from API
+
+```typescript
+class DynamicFormLoader {
+  async loadFormSchema(formId: string): Promise<FlexiFormSchema> {
+    const response = await fetch(`/api/forms/${formId}/schema`);
+    return await response.json();
+  }
+  
+  async loadFormData(formId: string, recordId?: string): Promise<any> {
+    const url = recordId 
+      ? `/api/forms/${formId}/data/${recordId}`
+      : `/api/forms/${formId}/data/new`;
+    const response = await fetch(url);
+    return await response.json();
+  }
+}
+
+// Usage in component
+const loader = new DynamicFormLoader();
+let formSchema = null;
+let formData = {};
+
+onMount(async () => {
+  formSchema = await loader.loadFormSchema('user-profile');
+  formData = await loader.loadFormData('user-profile', userId);
+});
+```
+
+### Schema Builder Pattern
+
+```typescript
+class FormSchemaBuilder {
+  private schema: FlexiFormSchema;
+  
+  constructor() {
+    this.schema = {
+      mode: 'flex',
+      arrangement: 'vertical',
+      variant: 'outlined',
+      elements: {}
+    };
+  }
+  
+  addCard(key: string, title?: string): CardBuilder {
+    const cardBuilder = new CardBuilder(title);
+    this.schema.elements[key] = cardBuilder.getSchema();
+    return cardBuilder;
+  }
+  
+  setLayout(mode: 'flex' | 'grid', arrangement?: 'vertical' | 'horizontal') {
+    this.schema.mode = mode;
+    this.schema.arrangement = arrangement;
+    return this;
+  }
+  
+  build(): FlexiFormSchema {
+    return this.schema;
+  }
+}
+
+class CardBuilder {
+  private card: FlexiCardSchema;
+  
+  constructor(title?: string) {
+    this.card = {
+      title,
+      fields: []
+    };
+  }
+  
+  addTextField(keyField: string, label: string, options: any = {}) {
+    this.card.fields.push({
+      type: 'text-editor',
+      keyField,
+      name: keyField,
+      label,
+      ...options
+    });
+    return this;
+  }
+  
+  addSelectField(keyField: string, label: string, dictName: string, options: any = {}) {
+    this.card.fields.push({
+      type: 'options-selector',
+      keyField,
+      name: keyField,
+      label,
+      dictName,
+      ...options
+    });
+    return this;
+  }
+  
+  getSchema(): FlexiCardSchema {
+    return this.card;
+  }
+}
+
+// Usage
+const schema = new FormSchemaBuilder()
+  .setLayout('flex', 'vertical')
+  .addCard('personal', 'Personal Information')
+    .addTextField('name', 'Full Name', { required: true })
+    .addTextField('email', 'Email', { required: true })
+    .addSelectField('country', 'Country', 'countries')
+  .build();
+```
+
+## Events and Interactions
+
+### Form-Level Events
+
+```svelte
+<script>
+  function handleFormChange(event) {
+    const { data, field, value } = event.detail;
+    console.log(`Field ${field} changed to:`, value);
+    console.log('Full form data:', data);
+  }
+  
+  function handleFormSubmit(event) {
+    const { data, isValid } = event.detail;
+    if (isValid) {
+      submitForm(data);
+    } else {
+      console.error('Form validation failed');
+    }
+  }
+  
+  function handleFormReset(event) {
+    console.log('Form was reset');
+  }
+</script>
+
+<FlexiFormPage 
+  {schema}
+  bind:data={formData}
+  on:change={handleFormChange}
+  on:submit={handleFormSubmit}
+  on:reset={handleFormReset}
+/>
+```
+
+### Field-Level Events
+
+```typescript
+// In schema definition
+{
+  type: 'text-editor',
+  keyField: 'email',
+  name: 'email',
+  label: 'Email',
+  events: {
+    change: 'onEmailChange',
+    blur: 'onEmailBlur',
+    focus: 'onEmailFocus'
+  }
+}
+
+// In form implementation class
+class UserForm extends FlexiForm {
+  onEmailChange(value: string) {
+    console.log('Email changed:', value);
+    // Trigger email validation
+    this.validateEmail(value);
+  }
+  
+  onEmailBlur(event: FocusEvent) {
+    console.log('Email field lost focus');
+    // Check for duplicate email
+    this.checkEmailUniqueness(event.target.value);
+  }
+  
+  onEmailFocus(event: FocusEvent) {
+    console.log('Email field gained focus');
+  }
+}
+```
+
+## Extending FlexiForm
+
+### Creating Custom Field Types
+
+#### 1. Create Custom Field Component
+
+```svelte
+<!-- CustomRatingField.svelte -->
+<script lang="ts">
+  import type FlexiField from "$lib/flexi-form/flexi_field/FlexiField";
+  
+  export let field: FlexiField;
+  export let readonly: boolean;
+  export let disabled: boolean;
+  export let variant: "" | "outlined" | "filled";
+  
+  $: props = field.props;
+  $: data = field.data;
+  $: events = field.events;
+  
+  const maxRating = props.maxRating || 5;
+  let currentRating = data[field.keyField] || 0;
+  
+  function setRating(rating: number) {
+    if (readonly || disabled) return;
+    currentRating = rating;
+    data[field.keyField] = rating;
+    events.change?.(rating);
+  }
+</script>
+
+<div class="rating-field" class:readonly class:disabled>
+  <label>{field.label}</label>
+  <div class="stars">
+    {#each Array(maxRating) as _, i}
+      <button
+        type="button"
+        class="star"
+        class:filled={i < currentRating}
+        {disabled}
+        on:click={() => setRating(i + 1)}
+      >
+        ⭐
+      </button>
+    {/each}
+  </div>
+</div>
+
+<style>
+  .rating-field {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  
+  .stars {
+    display: flex;
+    gap: 4px;
+  }
+  
+  .star {
+    background: none;
+    border: none;
+    font-size: 24px;
+    cursor: pointer;
+    opacity: 0.3;
+    transition: opacity 0.2s;
+  }
+  
+  .star.filled {
+    opacity: 1;
+  }
+  
+  .star:hover:not(:disabled) {
+    opacity: 0.7;
+  }
+  
+  .readonly .star, .disabled .star {
+    cursor: default;
+  }
+</style>
+```
+
+#### 2. Register Custom Field Type
+
+```typescript
+import { ComponentBuilder } from '@ticatec/uniface-flexi-form/flexi-form/lib/ComponentBuilder';
+import CustomRatingField from './CustomRatingField.svelte';
+
+// Create builder function
+const buildRatingField = (schema: FlexiFieldSchema, dictLoader: DictionaryLoader) => {
+  return {
+    component: CustomRatingField,
+    props: schema.props
+  };
+};
+
+// Register the custom field type
+const componentBuilder = ComponentBuilder.getInstance();
+componentBuilder.register('rating-field', buildRatingField);
+
+// Use in schema
+const schemaWithRating = {
+  mode: 'flex',
+  elements: {
+    'review-card': {
+      title: 'Product Review',
+      fields: [
+        {
+          type: 'rating-field',
+          keyField: 'rating',
+          name: 'rating',
+          label: 'Product Rating',
+          props: {
+            maxRating: 5
+          }
+        },
+        {
+          type: 'memo-editor',
+          keyField: 'comment',
+          name: 'comment',
+          label: 'Review Comment'
+        }
+      ]
+    }
+  }
+};
+```
+
+### Creating Custom Form Classes
+
+```typescript
+import FlexiForm, { type FlexiFormSchema } from '@ticatec/uniface-flexi-form/flexi-form';
+
+class UserProfileForm extends FlexiForm {
+  private userId: string;
+  
+  constructor(userId: string, data: any, schema: FlexiFormSchema) {
+    super(data, schema);
+    this.userId = userId;
+  }
+  
+  protected buildCards(): void {
+    // Custom card building logic
+    for (const [key, element] of Object.entries(this.elements)) {
+      if (element.type === 'block') {
+        // Handle block elements
+      } else {
+        // Create card with custom logic
+        const card = new CustomUserCard(this, element as FlexiCardSchema);
+        this.cards.push(card);
+      }
+    }
+  }
+  
+  getTitle(): string {
+    return `User Profile - ${this.data.name || 'New User'}`;
+  }
+  
+  // Custom methods
+  async saveProfile(): Promise<void> {
+    try {
+      await fetch(`/api/users/${this.userId}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(this.data)
+      });
+      console.log('Profile saved successfully');
+    } catch (error) {
+      console.error('Failed to save profile:', error);
+    }
+  }
+  
+  validateEmail(email: string): boolean {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+  }
+  
+  // Event handlers (called from field events)
+  onEmailChange(value: string): void {
+    if (!this.validateEmail(value)) {
+      console.warn('Invalid email format');
+    }
+  }
+  
+  onPhoneChange(value: string): void {
+    // Format phone number
+    const formatted = this.formatPhoneNumber(value);
+    this.data.phone = formatted;
+    this.invalidate(); // Trigger UI update
+  }
+  
+  private formatPhoneNumber(phone: string): string {
+    const cleaned = phone.replace(/\D/g, '');
+    if (cleaned.length === 10) {
+      return `(${cleaned.slice(0, 3)}) ${cleaned.slice(3, 6)}-${cleaned.slice(6)}`;
+    }
+    return phone;
+  }
+}
+
+// Usage
+const userForm = new UserProfileForm(userId, userData, formSchema);
+await userForm.initialize();
+```
+
+## Advanced Patterns
+
+### Conditional Field Display
+
+```typescript
+class ConditionalFormCard extends FlexiCard {
+  protected createFromSchema(): void {
+    super.createFromSchema();
+    
+    // Add conditional logic
+    this.setupConditionalFields();
+  }
+  
+  private setupConditionalFields(): void {
+    const typeField = this.field['userType'];
+    const companyField = this.field['company'];
+    
+    if (typeField && companyField) {
+      typeField.events.change = (value: string) => {
+        companyField.visibility = value === 'business' 
+          ? Visibility.View 
+          : Visibility.Hidden;
+        this.invalidate();
+      };
+    }
+  }
+}
+```
+
+### Dynamic Field Dependencies
+
+```typescript
+class DependentFieldsHandler {
+  private form: FlexiForm;
+  private dependencies: Map<string, string[]> = new Map();
+  
+  constructor(form: FlexiForm) {
+    this.form = form;
+    this.setupDependencies();
+  }
+  
+  setupDependencies(): void {
+    // Define field dependencies
+    this.dependencies.set('country', ['state', 'city']);
+    this.dependencies.set('state', ['city']);
+    
+    // Setup change handlers
+    for (const [parentField, dependentFields] of this.dependencies) {
+      this.setupFieldHandler(parentField, dependentFields);
+    }
+  }
+  
+  private setupFieldHandler(parentField: string, dependentFields: string[]): void {
+    const field = this.findField(parentField);
+    if (field) {
+      const originalHandler = field.events.change;
+      field.events.change = async (value: any) => {
+        // Call original handler
+        originalHandler?.(value);
+        
+        // Update dependent fields
+        await this.updateDependentFields(parentField, value, dependentFields);
+      };
+    }
+  }
+  
+  private async updateDependentFields(
+    parentField: string, 
+    value: any, 
+    dependentFields: string[]
+  ): Promise<void> {
+    for (const fieldName of dependentFields) {
+      const field = this.findField(fieldName);
+      if (field) {
+        // Clear current value
+        this.form.data[fieldName] = null;
+        
+        // Load new options
+        const options = await this.loadOptions(fieldName, { [parentField]: value });
+        field.props.options = options;
+      }
+    }
+    
+    this.form.invalidate();
+  }
+  
+  private async loadOptions(fieldName: string, context: any): Promise<any[]> {
+    const response = await fetch(`/api/options/${fieldName}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(context)
+    });
+    return await response.json();
+  }
+  
+  private findField(fieldName: string): FlexiField | null {
+    for (const card of this.form.cards) {
+      if (card.field[fieldName]) {
+        return card.field[fieldName];
+      }
+    }
+    return null;
+  }
+}
+```
+
+### Form Wizard Pattern
+
+```typescript
+class WizardFormManager {
+  private steps: FlexiFormSchema[] = [];
+  private currentStep = 0;
+  private stepData: any[] = [];
+  
+  constructor(steps: FlexiFormSchema[]) {
+    this.steps = steps;
+    this.stepData = new Array(steps.length).fill({});
+  }
+  
+  getCurrentSchema(): FlexiFormSchema {
+    return this.steps[this.currentStep];
+  }
+  
+  getCurrentData(): any {
+    return this.stepData[this.currentStep];
+  }
+  
+  nextStep(): boolean {
+    if (this.currentStep < this.steps.length - 1) {
+      this.currentStep++;
+      return true;
+    }
+    return false;
+  }
+  
+  previousStep(): boolean {
+    if (this.currentStep > 0) {
+      this.currentStep--;
+      return true;
+    }
+    return false;
+  }
+  
+  getFinalData(): any {
+    return this.stepData.reduce((acc, stepData) => ({
+      ...acc,
+      ...stepData
+    }), {});
+  }
+  
+  isFirstStep(): boolean {
+    return this.currentStep === 0;
+  }
+  
+  isLastStep(): boolean {
+    return this.currentStep === this.steps.length - 1;
+  }
+  
+  getProgress(): number {
+    return ((this.currentStep + 1) / this.steps.length) * 100;
+  }
+}
+
+// Usage in Svelte component
+let wizardManager = new WizardFormManager([
+  personalInfoSchema,
+  contactInfoSchema,
+  preferencesSchema
+]);
+
+function handleNext() {
+  if (wizardManager.nextStep()) {
+    currentSchema = wizardManager.getCurrentSchema();
+    currentData = wizardManager.getCurrentData();
+  } else {
+    // Submit final form
+    submitWizardData(wizardManager.getFinalData());
+  }
+}
+```
+
+## Best Practices
+
+### 1. Schema Organization
+
+```typescript
+// Good: Organized schema structure
+const FORM_SCHEMAS = {
+  userProfile: {
+    mode: 'flex',
+    arrangement: 'vertical',
+    elements: {
+      personal: USER_PERSONAL_CARD,
+      contact: USER_CONTACT_CARD,
+      preferences: USER_PREFERENCES_CARD
+    }
+  }
+};
+
+const USER_PERSONAL_CARD: FlexiCardSchema = {
+  title: 'Personal Information',
+  fields: [
+    FIELDS.firstName,
+    FIELDS.lastName,
+    FIELDS.birthDate
+  ]
+};
+
+const FIELDS = {
+  firstName: {
+    type: 'text-editor',
+    keyField: 'firstName',
+    name: 'firstName',
+    label: 'First Name',
+    required: true,
+    props: { maxLength: 50 }
+  },
+  // ... more field definitions
+};
+```
+
+### 2. Type Safety
+
+```typescript
+// Define strict types for your schemas
+interface UserFormData {
+  firstName: string;
+  lastName: string;
+  email: string;
+  birthDate: Date;
+  preferences: UserPreferences;
+}
+
+interface UserPreferences {
+  newsletter: boolean;
+  language: string;
+  timezone: string;
+}
+
+// Use typed form creation
+class TypedUserForm extends FlexiForm {
+  protected data: UserFormData;
+  
+  constructor(data: UserFormData, schema: FlexiFormSchema) {
+    super(data, schema);
+  }
+  
+  getData(): UserFormData {
+    return this.data;
+  }
+}
+```
+
+### 3. Error Handling
+
+```typescript
+class FormErrorHandler {
+  static handleFormError(error: any, form: FlexiForm): void {
+    if (error.validationErrors) {
+      this.displayValidationErrors(error.validationErrors, form);
+    } else if (error.networkError) {
+      this.displayNetworkError(error.networkError);
+    } else {
+      this.displayGenericError(error);
+    }
+  }
+  
+  private static displayValidationErrors(
+    errors: Record<string, string>, 
+    form: FlexiForm
+  ): void {
+    for (const [fieldName, errorMessage] of Object.entries(errors)) {
+      const field = this.findFieldInForm(fieldName, form);
+      if (field) {
+        field.error = errorMessage;
+      }
+    }
+    form.invalidate();
+  }
+}
+```
+
+### 4. Performance Optimization
+
+```typescript
+// Lazy load large forms
+class LazyFormLoader {
+  private formCache = new Map<string, FlexiFormSchema>();
+  
+  async loadForm(formId: string): Promise<FlexiFormSchema> {
+    if (this.formCache.has(formId)) {
+      return this.formCache.get(formId)!;
+    }
+    
+    const schema = await fetch(`/api/forms/${formId}`).then(r => r.json());
+    this.formCache.set(formId, schema);
+    return schema;
+  }
+  
+  preloadForms(formIds: string[]): void {
+    formIds.forEach(id => this.loadForm(id));
+  }
+}
+
+// Debounce form changes
+function createDebouncedFormHandler(delay = 300) {
+  let timeoutId: number;
+  
+  return function(handler: Function) {
+    return function(...args: any[]) {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(() => handler(...args), delay);
+    };
+  };
+}
+```
+
+This comprehensive guide provides everything needed to effectively use and extend FlexiForm in your applications. The examples progress from basic usage to advanced patterns, showing how to build sophisticated form systems with FlexiForm's flexible architecture.