GrFormSection — Компоненты

Обзор

Когда брать

форма длинная — «Контакты», «Доставка», «Оплата»: разделы дают структуру и точки навигации;
раздел нужен незрячему — заголовок рендерится тегом h2…h6, и форма обходится по заголовкам;
у раздела есть действия — «Добавить», «Сбросить» в правой части шапки;
раздел нуждается в пояснении — описание под заголовком, а не подсказка у каждого поля.

Когда взять другое

Нужно	Берите
Правила и отправка	`GrForm`
Обвязка одного поля	`GrFormField`
Разделы переключаются, а не идут подряд	`GrTabs`
Раздел сворачивается	`GrCollapse`
Нужна просто карточка	`GrCard`

Playground контролы выводятся из API, а не пишутся руками

Сцена

Загружается…

0 изменено· состояние — в адресе

vue

<GrFormSection title="Billing contact" description="Invoices and payment reminders go to these addresses."><div class="grid gap-3"><GrFormField label="Invoice email"><GrInput modelValue="[email protected]" type="email" /></GrFormField><GrFormField label="Copy to"><GrInput modelValue="[email protected]" type="email" /></GrFormField></div></GrFormSection>

Примеры 3 у каждого — живое демо и его код

Оформление заказа, которое читается по заголовкам
Длинная форма получает структуру от секций: каждый заголовок — настоящий h3 под h2 страницы, поэтому скринридер обходит форму по заголовкам, а описание говорит за группу — «сюда придёт чек», — а не висит на первом поле.
Checkout
Contact
We send the receipt and delivery updates here.
Email
Phone
Delivery address
Couriers deliver on weekdays, 9:00–18:00.
Full name
Street
City
Eircode
Payment
Pay with
Visa ending 4242 Saved card, expires 08/28
Invoice Pay within 30 days by bank transfer
Действие, которое принадлежит секции
Слот title ставит счётчик рядом с заголовком, а слот actions держит то, что относится ко всей секции, — «Сбросить к умолчаниям». Внутри списка такая кнопка спорила бы с переключателями, которые сбрасывает.
Notifications 3 of 5 on
Email notifications for [email protected]
An invoice is paidRight away
An invoice becomes overdueThe morning after the due date
Weekly revenue summaryMondays at 9:00
Someone mentions youIn comments and notes
Product newsAbout once a month
Безопасность лендмарком и опасная зона
landmark превращает крупную секцию в регион с именем от заголовка — это оправдано там, где к «Безопасности» прыгают напрямую. Опасная зона ставит своё единственное действие в шапку через actions, а ссылку — в слот description.
Security
Applies to every member of the workspace.
Sign members out after
Danger zone
Deleting removes projects, invoices and members. What is kept for tax purposes

API порождается из пакета · разойтись не может

Props

Prop	Type	по умолчанию	Описание
`title`	`string \| undefined`	`undefined`	Заголовок секции — настоящий `h2`…`h6`, по нему обходят форму. Слот `#title` сильнее.
`description`	`string \| undefined`	`undefined`	Пояснение под заголовком, связано с секцией через `aria-describedby`. Слот `#description` сильнее.
`headingLevel`	`2 \| 3 \| 4 \| 5 \| 6 \| undefined`	`undefined`	Уровень заголовка под структуру страницы. Не задан — берётся из `GrConfigProvider`, иначе `3`.
`landmark`	`boolean \| undefined`	`false`	Объявить секцию лендмарком `region`. По умолчанию выключено: пять секций формы дали бы пять лендмарков и засорили обзор, а структуру и так несёт заголовок. Включать стоит там, где секция действительно крупная и к ней хочется прыгать как к региону.

Слоты

Slot	Type	Описание
`default`	`any`	Контент секции.
`title`	`any`	Заголовок целиком — вместо строки `title`.
`description`	`any`	Описание целиком — вместо строки `description`.
`actions`	`any`	Действия в правой части шапки: «Добавить», «Сбросить».

Типы

Все экспортируемые типы подпути, по файлам, где они объявлены. Имена, дженерики и тела читаются из файлов деклараций пакета и разойтись не могут.

Импорт

import type { GrFormSectionProps, GrFormSectionConfigurableProps, GrFormSectionHeadingLevel } from '@feugene/granularity/components/GrFormSection'

