swiftui_native/view/

layout.rs

//! Size, position and how a view sits among its neighbours.
//!
//! Part of [`crate::view::View`]'s chainable API; Rust allows a type's
//! inherent methods to be split across modules, and 400 of them in one file
//! was a file nobody could find anything in.

use super::{Color, Transition, View};
use crate::views;

impl View {
    // ── Size and frame ──

    /// Apply `.padding(_:)`.
    pub fn padding(self, amount: f64) -> Self {
        Self::new(views::padding(&self.handle, amount))
    }

    /// `.padding(_:_:)` on chosen edges — `.padding(.horizontal, 8)`.
    ///
    /// `None` asks for SwiftUI's own default inset rather than a number.
    pub fn padding_edges(self, edges: views::EdgeSet, length: Option<f64>) -> Self {
        Self::new(views::padding_set(&self.handle, edges, length))
    }

    /// `.padding()` — the system's default inset on every edge.
    pub fn padding_default(self) -> Self {
        Self::new(views::padding_default(&self.handle))
    }

    /// `.frame(width:height:alignment:)` with either dimension left out.
    ///
    /// An omitted dimension is not zero: it means "take what the parent offers",
    /// which is a different layout from asking for nothing.
    pub fn frame_optional(
        self,
        width: Option<f64>,
        height: Option<f64>,
        alignment: views::Alignment,
    ) -> Self {
        Self::new(views::frame_optional(&self.handle, width, height, alignment))
    }

    /// `.frame(maxWidth: .infinity, maxHeight: .infinity)` — fill the parent.
    pub fn expand(self, alignment: views::Alignment) -> Self {
        Self::new(views::frame_max_infinity(&self.handle, alignment))
    }

    /// `.frame(maxWidth: .infinity)` — fill across, keep the natural height.
    pub fn expand_width(self, alignment: views::Alignment) -> Self {
        Self::new(views::frame_max_width(&self.handle, alignment))
    }

    /// `.frame(width:height:alignment:)`.
    pub fn frame_aligned(self, w: f64, h: f64, alignment: views::Alignment) -> Self {
        Self::new(views::frame_aligned(&self.handle, w, h, alignment))
    }

    /// Apply `.frame(width:height:)`.
    pub fn frame(self, w: f64, h: f64) -> Self {
        Self::new(views::frame(&self.handle, w, h))
    }

    // ── Compositing ──

    /// `.clipShape(Circle())`
    pub fn clip_circle(self) -> Self {
        Self::new(views::clip_circle(&self.handle))
    }

    /// `.clipShape(Capsule())`
    pub fn clip_capsule(self) -> Self {
        Self::new(views::clip_capsule(&self.handle))
    }

    /// `.clipShape(Capsule(style:))` — `false` gives the circular arc.
    pub fn clip_capsule_styled(self, continuous: bool) -> Self {
        Self::new(views::clip_capsule_styled(&self.handle, continuous))
    }

    /// `.clipShape(RoundedRectangle(cornerRadius:style:))` — `.continuous` is
    /// the squircle Apple's own UI uses, and it is visibly not a circular arc.
    pub fn clip_rounded_styled(self, radius: f64, continuous: bool) -> Self {
        Self::new(views::clip_rounded_rect_styled(&self.handle, radius, continuous))
    }

    /// `.clipShape(RoundedRectangle(cornerRadius:))`
    pub fn clip_rounded(self, radius: f64) -> Self {
        Self::new(views::clip_rounded_rect(&self.handle, radius))
    }

    /// `.overlay(alignment: .center) { … }`
    pub fn overlay(self, content: View) -> Self {
        Self::new(views::overlay(&self.handle, content.handle()))
    }

    /// `.overlay(alignment:content:)` — the same modifier as [`View::overlay`],
    /// which pins to the centre.
    pub fn overlay_aligned(self, content: View, alignment: views::Alignment) -> Self {
        Self::new(views::overlay_aligned(&self.handle, content.handle(), alignment))
    }

    /// `.mask(alignment: .center) { … }` — a `_MaskAlignmentEffect`.
    pub fn mask(self, content: View) -> Self {
        Self::new(views::mask(&self.handle, content.handle()))
    }

    /// `.mask(alignment:_:)` with an alignment other than the centre.
    pub fn mask_aligned(self, content: View, alignment: views::Alignment) -> Self {
        Self::new(views::mask_aligned(&self.handle, content.handle(), alignment))
    }

