FRD-028: Form Layout Components

Field	Value
Owner	David Holmes
Status	Shipped
Last Updated	2026-05-26
Target Release	v2.0.0
Type	Widget
Size	M
Priority	P1 — Component Improvement

---

Document Summary

Introduce FormSection, FieldErrorSummary, and InlineEdit components to address form layout and editing patterns missing from the design system. FormSection provides semantic grouping with optional collapsibility. FieldErrorSummary aggregates validation errors with scroll-to-first-error behavior. InlineEdit enables click-to-edit patterns for read-heavy UIs. All integrate with React Hook Form and Zod.

---

Introduction

Overview

The design system provides field-group.tsx (FieldGroup) for grouping label + input + message, but lacks higher-level form layout primitives. Teams building multi-section forms (settings pages, profile editors, onboarding wizards) duplicate section heading/description/divider patterns. Error summaries that scroll to the first invalid field are hand-built per project. Inline edit patterns (click a value to edit it in place) have no standard implementation.

Goals

• Provide FormSection for visually and semantically grouping related form fields with heading, description, and optional collapse.
• Provide FieldErrorSummary that renders a list of validation errors with click-to-scroll-to-field behavior.
• Provide InlineEdit for toggling between a read-only display and an editable input, with save/cancel actions.
• Demonstrate RHF + Zod integration patterns for all three in Storybook docs.

Non-Goals

• Full form wizard (multi-step with routing) — PanelWizard exists for that.
• Form state management library — RHF is the recommended solution.
• Server-side form actions or progressive enhancement.

---

Scope

In Scope

Item	Description
FormSection	Semantic <fieldset>-based section with heading, description, optional collapse, divider control.
FieldErrorSummary	Error list component that accepts RHF errors object; each error is a clickable link scrolling to the field.
InlineEdit	Read-view / edit-view toggle with save/cancel buttons; supports TextField, Select, and TextArea as edit controls.
RHF + Zod examples	Storybook recipes showing form validation with these components.
Stories and tests	Full Storybook coverage; unit tests for scroll behavior, collapse, and edit toggling.

Out of Scope

Item	Reason
Multi-step wizard	Covered by PanelWizard.
Form auto-save	Consumer-level concern; InlineEdit supports onSave callback.
Drag-to-reorder form fields	Niche requirement; not a layout primitive.

---

Users and Pain Points

User	Pain Point
Settings page developers	Recreate section heading + description + divider layout for every settings group.
Form-heavy application teams	No standard error summary; users must scroll to find invalid fields.
Admin dashboard developers	Inline editing of table cells or profile fields requires custom toggle logic per field.
Accessibility-focused teams	Error summaries without programmatic focus management fail screen reader users.

---

Definitions

Term	Definition
FormSection	A visually distinct group of related form fields, rendered as a <fieldset> with a <legend>.
FieldErrorSummary	A banner-like component listing all current form errors with links to the corresponding fields.
InlineEdit	A pattern where a value is displayed as read-only text; clicking it transitions to an editable input.
Scroll-to-error	Programmatically scrolling the viewport and focusing the first invalid field in a form.

---

Current State

• FieldGroup (src/components/ui/field-group.tsx): Groups a label, input, hint, and error message for a single field. Does not handle multi-field sections.
• FieldMessage: Renders error/success/hint messages with icons. Used within FieldGroup.
• No FormSection, FieldErrorSummary, or InlineEdit exists.
• RHF is used in consumer applications but the design system has no integration layer or error aggregation utilities.

---

Proposed Solution

FormSection

src/components/ui/form-section.tsx — Renders a <fieldset> with a styled <legend> (heading), optional description paragraph, and optional collapsible behavior (using the existing Collapsible primitive or a simple details/summary pattern). A divider prop controls whether a top border separates it from the previous section.

FieldErrorSummary

src/components/ui/field-error-summary.tsx — Accepts an errors object (compatible with RHF formState.errors) and an optional fieldLabels map (Record<string, string>) for human-readable field names. Renders an alert-styled card with a list of errors. Each error is a button that calls document.getElementById(fieldId)?.scrollIntoView({ behavior: "smooth" }) and then focuses the element. The component uses role="alert" and aria-live="assertive" for screen reader announcement.

