# `PhiaUi.Components.FormLayout`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/components/forms/form_layout.ex#L1)

Form layout structure components for grouping, organizing, and collecting
feedback within complex forms.

## Components

| Function | Purpose |
|---|---|
| `form_section/1` | Titled (optionally collapsible) field group |
| `form_fieldset/1` | Accessible `<fieldset>` + `<legend>` wrapper |
| `form_grid/1` | Responsive N-column form grid |
| `form_row/1` | Horizontal equal-width field row |
| `form_actions/1` | Submit/cancel/reset footer bar |
| `form_summary/1` | Aggregate validation error list at form top |

# `form_actions`

Renders a form footer bar for action buttons (submit, cancel, reset).

## Example

    <.form_actions align="between">
      <.button variant="ghost" type="button">Cancel</.button>
      <.button type="submit">Save changes</.button>
    </.form_actions>

## Attributes

* `align` (`:string`) - Button alignment: start | center | end | between. Defaults to `"end"`.
* `class` (`:string`) - Defaults to `nil`.
## Slots

* `inner_block` (required)

# `form_fieldset`

Renders an accessible `<fieldset>` with a `<legend>` for grouping related inputs.

## Example

    <.form_fieldset legend="Billing Address" required={true}>
      <.phia_input field={@form[:street]} label="Street" />
      <.phia_input field={@form[:city]} label="City" />
    </.form_fieldset>

## Attributes

* `legend` (`:string`) (required) - Text rendered inside the <legend> element.
* `required` (`:boolean`) - Appends a red asterisk to the legend. Defaults to `false`.
* `disabled` (`:boolean`) - Disables all form elements inside the fieldset. Defaults to `false`.
* `class` (`:string`) - Defaults to `nil`.
## Slots

* `inner_block` (required)

# `form_grid`

Renders a responsive CSS grid for form fields.

Always 1 column on mobile, expands to `:cols` columns at the `sm:` breakpoint.

## Example

    <.form_grid cols={2} gap="md">
      <.phia_input field={@form[:first_name]} label="First name" />
      <.phia_input field={@form[:last_name]} label="Last name" />
    </.form_grid>

## Attributes

* `cols` (`:integer`) - Grid columns: 1–4. Collapses to 1 on mobile. Defaults to `2`.
* `gap` (`:string`) - Column/row gap: sm (gap-3) | md (gap-4) | lg (gap-6). Defaults to `"md"`.
* `class` (`:string`) - Defaults to `nil`.
## Slots

* `inner_block` (required)

# `form_row`

Renders a horizontal row of form fields that stack vertically on mobile.

Each child occupies equal horizontal space (via `flex-1` applied by the child).

## Example

    <.form_row>
      <div class="flex-1"><.phia_input field={@form[:email]} label="Email" /></div>
      <div class="flex-1"><.phia_input field={@form[:phone]} label="Phone" /></div>
    </.form_row>

## Attributes

* `class` (`:string`) - Additional CSS classes on the row wrapper. Defaults to `nil`.
## Slots

* `inner_block` (required)

# `form_section`

Renders a titled form section that can optionally collapse via `<details>/<summary>`.

When `:collapsible` is `true`, uses native HTML `<details>/<summary>` — zero JS required,
consistent with the Tree component pattern.

## Examples

    <%!-- Static section --%>
    <.form_section title="Personal Information" description="Fill in your basic details.">
      <.phia_input field={@form[:name]} label="Name" />
    </.form_section>

    <%!-- Collapsible section --%>
    <.form_section title="Advanced Settings" collapsible={true} open={false}>
      <.phia_input field={@form[:api_key]} label="API Key" />
    </.form_section>

## Attributes

* `title` (`:string`) (required) - Section heading text.
* `description` (`:string`) - Optional helper text below the title. Defaults to `nil`.
* `collapsible` (`:boolean`) - Wraps content in native <details>/<summary>. Defaults to `false`.
* `open` (`:boolean`) - Initial expanded state when collapsible is true. Defaults to `true`.
* `class` (`:string`) - Additional CSS classes on the root element. Defaults to `nil`.
## Slots

* `inner_block` (required)
* `action` - Optional header-right actions (e.g. badge, button).

# `form_summary`

Renders an aggregate validation error list at the top of a form.

Renders **nothing** when `:errors` is empty. Uses `role="alert"` and
`aria-live="polite"` so screen readers announce errors when they appear.

## Example

    <.form_summary errors={@form_errors} />

## Attributes

* `errors` (`:list`) - List of error strings to display. Defaults to `[]`.
* `title` (`:string`) - Heading text above the error list. Defaults to `"Please fix the following errors:"`.
* `class` (`:string`) - Defaults to `nil`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*