@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/figma-form-integration/SKILL.md

@@ -0,0 +1,542 @@
+---
+name: figma-form-integration
+description: "Form pattern integration for Figma-to-SwiftUI components. Guides FormSection/FormField adoption — when a component embeds form-capable sub-components (Selectbox, Checkbox, Radio, TextboxTextarea, DatepickerSchedule, ButtonsInputStepper) this skill defines how to model them as FormField references inside a nested FormSection, owned by the caller."
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+status: wip-v5
+sourced-from: upstream/figma-form-integration
+---
+
+# /figma-form-integration — Form Pattern Integration
+
+## Purpose
+
+This skill is consumed by other skills (Phase 3D pattern detection, Phase 4A configuration, Phase 4B view implementation) when a **form pattern** is detected in a Figma component. It defines how to model form inputs using the CoreUI `FormField` + `FormSection` system instead of raw `@State`, `Binding`, or ad-hoc value properties.
+
+It is also **user-invocable** for vibe-coding / ad-hoc work: whenever you are wiring up a component that embeds form-capable sub-components outside the full figma-to-swiftui pipeline, run `/figma-form-integration` to apply the same rules.
+
+This is the forms counterpart of `/figma-price-integration`. Same shape: a protocol-level pattern (`FormSection`) with a default concrete implementation (`FormGroup`), consumed by Phase 3/4 as a cross-cutting integration.
+
+---
+
+## Strict Rules (non-negotiable)
+
+1. **Any form input MUST go through a `FormField` subclass.** No raw `Binding<Value>`, no `@State` values, no ad-hoc `isChecked: Bool` / `selectedOption: X` properties on Configuration or View. This applies to:
+   - A single embedded atomic control (Checkbox, Radio, Selectbox, TextboxTextarea, DatepickerSchedule).
+   - Multiple embedded controls forming a composite form (2+ inputs in one component).
+   - Any nested form sub-component detected in Figma.
+   If you see any of those cases → `FormField` / `FormSection`, always.
+
+2. **Multi-field components MUST expose a nested `FormSection`.** When the component embeds 2+ form-capable sub-components, the Configuration holds a nested `@FormSection @Observable` class conforming to `FormSection`. The View binds the section via `@Bindable` and delegates rendering per field.
+
+3. **The caller owns the section / fields. The component does NOT instantiate them.** Configuration carries the `FormSection` (or single `FormField`) reference. The scene view-model constructs the fields with their rules and policy; the component is headless over them.
+
+4. **Configuration holds form references, not values.** No `amount: String`, no `selectedOption: Option`, no `isChecked: Bool` next to a form input. If a value travels through the API, it travels through its `FormField`.
+
+5. **Section belongs in Configuration, not View — if a Configuration exists.** When the component has a Configuration struct (COMPLEX), the `FormSection` property MUST live on Configuration. Only components with NO Configuration may accept a `FormField` directly as a View init parameter.
+
+6. **Static content (labels, placeholders, helper text, toggle captions) stays in Configuration — not on the field.** Fields are pure form state: value, rules, policy, options, loading. Labels and copy are visual/content — they go on Configuration (chainable via `@GenerateChainModifiers`).
+
+7. **The nested `FormSection` mirrors the design exactly.** Declare ONLY the fields the component actually renders. Do not add fields the design doesn't use; do not drop fields the design does use. The section's shape is dictated by the design, not by developer convenience or a shared/generic form model.
+
+8. **Non-form actions ("Sil", "Detaylar", "Edit") stay as paired closures on the View.** They are NOT fields, NOT Configuration values — they are View dependencies passed via paired modifiers, exactly like any other coexistent action (see Phase 3D §2.3.1).
+
+9. **Validation and focus are caller concerns.** The component never exposes an `isValid` property, never owns a `FormFocus`, never calls `validate()` internally. The scene calls `section.validate()` (or `[section].validateAll(focus:)`) and sets `.formFocus(...)` at the scene root.
+
+---
+
+## When to Invoke This Skill
+
+Invoke when ANY of these are detected:
+
+1. **Phase 3D — Sub-Component Integration (§2.2):** A nested instance of a form-capable design-system component:
+   - `Selectbox` (single-select dropdown)
+   - `Checkbox` / `CheckboxButton`
+   - `Radio` / `RadioButton`
+   - `TextboxTextarea` (text input, single or multi-line)
+   - `DatepickerSchedule` (date / date-range input)
+   - `ButtonsInputStepper` (numeric +/- counter, e.g. passenger / quantity selectors)
+   - Any component whose Figma variants include an input state (empty/filled/error/disabled) with a user-driven value
+2. **Phase 4A — Configuration:** A property group contains form-input fields.
+3. **Phase 4B — View:** The view renders form controls that require user input with validation semantics.
+
+**Counting rule (atomic vs composite):**
+- **0 embedded form sub-components** — no form pattern; skip this skill.
+- **1 embedded form sub-component** — atomic form: the Configuration (or View init) takes ONE `*FormField` directly, no `FormSection` wrapper.
+- **2+ embedded form sub-components** — composite form: nested `FormSection` class in Configuration bundling every field.
+
+---
+
+## Architecture
+
+```
+Scene ViewModel (caller)
+    |
+    |  constructs fields + rules + policy
+    v
+ComponentName.Section : FormSection    (component-specific, only needed fields)
+    |  declared with @FormSection @Observable
+    |  macro synthesizes: state, children
+    v
+ComponentNameConfiguration
+    |  holds `section: ComponentName.Section`
+    |  plus static content (labels, placeholders, copy)
+    v
+ComponentName: View
+    |  @Bindable var section (plus paired closures for non-form actions)
+    v
+Atomic form views (Checkbox, Radio, Selectbox, InputField, DatePicker)
+  each takes its child field from section.<fieldName>
+```
+
+### Key Files
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `FormSection.swift` | `CoreUI/Components/Forms/Foundation/` | Protocol + default aggregate `validate` / `evaluate` / `clear` / `state` semantics |
+| `FormGroup.swift` | `CoreUI/Components/Forms/Foundation/` | Concrete everyday `FormSection` — use for ad-hoc grouping when a named type isn't worth it |
+| `FormField.swift` | `CoreUI/Components/Forms/Foundation/` | Generic base: `value`, `state`, `rules`, `validationPolicy` |
+| `Validatable.swift` | `CoreUI/Components/Forms/Foundation/` | Non-generic protocol; `[any Validatable].validateAll(focus:)` + `leafFields` |
+| `FormFocus.swift` | `CoreUI/Components/Forms/Foundation/` | `.formFocus(focus)` environment, `focus.focusFirstError()` |
+| `CheckboxFormField.swift` etc. | `CoreUI/Components/Forms/FormFields/` | Per-control mini-viewmodels |
+| `FormSection` macro | `UIMacros/FormSection/` | `@FormSection` synthesizes `state` + `children` |
+
+---
+
+## The Protocol
+
+```swift
+public protocol FormSection: Validatable {
+    // Inherits from Validatable:
+    //   var children: [any Validatable] { get }
+    //   var state: FormState { get set }
+    //   validate() / evaluate() / clear()
+}
+```
+
+Default aggregate implementations are provided by a protocol extension: `validate()` runs every child (no short-circuit — all inline errors update), rolls the first error into the section's own `state`; `clear()` resets everything to `.pristine`. Identical semantics to `FormGroup`.
+
+### @FormSection macro
+
+Attached to an `@Observable` class, synthesizes:
+- `public var state: FormState = .pristine`
+- `public var children: [any Validatable]` — auto-detected from stored properties whose type matches `*FormField`, `*FormSection`, `FormGroup`, or is marked `@FormChild`.
+
+Supports `T?`, `[T]`, `[T]?` transparently. Plain data properties (`String`, `URL`, `Int`) are ignored.
+
+---
+
+## How to Create a Component-Specific Section
+
+**Rule: each COMPOSITE form component defines its own nested `.Section` class conforming to `FormSection`.** The nested section exposes ONLY the fields that component accepts — no silent discard.
+
+### Step 1: Inventory the Embedded Form Sub-Components
+
+From the Figma design, list every input element:
+
+| Figma element | FormField subclass | Notes |
+|---|---|---|
+| Selectbox (single value) | `PickerFormField<Option>` | `.searchable(options:)` if search enabled; `.async()` if remote |
+| Selectbox (multi select) | `MultiPickerFormField<Option>` | Usually max selection rule |
+| Checkbox / CheckboxButton (single) | `CheckboxFormField` | `MustBeTrueRule` if acceptance |
+| Checkbox group | `CheckboxGroupFormField<Option>` | `minSelections` / `maxSelections` |
+| Radio / RadioButton group | `RadioFormField<Option>` | `RequiredSelectionRule` |
+| TextboxTextarea (single line) | `TextFormField` | Add filters: digits, email regex, max length |
+| TextboxTextarea (multi line) | `TextFormField` (textArea:true) | Same field type, visual variant |
+| DatepickerSchedule (date) | `DatePickerFormField` | `.flightDate()` / `.birthDate()` factories |
+| DatepickerSchedule (range) | `DateRangePickerFormField` | `.roundTrip(minimumNights:maximumNights:)` |
+| ButtonsInputStepper (numeric +/-) | `StepperFormField` | `minValue` / `maxValue` / `step`; helpers `increment()` / `decrement()` / `canIncrement` / `canDecrement` |
+| Toggle (visual switch of Bool, dedicated) | `ToggleFormField` | Use when the design renders a Switch (`TurkishToggle`) and you want a typed-distinct field. No indeterminate state. `MustBeTrueRule()` if acceptance. Factory: `ToggleFormField.disabled(value:)`. |
+| Toggle (visual switch of Bool, unified with checkbox) | `CheckboxFormField` | Use when toggle and checkbox are interchangeable in the same form (atomic view decides Switch vs Box rendering). Has `.indeterminate` state which Toggle never uses. |
+| Phone input (country code + number) | Composite `PhoneFormField` (one field) | Wraps two children internally; see `FormField` composite pattern |
+
+### Step 2: Define the Nested Section (COMPOSITE, 2+ fields)
+
+**If the component has a Configuration struct (default for COMPLEX components):** Nest a `@FormSection`-annotated class inside the component's namespace, and put the `section` property on Configuration.
+
+```swift
+extension PNRContactCard {
+
+    @FormSection
+    @Observable
+    public final class Section: FormSection, @unchecked Sendable {
+        public let email = TextFormField(
+            rules: [RequiredRule(), EmailRule()]
+        )
+        public let phoneCountry = PickerFormField<CountryCode>.searchable(
+            options: CountryCode.all,
+            initialValue: .tr,
+            rules: [RequiredSelectionRule()]
+        )
+        public let phoneNumber = TextFormField(
+            rules: [RequiredRule(), PhoneRule()],
+            filter: .digitsOnly
+        )
+        public let isPrimary = CheckboxFormField()
+
+        public init() {}   // caller builds with defaults; override factories if needed
+        // Macro synthesizes: var state, var children
+    }
+}
+```
+
+> **`@unchecked Sendable` on the nested `Section`**: nested `Section` classes MUST conform to `@unchecked Sendable` so they can be stored on a `Sendable` Configuration (compiler cannot verify a mutable reference type as Sendable, but @Observable's MainActor scheduling makes it safe in practice). All concrete sections in the codebase use this pattern (see `MilesSmilesMilesMissingMiles.Section`, `AvailabilityFilter.Section`).
+
+**If the component has NO Configuration (SIMPLE, 0–1 field):** skip the `Section` and take the `FormField` directly on the View init.
+
+```swift
+public struct TermsCheckbox: View {
+    @Bindable private var field: CheckboxFormField
+    public init(field: CheckboxFormField) { self._field = Bindable(field) }
+    // ...
+}
+```
+
+### Step 3: Define the Configuration
+
+```swift
+@GenerateChainModifiers
+public struct PNRContactCardConfiguration: Sendable {
+    public let section: PNRContactCard.Section      // form binding root
+
+    // Identity / static content
+    public let badgeText: String                    // "PNR Kontakt"
+    public let passengerName: String                // display-only
+    public let avatarURL: URL?
+    public let deleteLinkTitle: String?             // "Sil" (paired action's label)
+
+    // Per-field labels / placeholders — static copy, NOT on the field
+    public let emailLabel: String                   // "E-Posta"
+    public let emailPlaceholder: String             // "E-Postanızı giriniz"
+    public let phoneLabel: String                   // "Telefon Numarası"
+    public let toggleLabel: String                  // "Birincil (PNR Kontakt) yolcusu yap"
+
+    public init(
+        section: PNRContactCard.Section,
+        badgeText: String,
+        passengerName: String,
+        avatarURL: URL? = nil,
+        deleteLinkTitle: String? = nil,
+        emailLabel: String,
+        emailPlaceholder: String,
+        phoneLabel: String,
+        toggleLabel: String
+    ) {
+        self.section = section
+        self.badgeText = badgeText
+        self.passengerName = passengerName
+        self.avatarURL = avatarURL
+        self.deleteLinkTitle = deleteLinkTitle
+        self.emailLabel = emailLabel
+        self.emailPlaceholder = emailPlaceholder
+        self.phoneLabel = phoneLabel
+        self.toggleLabel = toggleLabel
+    }
+}
+```
+
+### Step 4: Implement the View
+
+Bind the section, render each field via its atomic form view, pass paired closures for non-form actions.
+
+```swift
+public struct PNRContactCard: View {
+    private let configuration: PNRContactCardConfiguration
+    private let onDelete: (() -> Void)?
+
+    @Bindable private var section: Section
+
+    public init(
+        configuration: PNRContactCardConfiguration,
+        onDelete: (() -> Void)? = nil
+    ) {
+        self.configuration = configuration
+        self.onDelete = onDelete
+        self._section = Bindable(configuration.section)
+    }
+
+    public var body: some View {
+        VStack(alignment: .leading, spacing: .Spacing.m) {
+            Badge(configuration.badgeText, style: .success)
+
+            HStack {
+                Avatar(url: configuration.avatarURL)
+                Text(configuration.passengerName).font(.bodyBold)
+                Spacer()
+                if let label = configuration.deleteLinkTitle {
+                    LinkButton(label) { onDelete?() }
+                }
+            }
+
+            InputField(field: section.email)
+                .label(configuration.emailLabel)
+                .placeholder(configuration.emailPlaceholder)
+                .keyboard(.emailAddress)
+
+            HStack(spacing: .Spacing.s) {
+                Selectbox(field: section.phoneCountry).width(96)
+                InputField(field: section.phoneNumber)
+                    .label(configuration.phoneLabel)
+                    .keyboard(.phonePad)
+            }
+
+            HStack {
+                Text(configuration.toggleLabel)
+                Spacer()
+                Toggle(field: section.isPrimary)
+            }
+        }
+        .padding(.Spacing.l)
+        .background(Color.Surface.card)
+        .cornerRadius(.Radius.l)
+    }
+}
+```
+
+---
+
+## Scene-Level Usage (for vibe-coding reference)
+
+```swift
+@Observable
+final class EInvoiceSceneVM {
+    let contacts: [PNRContactCard.Section] = [PNRContactCard.Section()]
+    let passengerSelection = RadioFormField<Passenger>(
+        rules: [RequiredSelectionRule()]
+    )
+    var focus: FormFocus?
+
+    var form: FormGroup {
+        FormGroup([passengerSelection] + contacts.map { $0 as any Validatable })
+    }
+
+    func submit() {
+        guard form.validate() else { focus?.focusFirstError(); return }
+        // build payload from field values
+    }
+}
+
+struct EInvoiceSceneView: View {
+    @State private var vm = EInvoiceSceneVM()
+
+    var body: some View {
+        ScrollView {
+            VStack(spacing: .Spacing.l) {
+                PassengerList(configuration: .init(
+                    title: "Yolcu Listesi",
+                    description: "E-Fatura talebinde bulunacağınız yolcuyu seçiniz.",
+                    selection: vm.passengerSelection
+                )) { pax in router.openTicketDetails(pax) }
+
+                ForEach(vm.contacts) { section in
+                    PNRContactCard(configuration: .init(
+                        section: section,
+                        badgeText: "PNR Kontakt",
+                        passengerName: section.displayName,
+                        emailLabel: "E-Posta",
+                        emailPlaceholder: "E-Postanızı giriniz",
+                        phoneLabel: "Telefon Numarası",
+                        toggleLabel: "Birincil (PNR Kontakt) yolcusu yap"
+                    )) { vm.remove(section) }
+                }
+
+                PrimaryButton("Devam Et") { vm.submit() }
+            }
+        }
+        .formFocus($vm.focus)       // ← scene root
+    }
+}
+```
+
+---
+
+## Integration with Phase 3D
+
+When Phase 3D's Sub-Component Integration (§2.2) detects a form-capable instance:
+
+### Replace / augment §2.2 Output
+
+Instead of treating a Selectbox/Checkbox/Radio/TextboxTextarea/DatepickerSchedule instance as a mini-config struct of its dynamic props, recognize it as a **form input** and emit a `FormField` reference.
+
+### Architecture Output (04b_component_architecture.md)
+
+In the Sub-Components section:
+
+```markdown
+## Sub-Components
+
+| Element | Scope | Integration |
+|---------|-------|-------------|
+| Email input (TextboxTextarea) | Required | `FormField` — `email: TextFormField` in nested `Section` |
+| Phone country (Selectbox) | Required | `FormField` — `phoneCountry: PickerFormField<CountryCode>` |
+| Phone number (TextboxTextarea) | Required | `FormField` — `phoneNumber: TextFormField` |
+| Primary toggle (Checkbox)   | Required | `FormField` — `isPrimary: CheckboxFormField` (rendered as Switch) |
+```
+
+In the Final API Design:
+
+```swift
+extension ComponentName {
+    @FormSection
+    @Observable
+    public final class Section: FormSection, @unchecked Sendable {
+        public let email: TextFormField
+        public let phoneCountry: PickerFormField<CountryCode>
+        public let phoneNumber: TextFormField
+        public let isPrimary: CheckboxFormField
+        public init(...)
+    }
+}
+
+public struct ComponentNameConfiguration: Sendable {
+    public let section: ComponentName.Section
+    // + static content (labels, placeholders)
+}
+```
+
+> **Configuration imports**: when using `@GenerateChainModifiers` on a Configuration that contains String / `*Title` / label properties, the macro emits `LocalizationStringKey` overloads. Add `import CoreLocalization` to the Configuration file or the build will fail with `cannot find type 'LocalizationStringKey' in scope`.
+
+### Property Classification addition
+
+| Classification | When | Swift Pattern |
+|---|---|---|
+| Form section (composite) | Component contains 2+ form-capable sub-components | `section: ComponentName.Section` on Configuration |
+| Form field (atomic) | Component contains exactly 1 form-capable sub-component | `field: SomeFormField` on Configuration or View init |
+
+### Layer-text + form interaction
+
+Dynamic layer text INSIDE a form control (e.g. the placeholder text inside a Selectbox) is still **static copy** from the caller's perspective — it becomes a Configuration string (`placeholder`, `label`), NOT a FormField-value substitute. Form fields own the *value*, not the *copy*.
+
+---
+
+## Integration with Phase 4A
+
+When writing the Configuration struct for a component with form fields:
+
+1. Define the nested `Section: FormSection` class in an extension on the component namespace, annotated `@FormSection @Observable`.
+2. Only include the fields identified in Phase 3D analysis — one FormField subclass per form sub-component.
+3. The `section` property on Configuration is non-optional when the form is required, optional when the whole form block is boolean-gated.
+4. Do NOT flatten field values into the Configuration — keep them inside the section.
+5. Static content (labels, placeholders, helper copy, toggle labels) stays in Configuration as `String` / `String?` and gets chainable modifiers via `@GenerateChainModifiers`.
+6. Paired action closures (`onDelete`, `onEdit`, row-level disclosure) stay as View init parameters — NOT in Configuration, NOT on fields.
+
+---
+
+## Integration with Phase 4B
+
+When implementing the View that renders form data:
+
+```swift
+public struct ComponentName: View {
+    private let configuration: ComponentNameConfiguration
+    private let onAction: (() -> Void)?
+
+    @Bindable private var section: Section
+
+    public init(
+        configuration: ComponentNameConfiguration,
+        onAction: (() -> Void)? = nil
+    ) {
+        self.configuration = configuration
+        self.onAction = onAction
+        self._section = Bindable(configuration.section)
+    }
+
+    public var body: some View {
+        VStack(...) {
+            InputField(field: section.email)
+                .label(configuration.emailLabel)
+                .placeholder(configuration.emailPlaceholder)
+
+            Selectbox(field: section.phoneCountry)
+            // ... etc
+        }
+    }
+}
+```
+
+### Rules
+
+- **Never** use `@State` for form values. Never wrap `section.<field>.value` in `Binding(get:set:)` — pass the field itself.
+- **Never** call `section.validate()` from inside the View. Validation is a caller concern.
+- **Never** instantiate a `FormField` or `Section` inside the component. They come from the caller via Configuration.
+- **Do** read `section.state` to render section-level banners/errors if the design shows one.
+- **Do** use atomic form views (`InputField(field:)`, `Selectbox(field:)`, `Radio(field:)`, `Checkbox(field:)`, `DatePicker(field:)`) — they handle `field.state` → visual state internally.
+
+---
+
+## Atomic vs Composite Decision
+
+```
+┌────────────────────────────────────────────────────┐
+│ Count form-capable sub-components in the design    │
+├────────────────────────────────────────────────────┤
+│ 0  → No form pattern. Skip this skill.             │
+│ 1  → Atomic. Use `*FormField` directly on Config  │
+│      / View init. No Section wrapper.              │
+│ 2+ → Composite. Nested `.Section: FormSection`     │
+│      class on Configuration.                       │
+└────────────────────────────────────────────────────┘
+```
+
+---
+
+## When NOT to Use Form Integration
+
+- **Pure display components** showing data that is not user-editable — use plain `String` / `Int` / model properties.
+- **Static checkmarks / indicators** that are read-only state (e.g., a green tick in a stepper) — use `Bool` in Configuration, not `CheckboxFormField`.
+- **Radio-like selection that is display only** (e.g., a highlighted selected tab in a segmented control where selection is controlled by the parent, not a form submission) — use an `enum` property, not `RadioFormField`.
+- **Segmented controls that represent navigation / filter state, not form input** — plain `Binding<Enum>` is fine for those; they are not validated or submitted.
+
+Rule of thumb: ask "would a ViewModel run `validate()` on this value before submitting?" If no → it's not a form field.
+
+---
+
+## FormGroup Everyday Use
+
+When you need ad-hoc grouping (not a stable component-owned section), use `FormGroup` directly:
+
+```swift
+// In a scene where 3 fields logically belong together but no named type is worth it:
+let personalInfo = FormGroup(firstName, lastName, birthDate)
+
+personalInfo.validate()
+personalInfo.leafFields    // for FormFocus.fields
+```
+
+Prefer a named `FormSection` subclass when the card has a stable identity in the design. Use `FormGroup` only for genuinely ad-hoc scoping.
+
+---
+
+## Real-World Scenarios
+
+| Scenario | Model |
+|---|---|
+| Card with 1 checkbox (accept terms) | View takes `CheckboxFormField` directly, no Section |
+| PNR contact card (email + phone + primary toggle) | Nested `Section` with 3 fields |
+| Passenger list (single-select radio over passengers) | Caller owns `RadioFormField<Passenger>`, component atomic |
+| Search form with free-text + date range + pax count selectbox | Nested `Section` with 3 fields |
+| E-invoice form (passenger radio + N contact cards) | Scene `FormGroup([passengerRadio] + contacts.map { $0 })` |
+| Password change (old + new + confirm) | Nested `Section` with 3 `TextFormField`s + cross-field `MatchRule` |
+| Toggle inside a card (no other inputs, dedicated) | `ToggleFormField` directly on Configuration (atomic, no Section) — preferred when the design uses `TurkishToggle` |
+| Toggle inside a card (no other inputs, unified) | `CheckboxFormField` directly on Configuration (atomic, no Section) — only when toggle and checkbox are interchangeable in the same form |
+| Passenger picker (N stepper rows + disclosure expansion) | Nested `Section` with N `StepperFormField`s + a plain `displayState` enum property (named to avoid colliding with the `state: FormState` synthesized by `@FormSection`) |
+| Filter panel (1 toggle + N multi-select chip groups) | Nested `Section` with 1 `ToggleFormField` + N `CheckboxGroupFormField<Item>` (one per group). Section conforms to `@unchecked Sendable`. See `AvailabilityFilter` for the canonical example. |
+
+---
+
+## Checklist — Before Leaving the Skill
+
+```
+[ ] Counted form-capable sub-components in the Figma design
+[ ] Decided atomic (1) vs composite (2+)
+[ ] For composite: defined nested `Section: FormSection` with @FormSection @Observable
+[ ] Section declares ONLY fields the design renders (no extras, no omissions)
+[ ] Configuration carries `section: .Section` (or single field for atomic)
+[ ] Labels / placeholders / toggle captions are Configuration strings, NOT on fields
+[ ] Non-form actions (Sil/Edit/Detaylar) are paired closures on the View
+[ ] View uses @Bindable on the section; never @State for values
+[ ] View never calls validate() or instantiates fields
+[ ] No Binding<Value> anywhere in the component — only field references
+[ ] Scene-level caller builds the section, calls validate() / leafFields / focus
+```