swiftui_native/

view.rs

//! `View` — chainable modifier API for ergonomic view construction.
//!
//! ```ignore
//! use swiftui_native::prelude::*;
//!
//! text("Hello").bold().padding(16.0).bg(Color::BLUE).opacity(0.9)
//! ```

use crate::color::Color;
use crate::views::{self, ViewHandle};

/// A SwiftUI view with chainable modifiers.
pub struct View {
    pub(crate) handle: ViewHandle,
}

impl View {
    /// Wrap a handle so the chainable modifiers can be used on it.
    pub fn new(handle: ViewHandle) -> Self {
        Self { handle }
    }

    /// Get the underlying handle.
    pub fn handle(&self) -> &ViewHandle {
        &self.handle
    }

    /// Consume and return the handle.
    pub fn into_handle(self) -> ViewHandle {
        self.handle
    }

}

// `View`'s chainable methods, by subject. Rust lets a type's inherent methods
// live in several modules, and four hundred of them in one file was a file
// nobody could find anything in — each round's section had been inserted
// wherever the last edit happened to land, so "layout" appeared five times and
// "navigation" three.
mod accessibility;
mod generated;
pub mod style;
mod appearance;
mod controls;
mod interaction;
mod layout;
mod navigation;
mod system;
mod text;


impl std::fmt::Debug for View {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "View({:?})", self.handle)
    }
}

/// Anything that can become a `View`.
pub trait IntoView {
    fn into_view(self) -> View;
}

impl IntoView for View {
    fn into_view(self) -> View {
        self
    }
}

impl IntoView for ViewHandle {
    fn into_view(self) -> View {
        View::new(self)
    }
}

impl IntoView for &str {
    fn into_view(self) -> View {
        text(self)
    }
}

impl IntoView for String {
    fn into_view(self) -> View {
        text(&self)
    }
}

impl IntoView for &String {
    fn into_view(self) -> View {
        text(self)
    }
}

macro_rules! into_view_via_display {
    ($($t:ty),*) => {
        $(
            impl IntoView for $t {
                fn into_view(self) -> View {
                    text(&self.to_string())
                }
            }
        )*
    };
}

// Numbers are common enough in a UI that requiring `format!` at every call site
// is just noise.
into_view_via_display!(i32, i64, u32, u64, usize, f32, f64, bool);

/// `Optional` is a view in SwiftUI: `nil` renders as nothing.
///
/// So `Some(v)` is `v` and `None` is an `EmptyView`, which is what lets a
/// `children.iter().map(...)` that sometimes yields nothing be passed straight
/// into a container.
impl<T: IntoView> IntoView for Option<T> {
    fn into_view(self) -> View {
        match self {
            Some(v) => v.into_view(),
            None => empty(),
        }
    }
}

// ═══════════════════════════════════════════════════════════════════════════
// Free functions — the ergonomic DSL
// ═══════════════════════════════════════════════════════════════════════════

/// Create a `Text` view.
pub fn text(s: &str) -> View {
    View::new(views::text(s))
}

/// Create a `Color` view.
pub fn color(c: Color) -> View {
    View::new(views::color(c.r, c.g, c.b, c.a))
}

/// Create a `Spacer`.
pub fn spacer() -> View {
    View::new(views::spacer())
}

/// Create a `Divider`.
pub fn divider() -> View {
    View::new(views::divider())
}

/// Create an `EmptyView`.
pub fn empty() -> View {
    View::new(views::empty_view())
}

// The constructors for the things this crate *synthesises*. They are free
// functions rather than chainable methods because they start a view rather than
// modify one — `shape` and `ns_view` are to `custom_shape` and
// `ns_view_representable` what `text` is to `views::text`.

/// A `Shape` written in Rust, drawn with the foreground style.
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// # use swiftui_native::views;
/// let chevron = views::shape_fn(|p: &mut views::ShapePath, r: views::Rect| {
///     p.move_to(r.x, r.y + r.height);
///     p.line_to(r.x + r.width * 0.5, r.y);
///     p.line_to(r.x + r.width, r.y + r.height);
/// });
/// let v = shape(&chevron).frame(80.0, 80.0);
/// ```
pub fn shape(s: &views::CustomShape) -> View {
    View::new(views::custom_shape(s))
}

/// An AppKit view hosted in a SwiftUI tree.
///
/// See [`views::ns_view_fn`] for making one.
#[cfg(target_os = "macos")]
pub fn ns_view(rep: &views::NSViewRep) -> View {
    View::new(views::ns_view_representable(rep))
}

/// A `ScrollViewReader`, whose content is handed a proxy it can scroll with.
pub fn scroll_reader<V: IntoView>(
    content: impl Fn(views::ScrollProxy) -> V + 'static,
) -> View {
    View::new(views::scroll_view_reader(move |proxy| {
        content(proxy).into_view().into_handle()
    }))
}

/// `ContentUnavailableView` — the placeholder for a screen with nothing on it.
pub fn content_unavailable(title: &str, system_image: &str, description: Option<&str>) -> View {
    View::new(views::content_unavailable(title, system_image, description))
}

/// Create an SF Symbol `Image`.
pub fn image(system_name: &str) -> View {
    View::new(views::system_image(system_name))
}

/// Create a `VStack`.
pub fn vstack(children: &[View]) -> View {
    let handles: Vec<ViewHandle> = children.iter().map(|v| v.handle.clone()).collect();
    View::new(views::vstack(&handles))
}