    /// `.mask(_:)` — the older, alignment-free overload, which is a
    /// `_MaskEffect`. A different type from [`View::mask`], not a shorthand
    /// for it.
    pub fn mask_plain(self, content: View) -> Self {
        Self::new(views::mask_plain(&self.handle, content.handle()))
    }

    /// `.aspectRatio(_:contentMode:)`
    pub fn aspect_ratio(self, ratio: f64, fill: bool) -> Self {
        Self::new(views::aspect_ratio(&self.handle, ratio, fill))
    }

    /// `.fixedSize(horizontal:vertical:)`
    pub fn fixed_size(self, horizontal: bool, vertical: bool) -> Self {
        Self::new(views::fixed_size(&self.handle, horizontal, vertical))
    }

    /// `.zIndex(_:)`
    pub fn z_index(self, value: f64) -> Self {
        Self::new(views::z_index(&self.handle, value))
    }

    /// `.disabled(_:)`
    pub fn disabled(self, value: bool) -> Self {
        Self::new(views::disabled(&self.handle, value))
    }

    /// `.hidden()`
    pub fn hidden(self) -> Self {
        Self::new(views::hidden(&self.handle))
    }

    /// `.blendMode(_:)`
    pub fn blend_mode(self, mode: u8) -> Self {
        Self::new(views::blend_mode(&self.handle, mode))
    }

    /// `.navigationTitle(_:)`
    pub fn navigation_title(self, title: &str) -> Self {
        Self::new(views::navigation_title(&self.handle, title))
    }

    /// `.navigationTitle(_:)` with a binding — an *editable* title.
    ///
    /// The title bar becomes a rename field: the user edits it in place and the
    /// new name is written back into Rust. Only the fixed-string overload was
    /// bound, so a document could be shown under a name but never renamed from
    /// where the name appears.
    ///
    /// ```no_run
    /// # use swiftui_native::prelude::*;
    /// # use swiftui_native::views::BoundState;
    /// let name = BoundState::new(String::from("Untitled"));
    /// let doc = text("body").navigation_title_bound(&name);
    /// ```
    pub fn navigation_title_bound(self, state: &views::BoundState<String>) -> Self {
        Self::new(views::navigation_title_bound(&self.handle, state))
    }

    /// `.navigationDestination(for: Int.self) { value in … }` — value-based
    /// routing.
    ///
    /// This is how a `NavigationStack` is driven in modern SwiftUI: rows push a
    /// *value*, and the stack asks this modifier what view that value means.
    /// Only the `isPresented:` overload was bound, which is the older
    /// one-destination-per-flag shape — fine for a single detail sheet, and no
    /// use for a stack that pushes rows.
    ///
    /// ```no_run
    /// # use swiftui_native::prelude::*;
    /// let stack = navigation_stack(
    ///     list_identified(&[1, 2, 3], |id| text(&format!("row {id}")))
    ///         .navigation_destination_for(|id| text(&format!("detail {id}"))),
    /// );
    /// ```
    pub fn navigation_destination_for<V: crate::view::IntoView>(
        self,
        destination: impl Fn(i64) -> V + 'static,
    ) -> Self {
        Self::new(views::navigation_destination_for(&self.handle, move |i| {
            destination(i).into_view().into_handle()
        }))
    }

    /// `.alert(_:isPresented:actions:)` with a fixed flag.
    ///
    /// The flag becomes a `Binding.constant`, which SwiftUI treats as
    /// read-only, so this alert cannot be dismissed — there is nowhere to write
    /// `false` back to. [`View::alert_bound`] is the one a user can close.
    pub fn alert(self, title: &str, presented: bool, actions: View) -> Self {
        Self::new(views::alert(&self.handle, title, actions.handle(), presented))
    }

    /// `.alert(_:isPresented:actions:)` bound to Rust state.
    ///
    /// Dismissing writes `false` into `state`, so Rust learns the alert closed
    /// without being told.
    pub fn alert_bound(
        self,
        title: &str,
        state: &views::BoundState<bool>,
        actions: View,
    ) -> Self {
        Self::new(views::alert_bound(&self.handle, title, actions.handle(), state))
    }

