LCEssentials/Documentation/SwiftUI.md

# LCEssentials — SwiftUI

SwiftUI components and `View` helpers. Foundation/value-type helpers are in
[Extensions.md](Extensions.md); UIKit-era helpers in [UIKit.md](UIKit.md).

Every section is a collapsible block — click a heading to expand it.

## Contents

- [Navigation](#navigation)
- [View helpers](#view-helpers)

---

## Navigation

<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

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.