/// Create an `HStack`.
/// The handles behind a slice of views, for the stack constructors.
fn handles(children: &[View]) -> Vec<ViewHandle> {
    children.iter().map(|v| v.handle.clone()).collect()
}

/// `AsyncImage(url:scale:)` — an image fetched from a URL.
///
/// `None` is the empty case, which is what SwiftUI shows before a URL resolves.
pub fn async_image(url: Option<&str>, scale: f64) -> View {
    View::new(views::async_image(url, scale))
}

/// `Canvas { … }` — immediate-mode drawing.
pub fn canvas() -> View {
    View::new(views::canvas())
}

/// `ProgressView()` with no value — the indeterminate spinner, as distinct from
/// [`progress`], which shows a fraction.
pub fn progress_indeterminate() -> View {
    View::new(views::progress_indeterminate())
}

/// `Text(verbatim:)` — shown exactly as given.
///
/// [`text()`] goes through `LocalizedStringKey`, so a string that looks like a key
/// is looked up. This one never is, which is what you want for a name, a number
/// or anything already in the user's own words.
pub fn text_verbatim(s: &str) -> View {
    View::new(views::text_verbatim(s))
}

/// `EquatableView(content:)` — let SwiftUI skip redrawing when the value has not
/// changed.
pub fn equatable_text(text: &str) -> View {
    View::new(views::equatable_text(text))
}

/// `Table(of:)` over interface orientations, with a single column.
pub fn table(rows: &[views::Orientation], title: &str, cell: &str) -> View {
    View::new(views::table(rows, title, cell))
}

/// `TupleView<(A, B, …)>` — several views with no container around them.
///
/// This is what a `@ViewBuilder` block evaluates to, and it is why
/// `List { Text("a"); Text("b") }` is two rows: a `List` renders each element of
/// its content. Wrapping them in a stack instead gives one row holding a stack,
/// which is a different screen.
///
/// Usually reached through the container macros — [`crate::list!`],
/// [`crate::form!`], [`crate::section!`] — rather than called directly.
pub fn tuple_view(children: &[View]) -> View {
    View::new(views::tuple_view(&handles(children)))
}

/// `VStack(alignment:) { … }` — how children line up across the stack's width.
pub fn vstack_aligned(children: &[View], alignment: views::HorizontalAlignment) -> View {
    View::new(views::vstack_aligned(&handles(children), alignment))
}

/// `VStack(alignment:spacing:) { … }` — `None` keeps SwiftUI's own spacing.
pub fn vstack_aligned_spacing(
    children: &[View],
    alignment: views::HorizontalAlignment,
    spacing: Option<f64>,
) -> View {
    View::new(views::vstack_aligned_spacing(&handles(children), alignment, spacing))
}

/// `HStack(alignment:) { … }` — how children line up across the stack's
/// height. The baseline cases align on the children's text rather than on
/// their boxes.
pub fn hstack_aligned(children: &[View], alignment: views::VerticalAlignment) -> View {
    View::new(views::hstack_aligned(&handles(children), alignment))
}

/// `HStack(alignment:spacing:) { … }` — `None` keeps SwiftUI's own spacing.
pub fn hstack_aligned_spacing(
    children: &[View],
    alignment: views::VerticalAlignment,
    spacing: Option<f64>,
) -> View {
    View::new(views::hstack_aligned_spacing(&handles(children), alignment, spacing))
}

/// `Section { … }` with no header.
pub fn section(content: View) -> View {
    View::new(views::section_content(content.handle()))
}

/// `Section { … } header: { … }`
pub fn section_titled(header: View, content: View) -> View {
    View::new(views::section(header.handle(), content.handle()))
}

/// `Section { … } footer: { … }`
///
/// A footer is where a settings group's explanatory line goes — the small text
/// under a block of toggles saying what they do. Only the no-header and
/// header-only initialisers were bound, so there was nowhere to put one.
pub fn section_footer(footer: View, content: View) -> View {
    View::new(views::section_footer(footer.handle(), content.handle()))
}

/// `Section { … } header: { … } footer: { … }`
pub fn section_titled_footer(header: View, footer: View, content: View) -> View {
    View::new(views::section_header_footer(
        header.handle(),
        footer.handle(),
        content.handle(),
    ))
}

/// `Section(isExpanded:) { … } header: { … }` — a section that collapses.
///
/// The disclosure state is bound to Rust state rather than given as an initial
/// value, so the section opens and closes by itself *and* whatever else reads
/// that state sees it.
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// # use swiftui_native::views::BoundState;
/// let open = BoundState::new(true);
/// let s = section_expanded(&open, text("Advanced"), text("the details"));
/// ```
pub fn section_expanded(
    is_expanded: &views::BoundState<bool>,
    header: View,
    content: View,
) -> View {
    View::new(views::section_expanded(
        is_expanded,
        header.handle(),
        content.handle(),
    ))
}

/// `Tab("Home", systemImage: "house") { … }` — one tab of a modern `TabView`.
///
/// The older way to build a tab is `.tabItem { Label(…) }` on the page itself;
/// `Tab` is the replacement, where the tab and its label are one value rather
/// than a modifier on the content.
///
/// A `Tab` is not a view — it is a `TabContent`, and only [`tab_view_tabs`]
/// accepts one.
pub fn tab(title: &str, system_image: &str, content: View) -> View {
    View::new(views::tab(title, system_image, content.handle()))
}