InlineEdit

src/components/ui/inline-edit.tsx — A compound component with two states: read mode (renders the value as styled text with a pencil icon) and edit mode (renders the appropriate form control with save/cancel buttons). Props include value, onSave, onCancel, editControl (a render prop receiving { value, onChange }), and readView (optional custom read display). Pressing Escape cancels; Enter in a single-line input saves.

---

Requirements

Requirement Priorities

• Must Have: FormSection, FieldErrorSummary with scroll-to-error, InlineEdit with save/cancel.
• Should Have: FormSection collapsible mode, FieldErrorSummary field label mapping, InlineEdit keyboard shortcuts.
• Could Have: FormSection animated collapse, FieldErrorSummary auto-scroll-on-submit helper, InlineEdit optimistic save.

---

Functional Requirements

ID	Requirement	Priority
FR-01	FormSection renders a <fieldset> with <legend> heading and optional description.	Must
FR-02	FormSection collapsible prop enables expand/collapse with arrow indicator.	Should
FR-03	FormSection divider prop renders a top border when true (default true for non-first sections).	Must
FR-04	FieldErrorSummary accepts errors (RHF-compatible) and renders a clickable error list.	Must
FR-05	FieldErrorSummary clicking an error scrolls to and focuses the corresponding field.	Must
FR-06	FieldErrorSummary uses fieldLabels map to display human-readable field names.	Should
FR-07	FieldErrorSummary auto-focuses itself on mount (for submit-triggered rendering).	Should
FR-08	InlineEdit toggles between read mode and edit mode on click or Enter key.	Must
FR-09	InlineEdit save button triggers onSave callback; cancel restores original value.	Must
FR-10	InlineEdit Escape key cancels; Enter key saves (in single-line inputs).	Should
FR-11	InlineEdit shows loading state during async onSave.	Could

---

Non-Functional Requirements

ID	Requirement	Target
NFR-01	FormSection render time	< 5ms for a section with 10 fields.
NFR-02	FieldErrorSummary scroll-to-field latency	< 100ms from click to field focus.
NFR-03	InlineEdit mode toggle	< 16ms perceived transition.
NFR-04	Bundle size	< 3 KB gzipped per component.
NFR-05	Dark mode	Full token-based dark mode support.

---

API/Interface Requirements

FormSection

interface FormSectionProps {
  heading: string;
  description?: string;
  collapsible?: boolean;
  defaultCollapsed?: boolean;
  divider?: boolean;             // default true
  children: ReactNode;
  className?: string;
}

FieldErrorSummary

interface FieldErrorSummaryProps {
  errors: Record<string, { message?: string }>;
  fieldLabels?: Record<string, string>;
  title?: string;                // default "Please fix the following errors"
  autoFocus?: boolean;           // default true
  className?: string;
}

InlineEdit

interface InlineEditProps<T = string> {
  value: T;
  onSave: (value: T) => void | Promise<void>;
  onCancel?: () => void;
  editControl: (props: { value: T; onChange: (value: T) => void }) => ReactNode;
  readView?: (value: T) => ReactNode;
  saveLabel?: string;            // default "Save"
  cancelLabel?: string;          // default "Cancel"
  editLabel?: string;            // default "Edit"
  disabled?: boolean;
  className?: string;
}

---

Accessibility Requirements

ID	Requirement
A11Y-01	FormSection uses <fieldset> and <legend> for semantic grouping; collapse toggle has aria-expanded.
A11Y-02	FieldErrorSummary uses role="alert" and receives focus on mount for screen reader announcement.
A11Y-03	FieldErrorSummary error links use role="link" or native <a> with href="#fieldId" for navigation.
A11Y-04	InlineEdit read mode has role="button" or uses a <button> element; edit label is announced.
A11Y-05	InlineEdit edit mode traps focus within the edit region; cancel/save are keyboard accessible.
A11Y-06	All components pass axe-core automated checks with zero violations.

---

Content and Documentation Requirements

ID	Requirement
DOC-01	Storybook docs page for each component with usage guidelines, do/don’t, and prop tables.
DOC-02	RHF + Zod integration recipe showing FormSection grouping, FieldErrorSummary wired to formState.errors, and InlineEdit within a form.
DOC-03	Composition guide showing FormSection + FieldGroup + FieldErrorSummary working together in a settings page.