    /// `.alert(_:isPresented:actions:message:)` — an alert that explains itself.
    ///
    /// The message is the line under the title: what the buttons are about, and
    /// the difference between "Delete" and "Delete — this cannot be undone".
    /// Only the title-and-buttons overload was bound, so an alert could ask but
    /// not say why.
    ///
    /// ```no_run
    /// # use swiftui_native::prelude::*;
    /// # use swiftui_native::views::BoundState;
    /// let asking = BoundState::new(false);
    /// let page = text("Notes").alert_message_bound(
    ///     "Delete this?",
    ///     &asking,
    ///     button("Delete", || {}),
    ///     text("This cannot be undone."),
    /// );
    /// ```
    pub fn alert_message_bound(
        self,
        title: &str,
        state: &views::BoundState<bool>,
        actions: View,
        message: View,
    ) -> Self {
        Self::new(views::alert_message_bound(
            &self.handle,
            title,
            actions.handle(),
            message.handle(),
            state,
        ))
    }

    /// `.alert(_:isPresented:actions:message:)` with a fixed flag, which cannot
    /// be dismissed — see [`alert`](Self::alert).
    pub fn alert_message(
        self,
        title: &str,
        presented: bool,
        actions: View,
        message: View,
    ) -> Self {
        Self::new(views::alert_message(
            &self.handle,
            title,
            actions.handle(),
            message.handle(),
            presented,
        ))
    }

    /// `.confirmationDialog(_:isPresented:titleVisibility:actions:message:)`
    ///
    /// The message is the explanatory line under the title, and on a dialog it
    /// is often the only place the consequence is stated — "This deletes 12
    /// items" under a bare "Delete".
    pub fn confirmation_message_bound(
        self,
        title: &str,
        state: &views::BoundState<bool>,
        actions: View,
        message: View,
    ) -> Self {
        Self::new(views::confirmation_message_bound(
            &self.handle,
            title,
            actions.handle(),
            message.handle(),
            state,
        ))
    }

    /// `.sheet(isPresented:content:)` with a fixed flag — undismissable, as
    /// [`View::alert`] is. See [`View::sheet_bound`].
    pub fn sheet(self, presented: bool, content: View) -> Self {
        Self::new(views::sheet(&self.handle, content.handle(), presented))
    }

    /// `.sheet(isPresented:content:)` bound to Rust state, so a swipe down
    /// writes `false` back.
    pub fn sheet_bound(self, state: &views::BoundState<bool>, content: View) -> Self {
        Self::new(views::sheet_bound(&self.handle, content.handle(), state))
    }

    /// `.sheet(isPresented:onDismiss:content:)` — with a callback for the
    /// closing.
    ///
    /// A sheet that saves what was edited has to know when it was dismissed,
    /// and `onDismiss` was hardwired to `nil`, so the sheet could be opened and
    /// closed and nothing on the Rust side would hear about it.
    ///
    /// ```no_run
    /// # use swiftui_native::prelude::*;
    /// # use swiftui_native::views::BoundState;
    /// let editing = BoundState::new(false);
    /// let page = text("Notes").sheet_bound_dismiss(
    ///     &editing,
    ///     text("editor"),
    ///     || println!("saved"),
    /// );
    /// ```
    pub fn sheet_bound_dismiss(
        self,
        state: &views::BoundState<bool>,
        content: View,
        on_dismiss: impl Fn() + 'static,
    ) -> Self {
        Self::new(views::sheet_bound_dismiss(
            &self.handle,
            content.handle(),
            state,
            on_dismiss,
        ))
    }

    /// `.confirmationDialog(_:isPresented:actions:)` with a fixed flag —
    /// undismissable. See [`View::confirmation_dialog_bound`].
    pub fn confirmation_dialog(self, title: &str, presented: bool, actions: View) -> Self {
        Self::new(views::confirmation_dialog(&self.handle, title, actions.handle(), presented))
    }

    /// `.confirmationDialog(_:isPresented:actions:)` bound to Rust state.
    pub fn confirmation_dialog_bound(
        self,
        title: &str,
        state: &views::BoundState<bool>,
        actions: View,
    ) -> Self {
        Self::new(views::confirmation_dialog_bound(&self.handle, title, actions.handle(), state))
    }

    /// `.accessibilityLabel(_:)`
    pub fn a11y_label(self, label: &str) -> Self {
        Self::new(views::accessibility_label(&self.handle, label))
    }

    /// `.accessibilityHidden(_:)`
    pub fn a11y_hidden(self, hidden: bool) -> Self {
        Self::new(views::accessibility_hidden(&self.handle, hidden))
    }

    /// `.focusable(_:)`
    pub fn focusable(self, value: bool) -> Self {
        Self::new(views::focusable(&self.handle, value))
    }

    /// `.onDisappear(perform:)`
    pub fn on_disappear(self, action: impl Fn() + 'static) -> Self {
        Self::new(views::on_disappear(&self.handle, action))
    }