/// `TabView { Tab(…); Tab(…); … }` — the modern tab view.
///
/// The older way is [`tab_view`](crate::tab_view) with `.tab_item` on each
/// page; this takes [`tab`] values, where the tab and its label are one value
/// rather than a modifier on the content.
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// let view = tab_view_tabs(vec![
///     tab("Home", "house", text("home page")),
///     tab("Settings", "gear", text("settings page")),
/// ]);
/// ```
pub fn tab_view_tabs(tabs: Vec<View>) -> View {
    let handles: Vec<_> = tabs.into_iter().map(|t| t.into_handle()).collect();
    View::new(views::tab_view_tabs(&handles))
}

/// `Stepper(_:onIncrement:onDecrement:)` — a stepper driven by callbacks.
///
/// [`stepper_bound`] binds a number and a range, which is right when there is a
/// number to bind. A stepper that adds and removes rows, or nudges something
/// the Rust side computes, has no such number — and there was no way to ask for
/// one.
///
/// `None` for either half greys that side out, which is how SwiftUI says "you
/// cannot go further this way".
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// let rows = stepper_actions(
///     "Rows",
///     Some(Box::new(|| println!("more"))),
///     Some(Box::new(|| println!("fewer"))),
/// );
/// ```
pub fn stepper_actions(
    label: &str,
    on_increment: Option<Box<dyn Fn()>>,
    on_decrement: Option<Box<dyn Fn()>>,
) -> View {
    View::new(views::stepper_actions(label, on_increment, on_decrement))
}

/// `Toggle(isOn:) { label }` — a toggle whose label is any view.
///
/// [`toggle_bound`] takes a string, which becomes a `Text`. The convenience
/// that takes a symbol name — `Toggle(_:systemImage:isOn:)` — is inlinable and
/// exports nothing, so it cannot be called; but it only builds a `Label`, and
/// this takes any view at all, so the same row is reachable and any other label
/// with it.
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// # use swiftui_native::views::BoundState;
/// let wifi = BoundState::new(true);
/// let row = toggle_labelled(label("Wi-Fi", "wifi"), &wifi);
/// ```
pub fn toggle_labelled(label: View, state: &views::BoundState<bool>) -> View {
    View::new(views::toggle_labelled(label.handle(), state))
}

/// `DatePicker(_:selection:in:displayedComponents:)` — a date picker with
/// bounds.
///
/// "Pick a date after today" is a constraint a date picker exists to express,
/// and only the unbounded initialiser was bound — so every picker offered every
/// date and the check had to happen afterwards.
///
/// The bounds are seconds from Apple's reference date, the same scale
/// [`date_picker_bound`] takes.
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// # use swiftui_native::views::BoundState;
/// let when = BoundState::new(500_000.0);
/// let picker = date_picker_range("When", &when, 0.0, 1_000_000.0);
/// ```
pub fn date_picker_range(
    title: &str,
    state: &views::BoundState<f64>,
    lower: f64,
    upper: f64,
) -> View {
    View::new(views::date_picker_range(title, state, lower, upper))
}

/// `Toggle(_:sources:isOn:)` — one toggle over several bindings.
///
/// The "select all" row at the top of a settings group: it reads *mixed* when
/// the sources disagree, and setting it sets every one of them. There was no
/// way to express that — a toggle took exactly one binding, so the mixed state
/// had to be faked with a third value that nothing wrote back to.
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// # use swiftui_native::views::BoundState;
/// let wifi = BoundState::new(true);
/// let bluetooth = BoundState::new(false);
/// let all = toggle_sources("All", &[&wifi, &bluetooth]);
/// ```
pub fn toggle_sources(label: &str, states: &[&views::BoundState<bool>]) -> View {
    View::new(views::toggle_sources(label, states))
}

/// `Group { … }` — several views where one is wanted, with no layout of its own.
pub fn group(content: View) -> View {
    View::new(views::group(content.handle()))
}

/// `ControlGroup { … }`
pub fn control_group(content: View) -> View {
    View::new(views::control_group(content.handle()))
}

/// `Menu(_:) { … }`
pub fn menu(label: &str, content: View) -> View {
    View::new(views::menu(label, content.handle()))
}

/// `Link(_:destination:)` — opens a URL.
pub fn link(title: &str, destination: &str) -> View {
    View::new(views::link(title, destination))
}

/// `ShareLink(item:)` over a URL.
pub fn share_link(url: &str) -> View {
    View::new(views::share_link_url(url))
}

/// `Gauge(value:in:) { label }`
pub fn gauge(value: f64, lower: f64, upper: f64, label: View) -> View {
    View::new(views::gauge(value, lower, upper, label.handle()))
}

/// `ViewThatFits(in:) { … }` — the first child that fits, along the given axes.
pub fn view_that_fits(content: View, axes: &[views::AxisSet]) -> View {
    View::new(views::view_that_fits(content.handle(), axes))
}

/// `NavigationSplitView { sidebar } detail: { detail }`
pub fn navigation_split_view(sidebar: View, detail: View) -> View {
    View::new(views::navigation_split_view(sidebar.handle(), detail.handle()))
}

/// `NavigationSplitView { sidebar } content: { content } detail: { detail }`
///
/// The three-column shape — a sidebar, a list, and the selected item — which is
/// what a Mail or Notes window is. [`navigation_split_view`] pins the middle
/// column to `EmptyView`, so it could not be filled at all.
pub fn navigation_split_view3(sidebar: View, content: View, detail: View) -> View {
    View::new(views::navigation_split_view3(
        sidebar.handle(),
        content.handle(),
        detail.handle(),
    ))
}

/// `OutlineGroup(_:children:)` over an `Int` root.
pub fn outline_group(root: i64, leaf: View) -> View {
    View::new(views::outline_group(root, leaf.handle()))
}

