feat(design-system): new Formspage in ui-patterns section (supabase#40978)

Author: fsansalvadore

apps/design-system/__registry__/index.tsx

@@ -1831,6 +1831,28 @@ export const Index: Record<string, any> = {
       subcategory: "undefined",
       chunks: []
     },
+    "form-patterns-pagelayout": {
+      name: "form-patterns-pagelayout",
+      type: "components:example",
+      registryDependencies: ["form","card","input","button","select","switch","checkbox","textarea","radio-group","calendar","popover","multi-select"],
+      component: React.lazy(() => import("@/registry/default/example/form-patterns-pagelayout")),
+      source: "",
+      files: ["registry/default/example/form-patterns-pagelayout.tsx"],
+      category: "undefined",
+      subcategory: "undefined",
+      chunks: []
+    },
+    "form-patterns-sidepanel": {
+      name: "form-patterns-sidepanel",
+      type: "components:example",
+      registryDependencies: ["form","sheet","input","button","select","switch","checkbox","textarea","radio-group","calendar","popover","multi-select"],
+      component: React.lazy(() => import("@/registry/default/example/form-patterns-sidepanel")),
+      source: "",
+      files: ["registry/default/example/form-patterns-sidepanel.tsx"],
+      category: "undefined",
+      subcategory: "undefined",
+      chunks: []
+    },
     "form-item-layout-with-select": {
       name: "form-item-layout-with-select",
       type: "components:example",

apps/design-system/config/docs.ts

@@ -65,6 +65,11 @@ export const docsConfig: DocsConfig = {
           href: '/docs/ui-patterns/empty-states',
           items: [],
         },
+        {
+          title: 'Forms',
+          href: '/docs/ui-patterns/forms',
+          items: [],
+        },
       ],
     },
     {

apps/design-system/content/docs/ui-patterns/forms.mdx

@@ -0,0 +1,50 @@
+---
+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
+/>
+
+## 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`.
+
+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.