@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-4a-configuration.md

@@ -1,336 +0,0 @@
-# PHASE 4A  -  Configuration File
-
-Write the Configuration struct with chain modifier macros.
-Only executed for COMPLEX components (>3 properties).
-
-CONDITIONAL  -  skip if SIMPLE.
-PARALLEL WITH: Phase 4B (View), Phase 4C (FIGMA.md)
-
----
-
-## CONTEXT VARIABLES
-
-These are provided by the orchestrator in the dispatch prompt:
-- `componentName`  -  e.g., "LabelBadge"
-- `componentLocation`  -  e.g., "Sources/UIComponents/.../LabelBadge/"
-- `artifactPath`  -  path to implementation artifacts
-- `nodeId`  -  Figma node ID
-- `fileKey`  -  Figma file key
-- `complexity`  -  must be COMPLEX for this phase to execute
-- `gitUser`  -  from `git config user.name`
-- `date`  -  current date in DD.MM.YYYY format
-
----
-
-## PRE-CHECK
-
-If `complexity` is SIMPLE → do not execute. Return:
-
-```
-STATUS: COMPLETE
-PHASE: phase-4a
-GATES_PASSED: [PRE_CHECK]
-ARTIFACTS_CREATED: none
-SUMMARY: Skipped  -  SIMPLE component, no configuration file needed.
-```
-
-Read:
-```
-{artifactPath}/pass3/04b_component_architecture.md
-{artifactPath}/pass3/04c_variant_config_analysis.json
-{artifactPath}/pass3/05_complexity.md
-```
-
-The `04c_variant_config_analysis.json` (from Phase 3H) provides typed recommendations for each boolean property:
-- `KNOWN_SUBCOMPONENT` entries → use `swiftType` from 3H. Only `dynamicProps` go in config. If 2+ dynamic props → create mini config struct. If 1 → unwrap to single type. If 0 → boolean presence only.
-- `PAIRED_ACTION_SUBCOMPONENT` entries → same as KNOWN_SUBCOMPONENT for data props. The `pairedClosure` is a View dependency  -  NOT in Configuration. Phase 4B generates the paired modifier.
-- `ICON_BOOLEAN_GATED` entries → use `swiftType` (`Image?` or `Optional3<Image>`)
-- `CONTENT_LEAF` entries → `String?` (nil = hidden)
-
-Use `swiftName` from 3H for property naming. Use `rationale` to understand the classification.
-
-Read macros reference:
-```
-.instructions/figma/figma-to-swiftui/reference/macros.md
-```
-
-If any required file is missing:
-
-```
-STATUS: HALT
-PHASE: phase-4a
-GATE: PRE_CHECK
-REASON: Required Phase 3 artifacts missing.
-COMPLETED_GATES: []
-ARTIFACTS_CREATED: none
-USER_ACTION_REQUIRED: Run Phase 3 first.
-```
-
----
-
-## ARCHITECTURAL RULE  -  Configuration Purity
-
-**Configuration structs hold ONLY declarative, value-type properties.**
-
-Do NOT put these in Configuration  -  they are direct View dependencies:
-
-| Excluded Type | Where It Lives Instead |
-|---------------|----------------------|
-| Closures (`() -> Void`, `(T) -> Void`) | View property: `private var action: (() -> Void)?` |
-| `Binding<T>` / `@Binding` | View property: `@Binding var isPresented: Bool` |
-| `@State` / `@ObservedObject` / `@StateObject` | View property |
-| `AnyView` / `@ViewBuilder` closures | View property or generic parameter |
-
-This separation enables the `+Modifiers` extension (Phase 4E) to safely forward all Configuration properties as view-level chain modifiers.
-
-## ARCHITECTURAL RULE  -  Only Dynamic Props in Config
-
-**Sub-component properties that are fixed by the parent's design (static) do NOT go in Configuration.** Only caller-controlled (dynamic) properties are exposed.
-
-Phase 3H provides `dynamicProps` and `staticProps` for each sub-component entry. Use only `dynamicProps` when creating config properties or mini config structs. The parent View hardcodes `staticProps` internally when instantiating the sub-component.
-
----
-
-## GATE 1: CHECK_EXISTING
-
-```bash
-ls {componentLocation}/*Configuration.swift 2>/dev/null
-```
-
-| Result | Action |
-|--------|--------|
-| File exists | Read existing, extend if needed. Proceed to GATE 3. |
-| Not found | Create new (GATE 2) |
-
----
-
-## GATE 2: WRITE_CONFIGURATION
-
-INPUT: `pass3/04b_component_architecture.md`  -  contains the Final API Design section
-
-### 2.1 Extract from architecture
-
-From the **Final API Design** section, extract:
-- All enum definitions
-- All stored properties with types and defaults
-- All sub-configuration structs (if any)
-- Property attributes (@IgnoreChainModifier, @IgnoreLocalization, @ChainModifierName)
-
-### 2.2 Determine property attributes
-
-| Property Pattern | Attribute |
-|------------------|-----------|
-| UUID, ID, identifier | `@IgnoreChainModifier`  -  immutable, not chainable |
-| Non-localizable String (URL, code, ID) | `@IgnoreLocalization`  -  no `.title(localized:)` variant |
-| Name conflicts with SwiftUI methods | `@ChainModifierName("customName")` |
-| Closure `() -> Void` | `@IgnoreLocalization`  -  not a String |
-| Image | No special attribute needed |
-| Optional property | No attribute  -  macro generates double-optional `T??` in `modified()` automatically |
-
-### 2.3 Write file
-
-Write `{componentLocation}/{ComponentName}Configuration.swift`:
-
-```swift
-//
-//  {ComponentName}Configuration.swift
-//  UIComponents
-//
-//  Created by {gitUser} on {date}.
-//
-
-import SwiftUI
-import UIMacros
-
-// MARK: - {ComponentName} Configuration
-
-/// Configuration for ``{ComponentName}`` component.
-///
-/// Use chain modifiers to customize:
-/// ```swift
-/// {ComponentName} { config in
-///     config
-///         .property1("value")
-///         .property2(.variant)
-/// }
-/// ```
-@GenerateChainModifiers
-public struct {ComponentName}Configuration: Sendable {
-
-    // MARK: - Enums
-
-    {Enum definitions from architecture  -  inside the struct if component-specific}
-
-    // MARK: - Properties
-
-    public let {property1}: {Type}
-    public let {property2}: {Type}?
-    {... all properties from Final API Design}
-
-    // MARK: - Initialization
-
-    public init(
-        {property1}: {Type} = {default},
-        {property2}: {Type}? = nil
-    ) {
-        self.{property1} = {property1}
-        self.{property2} = {property2}
-    }
-}
-```
-
-**CRITICAL:** Do NOT manually write `modified()`, chain methods, or localized variants.
-The `@GenerateChainModifiers` macro generates ALL of these automatically:
-- `private func modified(...)` with double-optional pattern for optional properties
-- `.property1(_)` chain method for each property
-- `.property1(localized:)` for String properties (unless `@IgnoreLocalization`)
-
-### 2.4 Enum placement rules
-
-| Enum Scope | Placement |
-|------------|-----------|
-| Component-specific (e.g., `LabelBadgeState`) | Inside the Configuration struct |
-| Shared across components | Separate file or existing shared enum |
-| Purely visual (only affects styling) | Inside the Configuration struct, but consider making it internal |
-
-### 2.5 Sub-configuration structs
-
-If the architecture specifies sub-configurations (grouped properties):
-
-**For price data:** When the architecture identifies a `PRICE_PATTERN`, read the `/figma-price-integration` skill at `.instructions/figma/figma-price-integration/SKILL.md`. Define a nested `Price` struct conforming to `PriceRepresentable` with only the properties this component needs:
-
-```swift
-@GenerateChainModifiers
-public struct {ComponentName}Configuration: Sendable {
-    public let title: String
-    public let price: Price?
-
-    // Nested PriceRepresentable  -  only the fields this component uses
-    public struct Price: PriceRepresentable {
-        public let amount: Double
-        public let currency: String
-
-        public init(amount: Double, currency: String) {
-            self.amount = amount
-            self.currency = currency
-        }
-    }
-
-    public init(
-        title: String = "",
-        price: Price? = nil
-    ) {
-        self.title = title
-        self.price = price
-    }
-}
-```
-
-**For form data:** When the architecture identifies a `FORM_PATTERN` (component embeds 1+ form-capable sub-components  -  Selectbox, Checkbox, Radio, TextboxTextarea, DatepickerSchedule), read the `/figma-form-integration` skill at `.instructions/figma/figma-form-integration/SKILL.md`. Define a nested `Section` class conforming to `FormSection` (annotated with `@FormSection @Observable`) with ONLY the form fields this component renders. The `section` lives on Configuration; static labels/placeholders remain as Configuration strings:
-
-```swift
-@GenerateChainModifiers
-public struct {ComponentName}Configuration: Sendable {
-    public let section: {ComponentName}.Section
-    public let emailLabel: String
-    public let emailPlaceholder: String
-    public let phoneLabel: String
-    public let toggleLabel: String
-
-    public init(
-        section: {ComponentName}.Section,
-        emailLabel: String,
-        emailPlaceholder: String,
-        phoneLabel: String,
-        toggleLabel: String
-    ) {
-        self.section = section
-        self.emailLabel = emailLabel
-        self.emailPlaceholder = emailPlaceholder
-        self.phoneLabel = phoneLabel
-        self.toggleLabel = toggleLabel
-    }
-}
-
-extension {ComponentName} {
-    @FormSection
-    @Observable
-    public final class Section: FormSection {
-        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()])
-        public let isPrimary = CheckboxFormField()
-
-        public init() {}   // macro synthesizes `state` and `children`
-    }
-}
-```
-
-For atomic form components (exactly 1 embedded form sub-component), skip the `Section` and put the `FormField` directly on Configuration (or the View init for SIMPLE components). Value-carrying fields never flatten into Configuration as `Binding` or raw value properties.
-
-**For non-price, non-form sub-configurations:**
-
-```swift
-@GenerateChainModifiers
-public struct {ComponentName}Configuration: Sendable {
-    public let title: String
-    public let badge: BadgeSection?
-
-    // Nested sub-configuration (no @GenerateChainModifiers  -  only top-level gets it)
-    public struct BadgeSection: Sendable {
-        public let text: String
-        public let style: BadgeStyle
-
-        public init(text: String, style: BadgeStyle) {
-            self.text = text
-            self.style = style
-        }
-    }
-
-    public init(
-        title: String = "",
-        badge: BadgeSection? = nil
-    ) {
-        self.title = title
-        self.badge = badge
-    }
-}
-```
-
----
-
-## GATE 3: VALIDATE
-
-Verify the written file:
-
-```
-[ ] File exists at {componentLocation}/{ComponentName}Configuration.swift
-[ ] @GenerateChainModifiers applied to struct
-[ ] All properties from Final API Design present
-[ ] All enums defined with correct cases
-[ ] Init has sensible defaults (empty string, nil for optionals, first enum case or required)
-[ ] Struct is Sendable
-[ ] NO manual modified() method  -  macro handles it
-[ ] NO manual chain methods  -  macro handles it
-[ ] @IgnoreChainModifier on non-chainable properties
-[ ] @IgnoreLocalization on non-localizable String properties
-[ ] Correct imports: SwiftUI, UIMacros
-[ ] File header has correct author and date
-```
-
----
-
-## SUCCESS OUTPUT
-
-```
-STATUS: COMPLETE
-PHASE: phase-4a
-GATES_PASSED: [PRE_CHECK, CHECK_EXISTING, WRITE_CONFIGURATION, VALIDATE]
-ARTIFACTS_CREATED:
-  - {componentLocation}/{ComponentName}Configuration.swift
-SUMMARY: Configuration written with @GenerateChainModifiers. {PROPERTY_COUNT} properties, {ENUM_COUNT} enums. Macro generates chain methods automatically.
-```