[docs] SwiftUI.md: LCENavigationView (complete)

2026-08-29 19:30:30 -03:00
parent ec3442ed1c
commit 971278fa3c
1 changed files with 98 additions and 2 deletions
--- a/Documentation/SwiftUI.md
+++ b/Documentation/SwiftUI.md
@@ -14,8 +14,104 @@ Every section is a collapsible block — click a heading to expand it.

 ## Navigation

-<!-- batch 8 -->
+<details>
+<summary><b>LCENavigationView</b> — customizable navigation bar (iOS 15+)</summary>
+
+A drop-in replacement for the system navigation bar with left/right buttons,
+title + subtitle, background colour, and a hide toggle. Configuration methods
+return `self`, so they chain. **Per the workspace iOS standards, this component
+is mandatory on new SwiftUI screens instead of a hand-rolled bar.**
+
+`@available(iOS 15, *)`, iOS only.
+
+### `init(title: (any View) = Text(""), subTitle: (any View) = Text(""), @ViewBuilder content: () -> Content)`
+
+The `content` closure is everything shown **below** the bar.
+
+```swift
+LCENavigationView(title: Text("Profile")) {
+    ScrollView {
+        ProfileForm()
+    }
+}
+```
+
+### `func setTitle(text: (any View) = Text(""), subTitle: (any View)? = nil) -> LCENavigationView`
+
+Set (or replace) the title and optional subtitle. Passing no `subTitle` hides
+the subtitle row.
+
+```swift
+LCENavigationView { Content() }
+    .setTitle(text: Text("Orders"), subTitle: Text("32 open"))
+```
+
+### `func setLeftButton(text: Text = Text(""), image: (any View)? = nil, action: @escaping () -> Void) -> LCENavigationView`
+
+Configure the leading button. If the trailing button has no text/image yet, a
+transparent placeholder is added on that side so the title stays centred.
+
+```swift
+.setLeftButton(text: Text("Back"), image: Image(systemName: "chevron.left")) {
+    dismiss()
+}
+```
+
+### `func setRightButton(text: Text = Text(""), image: (any View)? = nil, action: @escaping () -> Void) -> LCENavigationView`
+
+Configure the trailing button (same placeholder behaviour for the leading side).
+
+```swift
+.setRightButton(image: Image(systemName: "plus")) {
+    showingNewItem = true
+}
+```
+
+### `func hideNavigationView(_ hide: Bool) -> LCENavigationView`
+
+Show or hide the whole bar (the content stays).
+
+```swift
+.hideNavigationView(isFullScreenMedia)
+```
+
+### `func setNavigationBarBackgroundColor(_ color: Color) -> LCENavigationView`
+
+Bar background colour (extends into the top safe area). Defaults to `.clear`.
+
+```swift
+.setNavigationBarBackgroundColor(.blue.opacity(0.1))
+```
+
+### Full example
+
+```swift
+struct OrdersScreen: View {
+    @Environment(\.dismiss) private var dismiss
+    @State private var showingNew = false
+
+    var body: some View {
+        LCENavigationView(title: Text("Orders")) {
+            OrdersList()
+        }
+        .setLeftButton(text: Text("Back"),
+                       image: Image(systemName: "chevron.left")) { dismiss() }
+        .setRightButton(image: Image(systemName: "plus")) { showingNew = true }
+        .setNavigationBarBackgroundColor(Color(.systemBackground))
+    }
+}
+```
+
+> `LCENavigationState` (the `@Published` backing store) and the reflection-based
+> `Text.string` / tag helpers in `View+Ext.swift` are `internal` implementation
+> details — not part of the public API.
+
+</details>
+
+---

 ## View helpers

-<!-- batch 8 -->
+There are currently no public standalone `View` extensions — the `getTag` /
+`extractTag` reflection utilities in `SwiftUI/View+Ext.swift` are `internal` and
+exist only to support `LCENavigationView`'s subtitle handling.