    /// `.gesture(LongPressGesture(...))`
    pub fn on_long_press(self, duration: f64, max_distance: f64) -> Self {
        Self::new(views::long_press_gesture(&self.handle, duration, max_distance))
    }

    /// `.onLongPressGesture(minimumDuration:maximumDistance:pressing:perform:)`
    ///
    /// Prefer this over [`on_long_press`](Self::on_long_press), which attaches
    /// the gesture with nothing listening.
    pub fn on_long_press_perform(self, duration: f64, max_distance: f64, action: impl Fn() + 'static) -> Self {
        Self::new(views::on_long_press_gesture(&self.handle, duration, max_distance, action))
    }

    /// `.clipped()`
    pub fn clipped(self) -> Self {
        Self::new(views::clipped(&self.handle))
    }

    /// `.compositingGroup()`
    pub fn compositing_group(self) -> Self {
        Self::new(views::compositing_group(&self.handle))
    }

    /// `.drawingGroup()` — flatten the subtree through Metal.
    pub fn drawing_group(self) -> Self {
        Self::new(views::drawing_group(&self.handle))
    }

    /// `.rotation3DEffect(_:axis:)`
    pub fn rotate_3d(self, degrees: f64, axis: (f64, f64, f64)) -> Self {
        Self::new(views::rotation_3d(&self.handle, degrees, axis.0, axis.1, axis.2))
    }

    /// `.gesture(DragGesture(...))`
    pub fn on_drag(self, minimum_distance: f64) -> Self {
        Self::new(views::drag_gesture(&self.handle, minimum_distance))
    }

    /// `.gesture(DragGesture(...).onEnded(_:))`
    ///
    /// Prefer this over [`on_drag`](Self::on_drag), which attaches the gesture
    /// with nothing listening.
    pub fn on_drag_ended(self, minimum_distance: f64, action: impl Fn() + 'static) -> Self {
        Self::new(views::on_drag_gesture(&self.handle, minimum_distance, action))
    }

    /// `.gesture(DragGesture(...).onEnded { value in … })`, with the value.
    ///
    /// [`on_drag_ended`](Self::on_drag_ended) tells the handler only *that* a
    /// drag ended. This one hands over where it started, where it finished and
    /// how fast it was moving — see [`views::DragValue`].
    ///
    /// ```no_run
    /// # use swiftui_native::prelude::*;
    /// let card = text("drag me").on_drag_value(1.0, |v| {
    ///     let (dx, dy) = v.translation();
    ///     println!("moved {dx} x {dy}");
    /// });
    /// ```
    pub fn on_drag_value(
        self,
        minimum_distance: f64,
        action: impl Fn(views::DragValue) + 'static,
    ) -> Self {
        Self::new(views::on_drag_ended_value(&self.handle, minimum_distance, action))
    }

    /// `.gesture(MagnifyGesture(...))`
    pub fn on_magnify(self, minimum_scale_delta: f64) -> Self {
        Self::new(views::magnify_gesture(&self.handle, minimum_scale_delta))
    }

    /// `.gesture(MagnifyGesture(...).onEnded { value in … })`
    ///
    /// [`on_magnify`](Self::on_magnify) attaches the gesture with nothing
    /// listening — it builds the value Swift would and can never be seen to
    /// fire. This one hands over the magnification, the velocity and where the
    /// pinch was centred; see [`views::MagnifyValue`].
    pub fn on_magnify_value(
        self,
        minimum_scale_delta: f64,
        action: impl Fn(views::MagnifyValue) + 'static,
    ) -> Self {
        Self::new(views::on_magnify_ended(&self.handle, minimum_scale_delta, action))
    }

    /// `.gesture(RotateGesture(...))`
    pub fn on_rotate(self, minimum_degrees: f64) -> Self {
        Self::new(views::rotate_gesture(&self.handle, minimum_degrees))
    }

    /// `.gesture(RotateGesture(...).onEnded { value in … })`
    ///
    /// As [`on_rotate`](Self::on_rotate), but the handler is told how far.
    /// `Angle` stores radians, so [`views::RotateValue::degrees`] converts
    /// rather than reading a second field.
    pub fn on_rotate_value(
        self,
        minimum_degrees: f64,
        action: impl Fn(views::RotateValue) + 'static,
    ) -> Self {
        Self::new(views::on_rotate_ended(&self.handle, minimum_degrees, action))
    }

