Skip to content

Pending Review

Pending Review from User Experience (UX)

Form Section Component

Overview

The PWC Form Section component provides structured organization for form fields with consistent grouping, headings, and layout patterns. Built with Lit web components, it serves as a container that automatically renders various form input types while maintaining design system consistency and accessibility standards.

Core Capabilities

  • Form Field Organization - Logical grouping of related form inputs with consistent spacing and visual hierarchy
  • Universal Input Rendering - Automatic rendering of all form input types including text inputs, selects, checkboxes, and complex components
  • Heading and Hint Support - Optional section headings and descriptive hints to guide users through form completion
  • Visual Separation - Configurable divider borders to create clear visual separation between different form sections
  • Flexible Layout - Responsive column layout with consistent gap spacing that adapts to container width
  • Accessibility Integration - Proper semantic structure with headings and descriptions for screen reader navigation

When to use Form Section:

  • Multi-part forms requiring logical organization of related fields into distinct sections
  • Complex forms with different categories of information that benefit from visual and semantic grouping
  • Settings interfaces with multiple configuration areas that need clear separation and organization
  • Registration and profile forms with personal, contact, and preference sections

When not to use Form Section:

  • Simple forms with just a few fields where sectioning adds unnecessary complexity
  • Single-purpose forms where all fields relate to the same concept and don't need grouping
  • Forms where custom layout requirements conflict with the standard section structure

Basic Implementation

import { PwcFormSection, PwcInput } from "@progress-i360/pwc-react";

function MyComponent() {
  return (
    <>
      <PwcFormSection 
        heading="Personal Information" 
        hint="Enter your basic contact details">
        <PwcInput name="firstName" label="First Name" required />
        <PwcInput name="lastName" label="Last Name" required />
      </PwcFormSection>

      <PwcFormSection 
        heading="Address" 
        hint="Provide your mailing address" 
        divider>
        <PwcInput name="street" label="Street Address" />
        <PwcInput name="city" label="City" />
      </PwcFormSection>
    </>
  );
}

import { useEffect, useRef, useState } from 'react';
import '@progress-i360/progress-web-components/checkbox';
import '@progress-i360/progress-web-components/form-section';
import '@progress-i360/progress-web-components/input';
import '@progress-i360/progress-web-components/password';
import '@progress-i360/progress-web-components/switch';

type InputElement = HTMLElement & { value?: string };
type ToggleElement = HTMLElement & { checked?: boolean };

function AccountSections() {
  const usernameRef = useRef<InputElement | null>(null);
  const passwordRef = useRef<InputElement | null>(null);
  const newsletterRef = useRef<ToggleElement | null>(null);
  const notificationsRef = useRef<ToggleElement | null>(null);

  const [state, setState] = useState({
    username: 'j.smith',
    newsletter: true,
    notifications: false,
    password: ''
  });

  useEffect(() => {
    const usernameEl = usernameRef.current;
    const passwordEl = passwordRef.current;
    const newsletterEl = newsletterRef.current;
    const notificationsEl = notificationsRef.current;

    if (!usernameEl || !passwordEl || !newsletterEl || !notificationsEl) {
      return;
    }

    const handleUsername = (event: Event) => {
      const detail = (event as CustomEvent<string>).detail;
      setState((prev) => ({ ...prev, username: detail }));
    };

    const handlePassword = (event: Event) => {
      const detail = (event as CustomEvent<string>).detail;
      setState((prev) => ({ ...prev, password: detail }));
    };

    const handleNewsletter = (event: Event) => {
      const detail = (event as CustomEvent<boolean>).detail;
      setState((prev) => ({ ...prev, newsletter: detail }));
    };

    const handleNotifications = (event: Event) => {
      const detail = (event as CustomEvent<boolean>).detail;
      setState((prev) => ({ ...prev, notifications: detail }));
    };

    usernameEl.addEventListener('pwc-input', handleUsername);
    passwordEl.addEventListener('pwc-change', handlePassword);
    newsletterEl.addEventListener('pwc-change', handleNewsletter);
    notificationsEl.addEventListener('pwc-change', handleNotifications);

    return () => {
      usernameEl.removeEventListener('pwc-input', handleUsername);
      passwordEl.removeEventListener('pwc-change', handlePassword);
      newsletterEl.removeEventListener('pwc-change', handleNewsletter);
      notificationsEl.removeEventListener('pwc-change', handleNotifications);
    };
  }, []);

  useEffect(() => {
    if (usernameRef.current) {
      usernameRef.current.value = state.username;
    }
    if (passwordRef.current) {
      passwordRef.current.value = state.password;
    }
    if (newsletterRef.current) {
      newsletterRef.current.checked = state.newsletter;
    }
    if (notificationsRef.current) {
      notificationsRef.current.checked = state.notifications;
    }
  }, [state]);

  return (
    <>
      <pwc-form-section heading="Account Setup">
        <pwc-input
          ref={usernameRef}
          name="username"
          label="Username"
          required
        ></pwc-input>
        <pwc-password
          ref={passwordRef}
          name="password"
          label="Password"
          required
        ></pwc-password>
      </pwc-form-section>

      <pwc-form-section
        heading="Preferences"
        hint="Customize your experience"
        divider
      >
        <pwc-checkbox
          ref={newsletterRef}
          name="newsletter"
          label="Subscribe to newsletter"
        ></pwc-checkbox>
        <pwc-switch
          ref={notificationsRef}
          name="notifications"
          label="Enable notifications"
        ></pwc-switch>
      </pwc-form-section>
    </>
  );
}

import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import "@progress-i360/progress-web-components/checkbox";
import "@progress-i360/progress-web-components/form-section";
import "@progress-i360/progress-web-components/input";
import "@progress-i360/progress-web-components/switch";