Файлdist/types/components/GrFormSection/GrFormSection.vue.d.ts

GrFormSectionPropsinterface

Секция формы: заголовок, необязательное описание и контент. Структуру длинной формы незрячий пользователь обходит **по заголовкам**, поэтому заголовок здесь настоящий (h2…h6), а не жирный текст.

interface GrFormSectionProps {
    /** Заголовок секции — настоящий `h2`…`h6`, по нему обходят форму. Слот `#title` сильнее. */
    title?: string;
    /**
     * Пояснение под заголовком, связано с секцией через `aria-describedby`. Слот
     * `#description` сильнее.
     */
    description?: string;
    /** Уровень заголовка под структуру страницы. Не задан — берётся из `GrConfigProvider`, иначе `3`. */
    headingLevel?: GrFormSectionHeadingLevel;
    /**
     * Объявить секцию лендмарком `region`.
     *
     * По умолчанию выключено: пять секций формы дали бы пять лендмарков и
     * засорили обзор, а структуру и так несёт заголовок. Включать стоит там, где
     * секция действительно крупная и к ней хочется прыгать как к региону.
     */
    landmark?: boolean;
}

Файлdist/types/components/GrFormSection/config.d.ts

grFormSectionConfigconst

const grFormSectionConfig: import("@feugene/granum/contract").GranumComponentDescriptor<"GrFormSection">;

Файлdist/types/components/GrFormSection/defaults.d.ts

GrFormSectionConfigurablePropsinterface

Пропы GrFormSection, настраиваемые глобально через <GrConfigProvider :component-defaults="{ GrFormSection: { … } }">. Только оформление — см. GrButton/defaults.ts.

interface GrFormSectionConfigurableProps {
    headingLevel: GrFormSectionHeadingLevel;
}

Файлdist/types/components/GrFormSection/grFormSectionStyles.d.ts

GrFormSectionHeadingLeveltype

type GrFormSectionHeadingLevel = typeof GR_FORM_SECTION_HEADING_LEVELS[number];

Файлdist/types/components/GrFormSection/safelist.d.ts

grFormSectionSafelistconst

const grFormSectionSafelist: string[];

Использование из прозы библиотеки

Заголовок — настоящий

Длинную форму незрячий пользователь обходит по заголовкам, поэтому заголовок секции рендерится тегом h2…h6, а не жирным текстом:

vue

<GrFormSection title="Профиль" :heading-level="2" description="Публичные данные">
  <GrFormField label="Имя"><GrInput v-model="name" /></GrFormField>
</GrFormSection>

headingLevel по умолчанию 3 и читается из GrConfigProvider (componentDefaults.GrFormSection.headingLevel) — уровень задаётся один раз на приложение, если у формы своя структура страницы.

Лендмарк по запросу

Корень — <section>, но без имени: именованная секция становится лендмарком region, и пять секций формы дали бы пять регионов в обзоре диктора. Структуру несёт заголовок.

Там, где секция действительно крупная и к ней хочется прыгать как к региону, включите landmark — имя придёт от заголовка:

vue

<GrFormSection landmark title="Безопасность" />

Описание связывается с секцией через aria-describedby в обоих режимах.

Слоты

Слот	Что заменяет
`title`	заголовок целиком — ссылка, бейдж, счётчик
`description`	описание целиком
`actions`	правая часть шапки: «Добавить», «Сбросить»
`default`	содержимое секции

Шапка — одна строка: заголовок с описанием слева, действия справа; на узком экране действия переносятся под заголовок. Без заголовка, описания и действий шапка не рендерится вовсе.

Рамка и сворачивание

Пропов bordered/collapsible нет намеренно — это композиция, а не настройка:

vue

<GrCard class="p-4">
  <GrFormSection title="Профиль" />
</GrCard>

Сворачивание даёт GrCollapse — у него тот же headingLevel, поэтому структура заголовков не ломается.

Обзор

Когда брать

Когда взять другое

Playground контролы выводятся из API, а не пишутся руками

Примеры 3 у каждого — живое демо и его код

Checkout

Contact

Delivery address

Payment

Notifications 3 of 5 on

Security

Danger zone

API порождается из пакета · разойтись не может

Props

Слоты

Типы

Использование из прозы библиотеки

Связанные четвёртый вопрос: когда не это