/// `TextEditor(text:)` showing a fixed string, which the user cannot edit.
///
/// As with [`textfield`], the string becomes a `Binding.constant` and SwiftUI
/// treats that as read-only.
pub fn text_editor(value: &str) -> View {
    View::new(views::text_editor(value))
}

/// `EditButton()` — iOS only; on macOS SwiftUI traps if it is reached.
#[cfg(not(target_os = "macos"))]
pub fn edit_button() -> View {
    View::new(views::edit_button())
}

/// `Button { action } label: { … }` — a button whose label is a view rather
/// than a string.
pub fn button_labelled(label: View, action: impl Fn() + 'static) -> View {
    View::new(views::button_labelled(label.handle(), action))
}

/// `VStack(spacing:) { … }`.
pub fn vstack_spacing(children: &[View], spacing: f64) -> View {
    View::new(views::vstack_spacing(&handles(children), spacing))
}

/// `HStack(spacing:) { … }`.
pub fn hstack_spacing(children: &[View], spacing: f64) -> View {
    View::new(views::hstack_spacing(&handles(children), spacing))
}

/// `ZStack(alignment:) { … }`.
pub fn zstack_aligned(children: &[View], alignment: views::Alignment) -> View {
    View::new(views::zstack_aligned(&handles(children), alignment))
}

pub fn hstack(children: &[View]) -> View {
    let handles: Vec<ViewHandle> = children.iter().map(|v| v.handle.clone()).collect();
    View::new(views::hstack(&handles))
}

/// Create a `ZStack`.
pub fn zstack(children: &[View]) -> View {
    let handles: Vec<ViewHandle> = children.iter().map(|v| v.handle.clone()).collect();
    View::new(views::zstack(&handles))
}

/// Create a `Button`.
pub fn button(label: &str, action: impl Fn() + 'static) -> View {
    View::new(views::button(label, action))
}

/// Create a `Toggle`.
pub fn toggle(label: &str, is_on: bool) -> View {
    View::new(views::toggle(label, is_on))
}

/// Create a `Toggle` wired to Rust state, readable and writable from both sides.
pub fn toggle_bound(label: &str, state: &views::BoundState<bool>) -> View {
    View::new(views::toggle_bound(label, state))
}

/// Create a `TextField` showing a fixed string, which the user cannot edit.
///
/// The string becomes a `Binding.constant`, so keystrokes have nowhere to go
/// and the field ignores them. [`textfield_bound`] is the editable one.
pub fn textfield(placeholder: &str, value: &str) -> View {
    View::new(views::textfield(placeholder, value))
}

/// Create a `TextField` wired to Rust state — every keystroke writes into it.
pub fn textfield_bound(placeholder: &str, state: &views::BoundState<String>) -> View {
    View::new(views::textfield_bound(placeholder, state))
}

/// `TextField(_:text:axis:)` — a field that grows along `axis` as it is typed
/// into.
///
/// `Axis::Vertical` is the multi-line one: it starts a line high and adds rows
/// as the text wraps, which is what a comment box or a note is. Only the
/// deprecated `onEditingChanged:onCommit:` initialiser was bound, so every
/// field was one line whatever went in it.
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// # use swiftui_native::views::{Axis, BoundState};
/// let note = BoundState::new(String::new());
/// let field = textfield_axis("Note", &note, Axis::Vertical);
/// ```
pub fn textfield_axis(
    placeholder: &str,
    state: &views::BoundState<String>,
    axis: views::Axis,
) -> View {
    View::new(views::textfield_axis(placeholder, state, axis))
}

/// Create a `SecureField` showing a fixed string, which the user cannot edit.
/// See [`securefield_bound`].
pub fn securefield(placeholder: &str, value: &str) -> View {
    View::new(views::securefield(placeholder, value))
}

/// Create a `SecureField` wired to Rust state — every keystroke writes into it.
pub fn securefield_bound(placeholder: &str, state: &views::BoundState<String>) -> View {
    View::new(views::securefield_bound(placeholder, state))
}

/// Create a `Slider` showing a fixed value, which the user cannot move.
///
/// The value becomes a `Binding.constant` and SwiftUI treats that as read-only.
/// [`slider_bound`] is the one that can be dragged.
pub fn slider(value: f64, lower: f64, upper: f64) -> View {
    View::new(views::slider(value, lower, upper))
}

/// Create a `Slider` wired to Rust state, readable and writable from both sides.
pub fn slider_bound(state: &views::BoundState<f64>, lower: f64, upper: f64) -> View {
    View::new(views::slider_bound(state, lower, upper))
}

/// `Slider(value:in:step:)` — a slider that snaps to multiples of `step`.
///
/// A continuous slider is right for a volume and wrong for a rating out of
/// five; only the continuous one was bound.
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// # use swiftui_native::views::BoundState;
/// let rating = BoundState::new(3.0);
/// let stars = slider_step_bound(&rating, 0.0, 5.0, 1.0);
/// ```
pub fn slider_step_bound(
    state: &views::BoundState<f64>,
    lower: f64,
    upper: f64,
    step: f64,
) -> View {
    View::new(views::slider_step_bound(state, lower, upper, step))
}

/// Create a `Picker` over `content`, showing a fixed selection the user cannot
/// change. See [`picker_bound()`].
pub fn picker(title: &str, selection: i64, content: View) -> View {
    View::new(views::picker(title, selection, content.handle()))
}

