mirror of
https://github.com/supabase/supabase.git
synced 2026-10-11 12:25:05 +03:00
Danny White
3a72b128de
## What kind of change does this PR introduce? Design system and validation consistency update. ## What is the current behaviour? `KeyValueFieldArray` already renders per-cell form messages, but each consumer still decides its own validation rules. At the moment, some consumers allow partially filled rows to submit silently, while Log Drains now treats them as inline validation errors. ## What is the new behaviour? This PR standardises the recommended partial-row behaviour for the current `KeyValueFieldArray` consumers by introducing a shared validation helper and using it from each form schema. - adds `getKeyValueFieldArrayValidationIssues` alongside `KeyValueFieldArray` - keeps `KeyValueFieldArray` presentation-only and leaves validation in consumer schemas - shows inline errors when one side of a key/value row is filled and the other is empty - keeps fully empty rows as draft rows - keeps duplicate-key validation in Log Drains, where it already applies - updates the design-system docs and examples to describe the validation pattern explicitly <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added reusable key/value validation utilities and public export; forms now trim header/key/value inputs, show inline errors for partially filled rows, and remove fully empty draft rows on submit. * **Documentation** * Clarified the field-array is rendering-only and added guidance for placing validation in form schemas and handling draft rows. * **Tests** * Added unit and integration tests covering validation rules, duplicate keys, trimming, draft-row stripping, and payload behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
65 lines
3.0 KiB
Plaintext
65 lines
3.0 KiB
Plaintext
---
|
|
title: Forms
|
|
description: Common form patterns used in Studio settings pages and side panels.
|
|
---
|
|
|
|
Forms in Supabase Studio should follow consistent patterns to ensure a cohesive user experience across settings pages and side panels. This guide covers the most common form patterns and field types.
|
|
|
|
## Page Layout
|
|
|
|
Forms in page layouts typically use `PageSection` components with `Card` containers. Fields use `FormItemLayout` with `layout="flex-row-reverse"` for horizontal alignment.
|
|
|
|
<ComponentPreview
|
|
name="form-patterns-pagelayout"
|
|
description="Complete form example with all field types in a PageLayout pattern"
|
|
peekCode
|
|
wide
|
|
/>
|
|
|
|
## Side Panel
|
|
|
|
Forms in side panels (Sheets) use `FormItemLayout` with `layout="horizontal"` on wider panels and `layout="vertical"` on panels with a size of `sm` or below. The form is typically wrapped in a `Sheet` component.
|
|
|
|
<ComponentPreview
|
|
name="form-patterns-sidepanel"
|
|
description="Complete form example with all field types in a SidePanel/Sheet pattern"
|
|
peekCode
|
|
wide
|
|
/>
|
|
|
|
## Field Arrays
|
|
|
|
The form previews above include both repeated-field patterns used across Studio:
|
|
|
|
- **Field Array** for repeated single-value rows such as redirect URIs.
|
|
- **Key/Value Field Array** for repeated text pairs such as headers, parameters, and config entries.
|
|
|
|
Use the shared [Single Value Field Array](../fragments/single-value-field-array) fragment when each row is one text input managed by `react-hook-form`.
|
|
|
|
Use the shared [Key/Value Field Array](../fragments/key-value-field-array) fragment when each row is two text inputs managed by `react-hook-form`.
|
|
|
|
Keep repeated-row validation in the form schema or shared validation helper, not in the fragment component itself.
|
|
|
|
Build a custom row when the cells are mixed controls, such as an input paired with a `Select`.
|
|
|
|
## Best Practices
|
|
|
|
1. **Always use FormItemLayout**: Use `FormItemLayout` instead of manually composing `FormItem`, `FormLabel`, `FormMessage`, and `FormDescription`.
|
|
|
|
2. **Layout selection**:
|
|
- Use `layout="flex-row-reverse"` for page layouts (horizontal alignment)
|
|
- Use `layout="horizontal"` for side panels with more width
|
|
- Use `layout="vertical"` for side panels with limited width
|
|
|
|
3. **Wrap inputs in FormControl*Shadcn***: Always wrap form inputs with `FormControl_Shadcn_` to ensure proper form integration.
|
|
|
|
4. **Use Cards for grouping**: Wrap form sections in `Card` components with `CardContent` and `CardFooter` for actions.
|
|
|
|
5. **Handle dirty state**: Show cancel buttons and disable save buttons based on `form.formState.isDirty`. Make sure you destructure `isDirty` from `form.formState` (see https://react-hook-form.com/docs/useform/formstate)
|
|
|
|
6. **Error handling**: Always use mutations with `onSuccess` and `onError` callbacks that show toast notifications.
|
|
|
|
7. **Loading states**: Show loading states on submit buttons using the `loading` prop.
|
|
|
|
8. **Form IDs**: When submit buttons are outside the form, use a form ID and reference it with the `form` prop on the button.
|