    /// `.popover(isPresented:content:)` with a fixed flag — undismissable.
    /// See [`View::popover_bound`].
    pub fn popover(self, presented: bool, content: View) -> Self {
        Self::new(views::popover(&self.handle, content.handle(), presented))
    }

    /// `.popover(isPresented:content:)` bound to Rust state, so tapping outside
    /// writes `false` back.
    pub fn popover_bound(self, state: &views::BoundState<bool>, content: View) -> Self {
        Self::new(views::popover_bound(&self.handle, content.handle(), state))
    }

    /// `.onChange(of:_:)`, watching an `Int`.
    pub fn on_change(self, value: i64, handler: impl Fn(i64, i64) + 'static) -> Self {
        Self::new(views::on_change(&self.handle, value, handler))
    }

    /// `.onChange(of:initial:_:)` over a `String`.
    ///
    /// `onChange` is one of the modifiers an application reaches for most, and
    /// it could only watch an `Int` — a search term, a selected identifier, a
    /// mode name all had to be turned into a number first. Swift constrains the
    /// watched value to `Equatable` and nothing else.
    ///
    /// ```no_run
    /// # use swiftui_native::prelude::*;
    /// let v = text("results").on_change_str("query", |was, now| {
    ///     println!("search went from {was:?} to {now:?}");
    /// });
    /// ```
    pub fn on_change_str(
        self,
        value: &str,
        handler: impl Fn(String, String) + 'static,
    ) -> Self {
        Self::new(views::on_change_str(&self.handle, value, handler))
    }

    /// `.onChange(of:initial:_:)` over a `Bool`.
    pub fn on_change_bool(self, value: bool, handler: impl Fn(bool, bool) + 'static) -> Self {
        Self::new(views::on_change_bool(&self.handle, value, handler))
    }

    /// `.onChange(of:initial:_:)` over a `Double`.
    pub fn on_change_f64(self, value: f64, handler: impl Fn(f64, f64) + 'static) -> Self {
        Self::new(views::on_change_f64(&self.handle, value, handler))
    }

    /// `.toolbar { ToolbarItem { content } }`
    pub fn toolbar(self, content: View) -> Self {
        Self::new(views::toolbar(&self.handle, content.handle()))
    }

    /// `.toolbar(id:) { ToolbarItem(id:showsByDefault:) { content } }` — a
    /// toolbar the user can rearrange, remembered under `toolbar_id`.
    ///
    /// `shows_by_default` is whether the item is there before any
    /// customization; `false` leaves it in the palette until it is dragged in.
    pub fn toolbar_customizable(
        self,
        toolbar_id: &str,
        item_id: &str,
        shows_by_default: bool,
        content: View,
    ) -> Self {
        Self::new(views::toolbar_customizable(
            &self.handle,
            toolbar_id,
            item_id,
            shows_by_default,
            content.handle(),
        ))
    }

    /// `.transition(.opacity)`
    pub fn transition(self, kind: Transition) -> Self {
        Self::new(match kind {
            Transition::Opacity => views::transition_opacity(&self.handle),
            Transition::Slide => views::transition_slide(&self.handle),
            Transition::Scale { scale, anchor } => {
                views::transition(&self.handle, views::transition_scale(scale, anchor))
            }
            Transition::ScaleDefault => {
                views::transition(&self.handle, views::transition_scale_value())
            }
            Transition::Identity => {
                views::transition(&self.handle, views::transition_identity_value())
            }
            Transition::ScaleWithOpacity { scale, anchor } => views::transition(
                &self.handle,
                views::transition_combined(
                    views::transition_scale(scale, anchor),
                    views::transition_opacity_value(),
                ),
            ),
        })
    }

    /// `.id(_)` — the identity SwiftUI diffs against.
    ///
    /// Changing it replaces the view rather than updating it, which is what
    /// makes a transition play: the old identity leaves, the new one arrives.
    pub fn id(self, value: i64) -> Self {
        Self::new(views::id(&self.handle, views::HashableValue::Int(value)))
    }

    /// `.animation(.default, value:)`
    pub fn animation(self, value: i64) -> Self {
        Self::new(views::animation(&self.handle, value))
    }

    /// `.onAppear(perform:)`
    pub fn on_appear(self, action: impl Fn() + 'static) -> Self {
        Self::new(views::on_appear(&self.handle, action))
    }

    /// `.onTapGesture(count:perform:)`
    pub fn on_tap(self, action: impl Fn() + 'static) -> Self {
        Self::new(views::on_tap_gesture(&self.handle, 1, action))
    }