/// Create a `Picker` wired to Rust state — choosing a row writes its tag into
/// `state`.
///
/// The rows are tagged with [`View::tag`]; the tag is what lands in `state`.
pub fn picker_bound(title: &str, state: &views::BoundState<i64>, content: View) -> View {
    View::new(views::picker_bound(title, state, content.handle()))
}

/// Create a `DatePicker` showing a fixed date the user cannot change, as
/// seconds since the reference date. See [`date_picker_bound`].
pub fn date_picker(title: &str, interval: f64) -> View {
    View::new(views::date_picker(title, interval))
}

/// Create a `DatePicker` wired to Rust state, in seconds since the reference date.
pub fn date_picker_bound(title: &str, state: &views::BoundState<f64>) -> View {
    View::new(views::date_picker_bound(title, state))
}

/// Create a `ColorPicker` showing a fixed colour the user cannot change.
/// See [`color_picker_bound`].
pub fn color_picker(title: &str, color: Color, supports_opacity: bool) -> View {
    View::new(views::color_picker(title, color, supports_opacity))
}

/// Create a `ColorPicker` wired to Rust state.
///
/// The state holds the colour as the single reference `Color` is — what
/// [`views::color_value_of`] returns — because that is what the binding reads
/// and writes. `Color` is a class instance, not a struct of components, so
/// there is no triple to store.
pub fn color_picker_bound(
    title: &str,
    state: &views::BoundState<u64>,
    supports_opacity: bool,
) -> View {
    View::new(views::color_picker_bound(title, state, supports_opacity))
}

/// Create a `ProgressView`.
pub fn progress(value: f64, total: f64) -> View {
    View::new(views::progress(value, total))
}

/// Create a `Label(_:systemImage:)`.
pub fn label(title: &str, system_image: &str) -> View {
    View::new(views::label(title, system_image))
}

/// `Rectangle()`
pub fn rectangle() -> View {
    View::new(views::rectangle())
}

/// Which transition a view uses when it appears or leaves.
// `Eq` is gone from the derive: two of these carry an `f64`, and floats have no
// total equality to derive one from.
#[derive(Clone, Copy, PartialEq, Debug)]
pub enum Transition {
    /// `.opacity` — fade.
    Opacity,
    /// `.slide` — in from the leading edge, out to the trailing.
    Slide,
    /// `.scale(scale:anchor:)` — grow from a unit point.
    Scale { scale: f64, anchor: (f64, f64) },
    /// `.scale(…).combined(with: .opacity)` — the pair SwiftUI's own
    /// `.scale` transitions are usually written with, since scaling from
    /// nothing without fading looks like a pop.
    ScaleWithOpacity { scale: f64, anchor: (f64, f64) },
    /// `.scale` — the bare static property, which is `Scale` with SwiftUI's
    /// own factor and anchor rather than ones given here.
    ScaleDefault,
    /// `.identity` — no transition, and not the same as no modifier: this
    /// overrides one a container would otherwise hand down.
    Identity,
}

/// A shape, before it is given something to draw with.
///
/// `Circle()` is a `Shape`, not yet a `View`: SwiftUI gives it a default fill
/// when one is used as a view, and `.fill()` says what to use instead. Keeping
/// that distinction here is what lets `circle().fill(.red)` build the type the
/// same line of Swift builds, rather than a `Circle` with a foreground style
/// over it.
pub struct Shape {
    inner: views::Shape,
}

impl Shape {
    /// `.fill(_)` — draw the shape in one colour.
    pub fn fill(self, c: Color) -> View {
        View::new(self.inner.fill(views::color_value_of(c)))
    }

    /// `.fill(_)` with one of SwiftUI's own colours.
    ///
    /// `.blue` is not a fixed triple: it is `(0, 0.569, 1)` on the Mac and
    /// `#007AFF` on iOS, and it changes again in dark appearance. Naming the
    /// colour asks SwiftUI for whichever one is right, where spelling out
    /// components picks one platform's answer and freezes it.
    pub fn fill_system(self, c: views::SystemColor) -> View {
        View::new(self.inner.fill(views::system_color_value(c)))
    }

    /// The shape as a view, with SwiftUI's default fill.
    pub fn view(self) -> View {
        View::new(self.inner.fill(views::color_value_of(Color::BLACK)))
    }

    /// `.stroke(_:lineWidth:)` — the outline instead of the fill.
    pub fn stroke(self, c: Color, line_width: f64) -> View {
        View::new(self.inner.stroke(views::color_value_of(c), line_width))
    }

    /// `.stroke(_:lineWidth:)` with one of SwiftUI's own colours.
    pub fn stroke_system(self, c: views::SystemColor, line_width: f64) -> View {
        View::new(self.inner.stroke(views::system_color_value(c), line_width))
    }

    /// `.fill(_).stroke(_, lineWidth:)` — both at once, which a shape cannot
    /// express by chaining because `.fill` already produces a view.
    ///
    /// Works on transformed shapes too: `.inset(2)` gives a `Circle._Inset`,
    /// which this now spells correctly. It used to assert, because
    /// `inset(by:)` returns `some InsettableShape` and the binding kept the
    /// shape it started as — so the result was named `StrokeShapeView<Circle,
    /// …>`, a type that exists, is the wrong one, and is laid out differently.
    ///
    /// The field offsets are still computed by padding each to eight rather
    /// than read from the metadata, and still checked against the type's own
    /// size before anything is written.
    pub fn fill_then_stroke(self, fill: Color, stroke: Color, line_width: f64) -> View {
        // The result is `StrokeShapeView<S, Color, _ShapeView<S, Color>>`, which
        // has to be spelled with whatever this shape actually is — after
        // `.inset` or `.rotation` that is no longer what it started as, which is
        // why the shape carries its own `mangle::Type`.
        use crate::mangle;
        let shape = self.inner.ty().clone();
        let color = mangle::ty("Color");
        let filled = mangle::ty("_ShapeView").of(vec![shape.clone(), color.clone()]);
        let result = mangle::ty("StrokeShapeView").of(vec![shape, color, filled]).mangle();
        View::new(views::fill_then_stroke(
            &self.inner,
            views::color_value_of(fill),
            views::color_value_of(stroke),
            line_width,
            result.as_bytes(),
        ))
    }