@Component({
  selector: 'form-section-demo',
  template: `
    <pwc-form-section heading="User Information" hint="Please provide your contact details" [divider]="showDivider">
      <pwc-input name="firstName" label="First Name" required (pwc-change)="updateField('firstName', $event)"></pwc-input>
      <pwc-input name="email" label="Email" type="email" (pwc-change)="updateField('email', $event)"></pwc-input>
      <pwc-checkbox name="newsletter" label="Subscribe to newsletter" (pwc-change)="updatePreference($event)"></pwc-checkbox>
    </pwc-form-section>

    <pwc-form-section heading="Preferences" divider="true">
      <pwc-switch name="notifications" label="Email notifications" (pwc-change)="toggleNotifications($event)"></pwc-switch>
    </pwc-form-section>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class FormSectionDemo {
  showDivider = false;
  formData = { firstName: '', email: '' };

  updateField(field: string, event: any) {
    this.formData[field as keyof typeof this.formData] = event.detail;
    this.showDivider = Object.values(this.formData).some(value => value);
  }

  updatePreference(event: any) {
    console.log('Newsletter preference:', event.detail);
  }

  toggleNotifications(event: any) {
    console.log('Notifications enabled:', event.detail);
  }
}

import '@progress-i360/progress-web-components/form-section';
import '@progress-i360/progress-web-components/input';

const section = document.createElement('pwc-form-section');
section.setAttribute('heading', 'Contact Information');
section.setAttribute('hint', 'Please provide your details');
section.setAttribute('divider', 'true');

const input = document.createElement('pwc-input');
input.setAttribute('label', 'Email');
input.setAttribute('name', 'email');
section.appendChild(input);

document.body.appendChild(section);

Usage Patterns

  • Logical Information Grouping - Organize related form fields into sections like personal info, contact details, preferences, and security settings
  • Progressive Form Structure - Create multi-step form experiences with clear section progression from basic to advanced information
  • Settings Organization - Structure configuration interfaces with sections for different feature areas and user preferences
  • Conditional Section Display - Show or hide entire form sections based on user selections or permissions using dividers for visual separation

Best Practices

Content Strategy Guidelines

  • Descriptive Section Headings - Use clear, specific headings that help users understand what information each section requires
  • Helpful Section Hints - Provide context through hint text that explains why information is needed or how it will be used
  • Logical Field Ordering - Arrange fields within sections in a natural, intuitive order that matches user mental models
  • Consistent Section Structure - Use similar patterns across sections for field types, labels, and required field indicators

Performance Optimization

  • Efficient Field Rendering - Leverage the renderFormInput function to efficiently render various field types without manual switching
  • Conditional Section Loading - Only render sections that are relevant to the current user context or form state
  • State Management Optimization - Group related form state updates to minimize re-renders across section boundaries
  • Memory Management - Properly dispose of form field subscriptions when sections are removed or hidden

Integration Architecture

  • Form Context Integration - Ensure all section fields properly integrate with parent form validation and submission handling
  • Accessibility Standards - Use proper heading hierarchy and semantic structure for screen reader navigation
  • Design System Consistency - Apply consistent spacing, typography, and color tokens across all section content
  • Responsive Layout - Ensure sections adapt appropriately to different screen sizes while maintaining usability

Common Use Cases

User Profile Management

  • Personal information sections with name, contact details, and demographic information
  • Account security sections with password management, two-factor authentication, and recovery options
  • Privacy preference sections with visibility settings, communication preferences, and data sharing controls

Business Configuration

  • Company information sections with business details, contact information, and organizational structure
  • Integration settings sections with API configurations, third-party service connections, and webhook setup
  • Billing and subscription sections with payment methods, plan selection, and usage tracking

Application Settings

  • User interface sections with theme selection, language preferences, and display customization
  • Notification sections with email, SMS, and in-app notification preferences organized by category
  • Feature configuration sections with module enablement, permission settings, and advanced options

Troubleshooting

Common Issues

Actions Not Triggering

Symptoms: Form fields within sections don't respond to user input or validation events

Solutions:

  • Verify form field components are properly imported and registered in the renderFormInput function

  • Check that form context is properly provided and consumed by fields within sections

  • Ensure field names are unique across all sections to prevent data binding conflicts

Actions Not Visible

Symptoms: Form sections don't render or appear empty despite having child fields defined

Solutions:

  • Confirm children array is populated with valid FormInputProps objects

  • Check that form input types match the supported types in the renderFormInput switch statement

  • Verify section heading and hint properties are properly bound when provided

Layout Issues

Symptoms: Form sections appear with incorrect spacing, alignment, or divider placement

Solutions:

  • Use divider property appropriately to create visual separation between sections

  • Check parent form container width and layout properties affecting section rendering

  • Ensure consistent gap and padding values are applied across all form sections

Icon Problems

Symptoms: Section headings, field icons, or validation indicators don't display correctly within sections

Solutions:

  • Verify design system tokens are loaded for proper typography and icon rendering

  • Check that form field icons are properly configured within section field definitions

  • Ensure heading size and color tokens are applied correctly for section headers

Implementation Support

  • Form Architecture - Guidance for structuring complex forms with multiple sections and conditional field display
  • Field Integration - Best practices for integrating various form field types within section containers
  • Accessibility Compliance - WCAG implementation for section headings, field grouping, and navigation structure

Resources

Storybook Documentation

For comprehensive API documentation, interactive examples, and testing tools: 📖 View Complete API Documentation in Storybook →

This guide provides high-level implementation guidance. For detailed API specifications and interactive examples, visit our Storybook documentation.