    /// `.contextMenu(menuItems:)`
    pub fn context_menu(self, items: View) -> Self {
        Self::new(views::context_menu(&self.handle, items.handle()))
    }

    /// `.contextMenu(menuItems:preview:)` — a menu with something to look at.
    ///
    /// The preview is what a long press enlarges before the menu appears: the
    /// row blown up, a photo, a card. [`context_menu`](Self::context_menu) has
    /// no such slot, so the menu came up over the view as it already was.
    ///
    /// ```no_run
    /// # use swiftui_native::prelude::*;
    /// let row = text("Photo").context_menu_preview(
    ///     button("Delete", || {}),
    ///     image("photo").frame(200.0, 200.0),
    /// );
    /// ```
    pub fn context_menu_preview(self, items: View, preview: View) -> Self {
        Self::new(views::context_menu_preview(
            &self.handle,
            items.handle(),
            preview.handle(),
        ))
    }

    /// Wrap in a vertical `ScrollView`.
    pub fn scroll(self) -> Self {
        Self::new(views::scroll(&self.handle))
    }

    // ── Placement ──

    /// `.position(x:y:)` — place the view's centre at a point in its parent,
    /// which is not the same as `.offset(x:y:)` moving it from where it was.
    pub fn position(self, x: f64, y: f64) -> Self {
        Self::new(views::position(&self.handle, x, y))
    }

    /// `.hueRotation(.radians(_))`
    pub fn hue_rotation(self, radians: f64) -> Self {
        Self::new(views::hue_rotation(&self.handle, radians))
    }

    /// `.colorMultiply(_:)` — multiply every pixel by a colour, which tints
    /// without covering.
    pub fn color_multiply(self, color: Color) -> Self {
        Self::new(views::color_multiply(&self.handle, color))
    }

    /// `.contentTransition(_:)` — how a change to the *content* animates, as
    /// distinct from the view arriving or leaving.
    pub fn content_transition(self, transition: views::ContentTransition) -> Self {
        Self::new(views::content_transition(&self.handle, transition))
    }

    /// `.projectionEffect(_:)` — a 3x3 projection, row-major.
    pub fn projection_effect(self, m: [f64; 9]) -> Self {
        Self::new(views::projection_effect(&self.handle, m))
    }

    /// `.aspectRatio(contentMode:)` without pinning a ratio — `true` fills,
    /// `false` fits.
    pub fn aspect_ratio_mode(self, fill: bool) -> Self {
        Self::new(views::aspect_ratio_mode(&self.handle, fill))
    }

    /// `.safeAreaPadding(_:)` — padding measured from the safe area rather than
    /// from the view.
    pub fn safe_area_padding(self, length: f64) -> Self {
        Self::new(views::safe_area_padding(&self.handle, length))
    }

    /// `.contentMargins(_:for:)`
    pub fn content_margins(self, length: f64, placement: views::ContentMarginPlacement) -> Self {
        Self::new(views::content_margins(&self.handle, length, placement))
    }

    /// `.containerShape(_:)` — the shape descendants inherit for clipping.
    pub fn container_shape(self, shape: views::InsettableShape) -> Self {
        Self::new(views::container_shape(&self.handle, shape))
    }

    /// `.coordinateSpace(_:)` — name this view's space so a `GeometryProxy` can
    /// report positions relative to it.
    pub fn coordinate_space(self, name: views::HashableValue<'_>) -> Self {
        Self::new(views::coordinate_space(&self.handle, name))
    }

    // ── Grid cells ──

    /// `.gridCellUnsizedAxes(_:)` — axes this cell should not stretch along.
    pub fn grid_cell_unsized_axes(self, axes: views::AxisSet) -> Self {
        Self::new(views::grid_cell_unsized_axes(&self.handle, axes))
    }

    /// `.gridColumnAlignment(_:)`
    pub fn grid_column_alignment(self, alignment: views::HorizontalAlignment) -> Self {
        Self::new(views::grid_column_alignment(&self.handle, alignment))
    }

    // ── Guides and container-relative sizing ──