    /// `.fill(_).strokeBorder(_, lineWidth:)` — filled, then bordered *inside*
    /// its own edge.
    ///
    /// The difference from [`fill_then_stroke`](Self::fill_then_stroke) is
    /// where the line sits: a stroke straddles the edge and a border is drawn
    /// within it, so a bordered shape never paints outside its bounds.
    pub fn fill_then_stroke_border(self, fill: Color, border: Color, line_width: f64) -> View {
        use crate::mangle;
        // `StrokeBorderShapeView<Shape, Style, Background>` — the third
        // parameter is what goes *behind*, which here is the filled shape, the
        // same way `strokeBorder` alone puts an `EmptyView` there.
        let shape = self.inner.ty().clone();
        let color = mangle::ty("Color");
        let filled = mangle::ty("_ShapeView").of(vec![shape.clone(), color.clone()]);
        let result = mangle::ty("StrokeBorderShapeView")
            .of(vec![shape, color, filled])
            .mangle();
        View::new(views::fill_then_stroke_border(
            &self.inner,
            views::color_value_of(fill),
            views::color_value_of(border),
            line_width,
            result.as_bytes(),
        ))
    }

    /// `.stroke(lineWidth:)` — outlined in the inherited foreground style,
    /// which is what picks up an enclosing `.foregroundStyle`.
    pub fn stroke_default(self, line_width: f64) -> View {
        View::new(self.inner.stroke_default(line_width))
    }

    /// `.trim(from:to:)` — keep a fraction of the path, as unit fractions.
    ///
    /// How a progress ring is drawn: a stroked circle trimmed to the fraction
    /// complete, usually with `.rotate(-90.0)` after it so the arc starts at the
    /// top rather than at three o'clock. Without it a "ring showing 70%" is a
    /// full circle.
    pub fn trim(self, from: f64, to: f64) -> Self {
        Self { inner: self.inner.trim(from, to) }
    }

    /// `.inset(by:)` — still a shape, so it can be filled or stroked after.
    ///
    /// Insetting before stroking is how you keep a `lineWidth` inside the
    /// frame; stroking alone centres the line on the edge and spills half of it.
    pub fn inset(self, amount: f64) -> Self {
        Self { inner: self.inner.inset(amount) }
    }

    /// `.offset(x:y:)` on the shape itself, before it is filled.
    pub fn offset(self, x: f64, y: f64) -> Self {
        Self { inner: self.inner.offset(x, y) }
    }

    /// `.rotation(.degrees(_))` on the shape's path.
    pub fn rotation(self, degrees: f64) -> Self {
        Self { inner: self.inner.rotation(degrees) }
    }
}

impl IntoView for Shape {
    fn into_view(self) -> View {
        self.view()
    }
}

/// A SwiftUI `Image`, before it becomes a view.
///
/// The same reason [`Shape`] exists: `Image` has modifiers of its own that
/// return `Image` — `.resizable()`, `.renderingMode(_:)`,
/// `.symbolRenderingMode(_:)` — and going through the `View` extensions instead
/// wraps it in a `ModifiedContent` and changes the type. Reaching them means
/// keeping the `Image` around rather than turning it into a view straight away.
pub struct Image {
    inner: views::Image,
}

impl Image {
    /// `.resizable()`, with the zero cap insets Swift source gets from the bare
    /// call.
    pub fn resizable(self) -> Self {
        Self { inner: self.inner.resizable(views::ResizingMode::Stretch) }
    }

    /// `.resizable(resizingMode:)`
    pub fn resizable_mode(self, mode: views::ResizingMode) -> Self {
        Self { inner: self.inner.resizable(mode) }
    }

    /// `.renderingMode(_:)` — `None` restores the default.
    pub fn rendering_mode(self, mode: Option<views::TemplateRenderingMode>) -> Self {
        Self { inner: self.inner.rendering_mode(mode) }
    }

    /// `.symbolRenderingMode(_:)`
    pub fn symbol_rendering_mode(self, mode: Option<views::SymbolRenderingMode>) -> Self {
        Self { inner: self.inner.symbol_rendering_mode(mode) }
    }

    /// `.antialiased(_:)`
    pub fn antialiased(self, on: bool) -> Self {
        Self { inner: self.inner.antialiased(on) }
    }

    /// The image as a view, so the `View` modifiers can be chained after.
    pub fn view(self) -> View {
        View::new(self.inner.view())
    }
}

impl IntoView for Image {
    fn into_view(self) -> View {
        self.view()
    }
}

/// `Image(systemName:)`, kept as an `Image` so its own modifiers are reachable.
pub fn system_image(name: &str) -> Image {
    Image { inner: views::Image::system(name) }
}

/// `Image(_:)` — a named asset, kept as an `Image`.
pub fn named_image(name: &str) -> Image {
    Image { inner: views::Image::named(name) }
}