---

Dependencies

Dependency	Type	Risk
src/components/ui/field-group.tsx	Internal	Low — FormSection wraps multiple FieldGroups.
src/components/ui/text-field.tsx	Internal	Low — InlineEdit default edit control.
src/components/ui/button.tsx	Internal	Low — Save/cancel actions.
react-hook-form	Peer	Low — Error object shape is standard; no hard dependency.
src/styles/motion.css	Internal	Low — Collapse animation tokens.

---

Risks and Tradeoffs

Risk	Likelihood	Impact	Mitigation
FieldErrorSummary scroll-to-field fails if field IDs don’t match	Medium	Medium	Document ID convention; provide a fieldIdPrefix prop for namespaced forms.
FormSection collapsible state hides required fields from validation	Low	High	Expand collapsed sections containing errors when FieldErrorSummary is rendered.
InlineEdit save/cancel buttons conflict with table row click handlers	Medium	Medium	Stop propagation on InlineEdit button clicks; document this behavior.

---

Open Questions

#	Question	Owner	Status
OQ-01	Should FormSection support a required indicator showing that the section contains required fields?	David Holmes	Open
OQ-02	Should FieldErrorSummary auto-expand collapsed FormSections containing errors?	David Holmes	Open
OQ-03	Should InlineEdit support multi-field editing (e.g., first name + last name as a single inline edit)?	David Holmes	Open

---

Acceptance Criteria

#	Criterion
AC-01	FormSection renders a semantic <fieldset> with heading and optional description; collapsible mode works.
AC-02	FieldErrorSummary renders validation errors as clickable links that scroll to and focus the corresponding field.
AC-03	FieldErrorSummary receives focus on mount and announces errors to screen readers.
AC-04	InlineEdit toggles between read and edit modes; save and cancel work via buttons and keyboard shortcuts.
AC-05	All components render correctly in dark mode.
AC-06	All components pass axe-core checks with zero violations.
AC-07	Storybook stories exist with controls for all props.
AC-08	pnpm typecheck and pnpm vitest run --project unit pass with zero errors.

---

LLM Handoff Instructions

When implementing this FRD:

1. Start with FormSection — src/components/ui/form-section.tsx. Use <fieldset> and <legend>. For collapsible, use a simple useState with height animation via motion tokens. Follow the existing FieldGroup naming and file conventions.
2. Then FieldErrorSummary — src/components/ui/field-error-summary.tsx. Accept an errors object matching RHF’s formState.errors shape (Record<string, { message?: string }>). Use scrollIntoView + focus() for navigation. Render in an alert card using StatusCard or a styled div with role="alert".
3. Then InlineEdit — src/components/ui/inline-edit.tsx. Use a generic type parameter <T> for the value. Default readView renders the value as text in a button-like container. The editControl render prop gives consumers full control over the edit UI.
4. Stories in sibling .stories.tsx files. Include a “Full Settings Page” story composing all three.
5. Tests in sibling .test.tsx files. Test scroll-to-error with mocked scrollIntoView, collapse toggle, and InlineEdit mode switching.

Key files to reference:

• src/components/ui/field-group.tsx — existing field grouping pattern.
• src/components/ui/text-field.tsx — default InlineEdit edit control.
• src/components/ui/button.tsx — save/cancel buttons.
• src/components/ui/status-card.tsx — potential base for error summary card.

---

Decision Log

Date	Decision	Rationale
2026-05-26	FormSection uses native <fieldset>/<legend> rather than div + heading.	Semantic HTML provides free accessibility; styled <legend> is achievable with CSS.
2026-05-26	FieldErrorSummary accepts RHF error shape but has no hard dependency on RHF.	Any object matching Record<string, { message?: string }> works; keeps the component framework-agnostic.
2026-05-26	InlineEdit uses a render prop for the edit control rather than a fixed set of input types.	Maximum flexibility; consumers can use TextField, Select, TextArea, or custom inputs.

---

Document History

Version	Date	Author	Changes
0.1	2026-05-26	David Holmes	Initial draft.