    /// `.alignmentGuide(_:computeValue:)` — move where this view lines up with
    /// its siblings without moving the view.
    ///
    /// `compute` is handed the view's [`views::ViewDimensions`] and answers in
    /// terms of them, which is what an alignment guide is for: returning
    /// `d.width / 2.0` lines the view up by its centre, `d.width` by its far
    /// edge. It used to take no arguments, so the only guide it could express
    /// was a constant — the one kind that does not need the modifier.
    ///
    /// ```no_run
    /// # use swiftui_native::prelude::*;
    /// # use swiftui_native::views::HorizontalAlignment;
    /// let v = text("centred").alignment_guide(HorizontalAlignment::Leading, |d| d.width / 2.0);
    /// ```
    pub fn alignment_guide(
        self,
        alignment: views::HorizontalAlignment,
        compute: impl Fn(views::ViewDimensions) -> f64 + 'static,
    ) -> Self {
        Self::new(views::alignment_guide(&self.handle, alignment, compute))
    }

    /// `.containerRelativeFrame(_:alignment:)` — size against the container
    /// rather than the content, which is what makes a carousel page.
    pub fn container_relative_frame(
        self,
        axes: &[views::AxisSet],
        alignment: views::Alignment,
    ) -> Self {
        Self::new(views::container_relative_frame(&self.handle, axes, alignment))
    }

    /// `.containerRelativeFrame(_:count:span:spacing:alignment:)` at thirds.
    pub fn container_relative_frame_thirds(
        self,
        axes: &[views::AxisSet],
        alignment: views::Alignment,
    ) -> Self {
        Self::new(views::container_relative_frame_thirds(&self.handle, axes, alignment))
    }

    /// `.onGeometryChange(for:of:action:)` — observe the measured geometry.
    ///
    /// `measure` is handed the view's width and height and returns the value to
    /// watch; `action` is called with the old and the new one whenever that
    /// value changes. Both used to be blind — `measure` took no arguments, so
    /// it could not read the geometry the modifier exists to report, and
    /// `action` was told only that *something* had changed.
    ///
    /// ```no_run
    /// # use swiftui_native::prelude::*;
    /// let v = text("wide?").on_geometry_change(
    ///     |w, _h| (w > 400.0) as i64,
    ///     |was, now| println!("wide: {was} -> {now}"),
    /// );
    /// ```
    pub fn on_geometry_change(
        self,
        measure: impl Fn(f64, f64) -> i64 + 'static,
        action: impl Fn(i64, i64) + 'static,
    ) -> Self {
        Self::new(views::on_geometry_change_int(&self.handle, measure, action))
    }

    /// `.onGeometryChange(for: Double.self, of:action:)` — the same, watching a
    /// `Double`.
    ///
    /// Which is usually what is wanted: the value being watched is nearly
    /// always a width or a height, and `for: Int.self` meant rounding it before
    /// it could be watched at all.
    ///
    /// ```no_run
    /// # use swiftui_native::prelude::*;
    /// let v = text("wide?").on_geometry_change_f64(|w, _h| w, |was, now| {
    ///     println!("width {was} -> {now}");
    /// });
    /// ```
    pub fn on_geometry_change_f64(
        self,
        measure: impl Fn(f64, f64) -> f64 + 'static,
        action: impl Fn(f64, f64) + 'static,
    ) -> Self {
        Self::new(views::on_geometry_change_f64(&self.handle, measure, action))
    }

    /// `.clipShape(Ellipse())`
    pub fn clip_ellipse(self) -> Self {
        Self::new(views::clip_ellipse(&self.handle))
    }

    /// `.layoutDirectionBehavior(_:)` — whether this mirrors in a
    /// right-to-left language.
    pub fn layout_direction_behavior(self, value: views::LayoutDirectionBehavior) -> Self {
        Self::new(views::layout_direction_behavior(&self.handle, value))
    }

    /// `.layoutValue(key:value:)`
    pub fn layout_value(self, value: i64) -> Self {
        Self::new(views::layout_value_int(&self.handle, value))
    }

    /// `.containerCornerOffset(_:)`
    pub fn container_corner_offset(self, edges: views::EdgeSet, value: bool) -> Self {
        Self::new(views::container_corner_offset(&self.handle, edges, value))
    }

    /// `.safeAreaBar(edge:alignment:spacing:content:)` — a bar that shrinks the
    /// safe area, as [`View::safe_area_inset`] does, but styled as a bar.
    pub fn safe_area_bar(
        self,
        edge: views::VerticalEdge,
        alignment: views::HorizontalAlignment,
        spacing: Option<f64>,
        content: View,
    ) -> Self {
        Self::new(views::safe_area_bar(
            &self.handle,
            edge,
            alignment,
            spacing,
            content.handle(),
        ))
    }

    // ── Safe area and identity ──