/// `Circle()`, ready to be filled.
pub fn circle_shape() -> Shape {
    Shape { inner: views::Shape::circle() }
}

/// `Capsule()`, ready to be filled.
pub fn capsule_shape() -> Shape {
    Shape { inner: views::Shape::capsule() }
}

/// `Rectangle()`, ready to be filled.
pub fn rectangle_shape() -> Shape {
    Shape { inner: views::Shape::rectangle() }
}

/// `RoundedRectangle(cornerRadius:)`, ready to be filled.
pub fn rounded_rectangle_shape(radius: f64) -> Shape {
    Shape { inner: views::Shape::rounded_rectangle(radius, true) }
}

/// `RoundedRectangle(cornerRadius:style:)` — `false` gives the circular arc
/// rather than Swift's default squircle.
pub fn rounded_rectangle_shape_styled(radius: f64, continuous: bool) -> Shape {
    Shape { inner: views::Shape::rounded_rectangle(radius, continuous) }
}

/// `Ellipse()`, ready to be filled.
pub fn ellipse_shape() -> Shape {
    Shape { inner: views::Shape::ellipse() }
}

/// `Circle()`
pub fn circle() -> View {
    View::new(views::circle())
}

/// `Ellipse()`
pub fn ellipse() -> View {
    View::new(views::ellipse())
}

/// `Capsule()`
pub fn capsule() -> View {
    View::new(views::capsule())
}

/// `RoundedRectangle(cornerRadius:)`
pub fn rounded_rectangle(radius: f64) -> View {
    View::new(views::rounded_rectangle(radius))
}

/// `ForEach(0..<count) { … }`.
pub fn for_each<R: views::ForEachRange, V: IntoView>(
    range: R,
    builder: impl Fn(i64) -> V + 'static,
) -> View {
    View::new(views::for_each(range, move |i| builder(i).into_view().into_handle()))
}

/// `ScrollView { … }` — a vertical scroll view with indicators.
///
/// Named for what the macro derives from `ScrollView`, so the spelling in a
/// `swiftui!` body and the one here are the same word.
pub fn scroll_view(content: View) -> View {
    View::new(views::scroll(content.handle()))
}

/// `GeometryReader { … }`
/// `ForEach` over a Rust collection.
///
/// The common case, and the one `for_each` makes awkward: with only a range, a
/// caller writes `for_each(0..items.len() as i64, …)` and indexes back into the
/// slice, which is the loop SwiftUI was supposed to be writing.
///
/// Identity is still positional — this builds on `ForEach(0..<count)`, so
/// inserting in the middle makes SwiftUI treat every later row as changed rather
/// than moved, exactly as the Swift spelling would.
pub fn for_each_items<T: Clone + 'static, V: IntoView>(
    items: &[T],
    builder: impl Fn(&T) -> V + 'static,
) -> View {
    View::new(views::for_each_items(items, move |t| builder(t).into_view().into_handle()))
}

/// A view whose content is a function of the environment.
///
/// What `@Environment` is for, without having to be a view *type*: the closure is
/// handed the live `EnvironmentValues` and returns whatever it wants to build from
/// them. Reading a key declared here is
/// [`value_for`](views::EnvironmentValues::value_for), which is typed by the key.
///
/// ```no_run
/// # use swiftui_native::{environment_keys, prelude::*};
/// environment_keys! { depth: i64 = 0 }
///
/// # fn body() -> View {
/// environment_reader(|env| text(&format!("{} deep", env.value_for(depth()))))
/// # }
/// ```
pub fn environment_reader<V: IntoView>(
    builder: impl Fn(views::EnvironmentValues) -> V + 'static,
) -> View {
    View::new(views::environment_reader(move |env| {
        builder(env).into_view().into_handle()
    }))
}

pub fn geometry_reader<V: IntoView>(builder: impl Fn(f64, f64) -> V + 'static) -> View {
    View::new(views::geometry_reader(move |w, h| builder(w, h).into_view().into_handle()))
}

/// `NavigationLink(_:destination:)`
/// `NavigationLink(destination:) { label }` — a link whose label is a view.
///
/// What a list row is: a whole subtree, not a string. See [`navigation_link`]
/// for the string form.
pub fn navigation_link_labelled(label: View, destination: View) -> View {
    View::new(views::navigation_link_labelled(label.handle(), destination.handle()))
}

pub fn navigation_link(label: &str, destination: View) -> View {
    View::new(views::navigation_link(label, destination.handle()))
}

/// A `ViewBuilder` `if`/`else`, preserving branch identity.
pub fn conditional(flag: bool, if_true: View, if_false: View) -> View {
    View::new(views::conditional(flag, if_true.handle(), if_false.handle()))
}

/// `TimelineView(.animation) { … }` — rebuild on SwiftUI's clock so that Rust
/// state changes appear without an explicit redisplay.
pub fn timeline<V: IntoView>(builder: impl Fn() -> V + 'static) -> View {
    View::new(views::timeline(move || builder().into_view().into_handle()))
}

/// `List(ids, id: \.self) { id in … }` — rows identified by value.
///
/// [`list`](fn@list) and the [`list!`](crate::list) macro identify rows by
/// *position*,
/// because everything under them is built on `ForEach(0..<n)`. Insert a row at
/// the front and SwiftUI sees every later row as changed rather than moved: no
/// move animation, and per-row state follows the index instead of the row. That
/// is the same semantics as writing `ForEach(0..<n)` in Swift, and it is the
/// wrong semantics for a list of things.
///
/// Here the identifiers are the data. Moving an id moves its row; removing one
/// removes that row and not the last.
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// let ids = [10, 20, 30];
/// let rows = list_identified(&ids, |id| text(&format!("row {id}")));
/// ```
pub fn list_identified<V: IntoView>(ids: &[i64], builder: impl Fn(i64) -> V + 'static) -> View {
    View::new(views::list_identified(ids, move |id| builder(id).into_view().into_handle()))
}

