import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
import {
  PlaygroundForm,
  DoWithOrganizedSections,
  DoWithActions,
  DontNoActions,
  DoWithActionsButton,
  DontNoSectionTitles,
  DoWithSectionTitles,
} from '../../components/layout/BmsForm.stories.js';

<Meta title="Documentation/Layout/Form" />

# <img src="../BmsIcon.png" /> Form

Form is a layout component that organizes form fields into sections and provides a consistent structure for form actions. It allows you to group related fields together using named slots and automatically positions action buttons at the bottom of the form. The component helps create well-organized, scannable forms with clear visual separation between sections.

## Anatomy

Form components consist of multiple named slots for organizing form fields into logical sections, and an actions slot for form submission buttons. Each section should have a clear title (typically an h2 heading) that describes the purpose of the fields within that section. Each section is visually separated, and the actions are consistently positioned at the bottom of the form.

## Component

Use the controls below to interact with the component and see how it behaves with different configurations.

<Canvas of={PlaygroundForm} />

### Props

<Controls of={PlaygroundForm} />

## Usage Examples

### ✅ Do: Form with organized sections

Organize form fields into logical sections using named slots. This makes the form easier to scan and understand.

<Canvas of={DoWithOrganizedSections} />

**Note on sections:** Using sections is not mandatory. They are particularly useful for improving readability when a form becomes too long. As a general guideline, consider using sections when you have more than 5 fields, as this helps users better understand and navigate the form structure.

### ✅ Do: Form with actions

Always provide action buttons (Submit, Cancel, etc.) in the actions slot. This gives users a clear way to submit or cancel the form.

<Canvas of={DoWithActions} />

## Rules

### ⛔ Don't: Form without section titles

Always provide a clear title for each section of the form. Section titles help users understand the purpose of each group of fields and make the form easier to scan and navigate.

**Note on section titles:** If your form has only one section, you don't need to add a title to that section. The page title should be sufficient in this case. Section titles are most useful when you have multiple sections to distinguish between different groups of fields.

**❌ Don't:**

<Canvas of={DontNoSectionTitles} />

**✅ Do:**

<Canvas of={DoWithSectionTitles} />

### ⛔ Don't: Form without actions

Always provide action buttons for forms. Without actions, users cannot submit or cancel the form, creating a poor user experience.

**❌ Don't:**

<Canvas of={DontNoActions} />

**✅ Do:**

<Canvas of={DoWithActionsButton} />