    /// `.ignoresSafeArea()` — let the view run under the notch, the home
    /// indicator and the keyboard, which is what a full-bleed background wants.
    pub fn ignores_safe_area(self) -> Self {
        self.ignores_safe_area_edges(views::SafeAreaRegions::All, views::EdgeSet::All)
    }

    /// `.ignoresSafeArea(_:edges:)` — the same, but only the regions and edges
    /// named. `.ignoresSafeArea(.keyboard)` alone is the common case.
    pub fn ignores_safe_area_edges(
        self,
        regions: views::SafeAreaRegions,
        edges: views::EdgeSet,
    ) -> Self {
        Self::new(views::ignores_safe_area(&self.handle, regions, edges))
    }

    /// `.safeAreaInset(edge:alignment:spacing:) { … }` — put a view against one
    /// edge and shrink this view's safe area by however tall it turns out to
    /// be. A bottom bar that scrolling content stops above, without measuring.
    pub fn safe_area_inset(
        self,
        edge: views::VerticalEdge,
        alignment: views::HorizontalAlignment,
        spacing: Option<f64>,
        content: View,
    ) -> Self {
        Self::new(views::safe_area_inset(
            &self.handle,
            edge,
            alignment,
            spacing,
            content.handle(),
        ))
    }

    /// `.scrollIndicators(_:axes:)`
    ///
    /// The axis is not optional here as it is in Swift: SwiftUI's default is
    /// `[.horizontal, .vertical]`, and `Axis.Set` has no `.all` static to name
    /// that pair with, so a no-axis convenience would have to quietly pick one.
    pub fn scroll_indicators(
        self,
        visibility: views::ScrollIndicatorVisibility,
        axes: views::AxisSet,
    ) -> Self {
        Self::new(views::scroll_indicators(&self.handle, visibility, axes))
    }

    /// `.contentShape(_:)` — the region that takes hits, which is otherwise the
    /// view's frame. A circular button in a square frame needs this or its
    /// corners stay tappable.
    pub fn content_shape(self, shape: views::InsettableShape) -> Self {
        Self::new(views::content_shape(&self.handle, shape, false))
    }

    /// `.tag(_:)` — the value a `Picker` or `TabView` selects when this is the
    /// chosen row.
    pub fn tag(self, value: views::HashableValue<'_>) -> Self {
        Self::new(views::tag(&self.handle, value))
    }

    /// `.tag(_:)` with an `Int`, which is what a `Picker` bound to
    /// [`views::BoundState<i64>`] selects by.
    pub fn tag_int(self, value: i64) -> Self {
        self.tag(views::HashableValue::Int(value))
    }

    /// `.tag(_:)` with a `String`.
    pub fn tag_str(self, value: &str) -> Self {
        self.tag(views::HashableValue::Str(value))
    }

    /// `.task { … }` — run the action once when the view appears, cancelled if
    /// it goes away first.
    ///
    /// `#[track_caller]` so the task carries the call site's file and line,
    /// which is what SwiftUI names it by in Instruments — taking `file!()` here
    /// would name every task after this file.
    #[track_caller]
    pub fn task(self, action: impl Fn() + Send + Sync + 'static) -> Self {
        let loc = core::panic::Location::caller();
        Self::new(views::task_once(
            &self.handle,
            views::TaskPriority::UserInitiated,
            loc.file(),
            i64::from(loc.line()),
            action,
        ))
    }

    /// `.task(id:) { … }` — as [`task`](Self::task), but restarted whenever the
    /// identity changes.
    ///
    /// SwiftUI cancels the running task and starts a new one when `id` differs
    /// from the last body evaluation, which is how a detail view re-fetches
    /// when the selection moves. `views::task` has always built this; it had
    /// no chainable method, so the DSL could only ever start a task once.
    #[track_caller]
    pub fn task_id(self, id: i64, action: impl Fn() + Send + Sync + 'static) -> Self {
        let loc = core::panic::Location::caller();
        Self::new(views::task(
            &self.handle,
            id,
            views::TaskPriority::UserInitiated,
            loc.file(),
            i64::from(loc.line()),
            action,
        ))
    }

    /// `.imageScale(_:)` — how large an SF Symbol draws relative to its font.
    pub fn image_scale(self, scale: views::ImageScale) -> Self {
        Self::new(views::image_scale(&self.handle, scale))
    }

    /// `.textCase(_:)` — `None` restores the text as written.
    pub fn text_case(self, case: Option<views::TextCase>) -> Self {
        Self::new(views::text_case(&self.handle, case))
    }

}