/// `List(names, id: \.self) { name in … }` — the same, keyed by `String`.
///
/// Which is what most lists key on: an identifier is usually a name or a UUID
/// string, and turning one into an integer to get identity back would defeat
/// the point.
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// let rows = list_identified_str(&["alpha", "beta"], |id| text(id));
/// ```
pub fn list_identified_str<V: IntoView>(
    ids: &[&str],
    builder: impl Fn(&str) -> V + 'static,
) -> View {
    View::new(views::list_identified_str(ids, move |id| {
        builder(id).into_view().into_handle()
    }))
}

/// `List { … }`
pub fn list(child: View) -> View {
    View::new(views::list(child.handle()))
}

/// `Form { … }`
pub fn form(child: View) -> View {
    View::new(views::form(child.handle()))
}

/// `GroupBox { … }`
pub fn group_box(child: View) -> View {
    View::new(views::group_box(child.handle()))
}

/// `TabView { … }`
pub fn tab_view(child: View) -> View {
    View::new(views::tab_view(child.handle()))
}

/// `NavigationStack { … }`
pub fn navigation_stack(child: View) -> View {
    View::new(views::navigation_stack(child.handle()))
}

/// `DisclosureGroup(_:content:)`
pub fn disclosure_group(label: &str, child: View) -> View {
    View::new(views::disclosure_group(label, child.handle()))
}

/// A layout written in Rust, given children — `MyLayout { … }`.
///
/// ```no_run
/// # use swiftui_native::prelude::*;
/// # use swiftui_native::views::{Proposal, Rect, Subviews};
/// let row = layout(
///     |s: &Subviews<'_>, _| (s.len() as f64 * 44.0, 44.0),
///     |s: &Subviews<'_>, b: Rect, _| {
///         for i in 0..s.len() {
///             s.place(i, b.x + i as f64 * 44.0, b.y);
///         }
///     },
/// );
/// laid_out(&row, &[text("a"), text("b")]);
/// ```
pub fn laid_out(layout: &views::CustomLayout, children: &[View]) -> View {
    View::new(views::custom_layout(layout, &handles(children)))
}

/// Build a layout from a sizing pass and a placement pass.
///
/// For a layout with parameters, implement [`views::LayoutAlgorithm`] on a
/// type and hand it to [`views::register`] instead.
pub fn layout(
    size: impl Fn(&views::Subviews<'_>, views::Proposal) -> (f64, f64) + Send + Sync + 'static,
    place: impl Fn(&views::Subviews<'_>, views::Rect, views::Proposal) + Send + Sync + 'static,
) -> views::CustomLayout {
    views::layout(size, place)
}

/// `Grid { … }` over rows.
pub fn grid(rows: &[View]) -> View {
    let handles: Vec<ViewHandle> = rows.iter().map(|v| v.handle.clone()).collect();
    View::new(views::grid(&handles))
}

/// `GridRow { … }`
pub fn grid_row(children: &[View]) -> View {
    let handles: Vec<ViewHandle> = children.iter().map(|v| v.handle.clone()).collect();
    View::new(views::grid_row(&handles))
}

/// `GridRow(alignment:) { … }` — this row's own vertical alignment, which
/// overrides the grid's for the row alone.
pub fn grid_row_aligned(children: &[View], alignment: views::VerticalAlignment) -> View {
    let handles: Vec<ViewHandle> = children.iter().map(|v| v.handle.clone()).collect();
    View::new(views::grid_row_aligned(&handles, alignment))
}

/// Create a `Stepper`.
pub fn stepper(label: &str, value: f64, lower: f64, upper: f64, step: f64) -> View {
    View::new(views::stepper(label, value, lower, upper, step))
}

/// Create a `Stepper` wired to Rust state — the `+`/`−` buttons write back.
pub fn stepper_bound(
    label: &str,
    state: &views::BoundState<f64>,
    lower: f64,
    upper: f64,
    step: f64,
) -> View {
    View::new(views::stepper_bound(label, state, lower, upper, step))
}

/// Create a `LazyVStack`.
pub fn lazy_vstack(children: &[View]) -> View {
    let handles: Vec<ViewHandle> = children.iter().map(|v| v.handle.clone()).collect();
    View::new(views::lazy_vstack(&handles))
}

/// `LazyVStack(alignment:)`.
pub fn lazy_vstack_aligned(children: &[View], alignment: views::HorizontalAlignment) -> View {
    let handles: Vec<ViewHandle> = children.iter().map(|v| v.handle.clone()).collect();
    View::new(views::lazy_vstack_aligned(&handles, alignment))
}

/// Create a `LazyHStack`.
pub fn lazy_hstack(children: &[View]) -> View {
    let handles: Vec<ViewHandle> = children.iter().map(|v| v.handle.clone()).collect();
    View::new(views::lazy_hstack(&handles))
}

/// `LazyHStack(alignment:)`.
pub fn lazy_hstack_aligned(children: &[View], alignment: views::VerticalAlignment) -> View {
    let handles: Vec<ViewHandle> = children.iter().map(|v| v.handle.clone()).collect();
    View::new(views::lazy_hstack_aligned(&handles, alignment))
}