UIKit.lua

-- UIKitNative is registered by the host before this layer runs.
local bridge = require("UIKitNative")
local UIKit = bridge
UIKit.platform = "UIKit"
local Scope = require("ui.scope")(bridge)
UIKit.Scope = Scope

local function resumeCoroutine(co, ...)
	local ok, err = coroutine.resume(co, ...)
	if not ok then
		io.stderr:write("coroutine error: " .. tostring(err) .. "\n")
	end
	return ok, err
end

local layout_properties = {
	"padding",
	"paddingHorizontal",
	"paddingLeading",
	"paddingTrailing",
	"paddingVertical",
	"paddingTop",
	"paddingBottom",
	"spacing",
	"maxRows",
	"trailingMaxWidthFraction",
	"alignment",
	"fixedWidth",
	"fixedHeight",
	"minWidth",
	"minHeight",
	"maxWidth",
	"maxHeight",
	"flexGrow",
	"flexShrink",
	"flexBasis",
	"fillWidth",
	"containerRelativeWidth",
	"fillHeight",
	"fitDiameter",
	"fixedSize",
	"hidden",
	"allowsHitTesting",
	"cornerRadius",
	"clipsToBounds",
	"opacity",
	"offsetX",
	"offsetY",
	"colorScheme",
	"ignoresSafeArea",
	"contentModeName",
	"background",
	"tint",
	"onTap",
	"onClick",
	"onDrag",
	"onEdgeSwipe",
}

local function applyLayout(view, props)
	if type(props) ~= "table" then return view end
	for _, key in ipairs(layout_properties) do
		if props[key] ~= nil then
			if key == "background" then
				view.backgroundColor = bridge._systemColor(props[key])
			elseif key == "tint" then
				-- SwiftUI `.tint`: descendants that draw in the accent colour
				-- (UIColor.tintColor) take this colour instead.
				view.tintColor = bridge._systemColor(props[key])
			elseif key == "onTap" or key == "onClick" then
				bridge._addTap(view, props[key])
			elseif key == "onDrag" then
				bridge._addDrag(view, props[key])
			elseif key == "onEdgeSwipe" then
				bridge._addEdgeSwipe(view, props[key])
			else
				view[key] = props[key]
			end
		end
	end
	return view
end

local function addChildren(parent, children)
	if type(children) ~= "table" then return end
	for _, child in ipairs(children) do
		if type(child) == "userdata" then
			parent:add(child)
		elseif type(child) == "table" and child.__appkitGroup then
			addChildren(parent, child)
		end
	end
end

local function asViewController(content)
	if content == nil then
		error("UIKit.Window requires content")
	end
	if type(content) == "table" then
		local stack = UIKit.VStack(content)
		return bridge._hostingController(stack)
	end
	local ok, vc = pcall(function()
		return bridge._hostingController(content)
	end)
	if ok then return vc end
	return content
end

--- Creates the app window and hosts the rendered root view.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop appearance string optional. Window appearance: `system`, `light`, or `dark`.
--- @prop orientation string optional. `landscape` or `portrait` locks the screen to it; a game played with
--- on-screen controls is landscape. Every orientation the app allows by default.
--- @prop content value optional. Rendered child content or the control’s text value.
--- @prop title value optional. Component-specific setting passed to the native control.
--- @example <Window title="Example" />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Window(props)
	props = props or {}
	local scope = Scope.push()
	local content = props.content or props[1]
	local vc = asViewController(content)
	local userInterfaceStyles = { automatic = 0, light = 1, dark = 2 }
	if props.appearance and userInterfaceStyles[props.appearance] ~= nil then
		vc.overrideUserInterfaceStyle = userInterfaceStyles[props.appearance]
	end
	-- If scene installation fails, do not leak the pushed scope.
	local ok, win = pcall(bridge._installScene, vc, props.title or "", props.orientation)
	if not ok then
		scope:close()
		error(win, 2)
	end
	-- Like AppKit, window teardown closes the scope automatically so apps
	-- never call dispose by hand.
	if bridge._onWindowClose then
		bridge._onWindowClose(win, function()
			scope:close()
		end)
	end
	return win
end

--- Presents mutually exclusive content in native tabs.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop onChange function optional. Callback invoked when the value changes.
--- @prop selected table optional. Selected option, tab, or row identifier.
--- @prop tabs table optional. Tab definitions containing a title and content.
--- @prop accessory table optional. A `TabAccessory` record: SwiftUI `tabViewBottomAccessory`.
--- @example <TabView />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.TabView(props)
	props = props or {}
	local tbc = bridge._tabview(props.minimizeBehavior or "automatic")
	local tabs = props.tabs or {}
	for _, tab in ipairs(tabs) do
		if type(tab) == "table" and tab.__tab then
			local vc = asViewController(tab.content)
			bridge._tabViewAddTab(tbc, vc, tab.title or "", tab.systemImage or "", tab.role or "")
		end
	end
	if props.selected ~= nil then
		bridge._tabViewSelectTab(tbc, props.selected)
	end
	if type(props.onChange) == "function" then
		bridge._tabViewOnChange(tbc, props.onChange)
	end
	if props.accessory then
		bridge._tabViewAccessory(tbc, props.accessory.content, props.accessory.hidden == true)
	end
	return tbc
end

--- Creates a fixed-size preview root for the IDE canvas.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @example <Preview />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Preview(props)
	local v = bridge._preview()
	props = props or {}
	if props.appearance then v.appearance = props.appearance end
	if props.zoom then v.zoom = props.zoom end
	return applyLayout(v, props)
end

function UIKit.HostingController(view, onDisappear, props)
	props = props or {}
	local controller = bridge._hostingController(view, onDisappear,
		props.hidesNavigationBar == true)
	if props and props.hidesTabBar ~= nil then
		controller.hidesBottomBarWhenPushed = props.hidesTabBar == true
	end
	return controller
end

--- A navigation destination: one content view plus its title, toolbar items
--- and presentation, as SwiftUI's `.navigationTitle` and `.toolbar` modifiers.
--- Push the returned controller onto a NavigationStack.
--- @tag Page
--- @prop title string optional. Navigation title.
--- @prop toolbar table optional. ToolbarItem records; `placement` is principal, primaryAction, topBarLeading, topBarTrailing, cancellationAction, confirmationAction or keyboard (one view child, shown above the keyboard while a text input edits; AppKit leaves it out).
--- @prop hidesTabBar boolean optional. Hides the tab bar while the page is visible.
--- @prop titleDisplayMode string optional. automatic, inline or large.
--- @prop backButtonDisplayMode string optional. default, generic or minimal.
--- @prop onDisappear function optional. Called once when the page leaves the stack.
--- @platform AppKit puts toolbar items and a back item in the window toolbar. UIKit uses the navigation bar.
function UIKit.Page(props)
	assert(type(props) == "table" and type(props.content) == "userdata", "Page requires one content view")
	local controller = UIKit.HostingController(props.content, props.onDisappear, {
		hidesTabBar = props.hidesTabBar,
		hidesNavigationBar = props.hidesNavigationBar,
	})
	controller.title = props.title or ""
	bridge._pageToolbar(controller, props.toolbar or {}, {
		titleDisplayMode = props.titleDisplayMode,
		backButtonDisplayMode = props.backButtonDisplayMode,
	})
	return controller
end

--- Describes content for a platform sheet presentation.
--- @platform AppKit creates a native sheet panel. UIKit hosts its single child view controller.
function UIKit.Sheet(props)
	props = props or {}
	assert(type(props[1]) == "userdata" and props[2] == nil,
		"Sheet requires exactly one content child")
	local controller = asViewController(props[1])
	if props.width or props.height then
		controller.preferredContentSize = UIKit.Size(props.width or 0, props.height or 0)
	end
	return controller
end

local navScreenScopes = setmetatable({}, { __mode = "k" })
local sheetScopes = {}

--- Manages a stack of screens and navigation transitions.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop content value optional. Rendered child content or the control’s text value.
--- @prop path table optional. A `ui.navigation`.Path value path.
--- @prop destinations table optional. Map path types to destination view builders.
--- @prop hidesNavigationBar boolean optional. Hides the navigation bar when true.
--- @prop hidesTabBar boolean optional. Hides the tab bar when true.
--- @prop largeTitle boolean optional. Uses the large navigation title style when true.
--- @prop toolbar table optional. ToolbarItem records for the root view, placed as on a `Page`.
--- @prop subtitle string optional. Second line under the root's title (SwiftUI `.navigationSubtitle`).
--- @prop background string optional. Color behind the root view where it does not reach, such as behind the keyboard.
--- @prop title value optional. Component-specific setting passed to the native control.
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.NavigationStack(props)
	props = props or {}
	local content = props.content or props[1]
	local root = asViewController(content)
	local navigation = bridge._navigationStack(root, props.hidesNavigationBar == true)
	if props.title then root.title = props.title end
	-- SwiftUI `.navigationSubtitle`: a second line under the title (iOS 26).
	if props.subtitle and props.subtitle ~= "" then root.navigationItem.subtitle = props.subtitle end
	if props.toolbar then bridge._pageToolbar(root, props.toolbar) end
	-- What shows where the root does not reach: the root ends at the
	-- keyboard's top, so this color fills behind the keyboard's corners.
	if props.background then root.view.backgroundColor = bridge._systemColor(props.background) end
	if props.largeTitle ~= nil then
		navigation.navigationBar.prefersLargeTitles = props.largeTitle
	end
	if props.hidesTabBar ~= nil then
		root.hidesBottomBarWhenPushed = props.hidesTabBar
	end
	if props.topPalette then
		bridge._navigationPalette(navigation, props.topPalette, "top",
			props.enablePrivateNavigationPalettes == true)
	end
	if props.bottomPalette then
		bridge._navigationPalette(navigation, props.bottomPalette, "bottom",
			props.enablePrivateNavigationPalettes == true)
	end
	navScreenScopes[navigation] = {}
	if props.path then
		for kind, builder in pairs(props.destinations or {}) do
			props.path:registerDestination(kind, builder)
		end
		require("ui.navigation").bindPath(props.path,
			function(value, builder)
				UIKit.pushScreen(navigation, type(value) == "table" and value.title or nil,
					function() return builder(value) end)
			end,
			function() UIKit.popScreen(navigation) end)
	end
	return navigation
end

function UIKit.pushScreen(nav, title, builder)
	assert(nav ~= nil, "pushScreen requires a navigation stack")
	assert(type(builder) == "function", "pushScreen requires a builder function")
	local stack = navScreenScopes[nav]
	assert(stack ~= nil, "pushScreen requires a NavigationStack host")
	local screenScope = Scope.push()
	local ok, content = pcall(builder)
	if not ok then
		screenScope:close()
		error(content, 2)
	end
	local vc = asViewController(content)
	if title then vc.title = title end
	nav:push(vc)
	table.insert(stack, screenScope)
	return vc
end

function UIKit.popScreen(nav)
	assert(nav ~= nil, "popScreen requires a navigation stack")
	local stack = navScreenScopes[nav]
	assert(stack ~= nil, "popScreen requires a NavigationStack host")
	nav:pop()
	local screenScope = table.remove(stack)
	if screenScope then screenScope:close() end
end

--- Navigates to a destination within a navigation stack.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop destination string optional. Navigation destination associated with the link.
--- @prop label value optional. Component-specific setting passed to the native control.
--- @prop navigation string optional. Navigation stack that receives the destination.
--- @prop title value optional. Component-specific setting passed to the native control.
--- @platform UIKit uses the UIKit implementation.
function UIKit.NavigationLink(props)
	props = props or {}
	assert(props.navigation, "NavigationLink requires a navigation stack")
	assert(props.destination, "NavigationLink requires a destination")
	local destination = asViewController(props.destination)
	return applyLayout(bridge._navigationLink(props.navigation, destination,
		props.title or props.label or props[1] or "Open"), props)
end

-- Shares AppKit.presentSheet's signature. `options.detents` selects sheet
-- heights; `options.presentationStyle = "formSheet"` uses the Sheet's preferred
-- size for a centered popup. `options.parent` is ignored because UIKit presents from the
-- active view controller. Builder results (sheet, refs) are returned intact.
function UIKit.presentSheet(contentOrBuilder, options)
	options = options or {}
	local sheetScope = Scope.push()
	local results = table.pack(true, contentOrBuilder)
	if type(contentOrBuilder) == "function" then
		results = table.pack(pcall(contentOrBuilder))
		if not results[1] then
			sheetScope:close()
			error(results[2], 2)
		end
	end
	bridge._presentSheet(asViewController(results[2]), options)
	table.insert(sheetScopes, sheetScope)
	return table.unpack(results, 2, results.n)
end

function UIKit.dismiss()
	local sheetScope = table.remove(sheetScopes)
	local ok, err = pcall(bridge._dismiss)
	if sheetScope then sheetScope:close() end
	if not ok then error(err, 2) end
end

function UIKit.Font(props)
	assert(type(props) == "table" and tonumber(props.size), "Font requires a size")
	return bridge._font(props.size, props.weight, props.italic == true, props.design,
		props.monospacedDigit == true, props.fontName, props.smallCaps == true)
end

function UIKit.Color(name)
	return bridge._systemColor(name)
end

function UIKit.confirm(props)
	props = props or {}
	return bridge._confirm(props.title or "Confirm", props.message or "",
		props.destructive or "OK", props.cancel or "Cancel", props.action)
end

--- Arranges child views vertically with sibling spacing.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @example <VStack />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.VStack(props)
	local view = bridge._vstack()
	if type(props) == "table" then
		applyLayout(view, props)
		addChildren(view, props)
	end
	return view
end

-- Attach the native drag interaction to a collection of item views.
function UIKit.attachReorder(container, children, onReorder)
	assert(type(onReorder) == "function", "reorder container requires an action")
	local Difference = require("ui.reorder").Difference
	bridge._attachReorder(container, children, function(from, to)
		onReorder(Difference.new():move(from, to))
	end)
	return container
end

--- Arranges child views horizontally with sibling spacing.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @example <HStack />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.HStack(props)
	local view = bridge._hstack()
	if type(props) == "table" then
		applyLayout(view, props)
		addChildren(view, props)
	end
	return view
end

--- Wraps child views into additional rows or columns as space runs out.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop alignment value optional. Component-specific setting passed to the native control.
--- @prop spacing number optional. Component-specific setting passed to the native control.
--- @example <FlowStack />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.FlowStack(props)
	local view = bridge._flowStack()
	if type(props) == "table" then
		applyLayout(view, props)
		addChildren(view, props)
	end
	return view
end

local function stackChildren(props, header)
	local content = {
		spacing = props.spacing or 8,
		alignment = props.alignment or "leading",
	}
	if header and header ~= "" then
		table.insert(content, (UIKit.Text({ header, weight = "bold" })))
	end
	for _, child in ipairs(props) do table.insert(content, child) end
	return content
end

--- Groups related content and may display a header.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop header table optional. Section or group heading.
--- @example <Section />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Section(props)
	props = props or {}
	return UIKit.VStack(stackChildren(props, props.header))
end

--- Groups related controls inside a titled native box.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop background color optional. Background color or semantic background value.
--- @prop cornerRadius number optional. Corner radius for this component where supported.
--- @prop header table optional. Section or group heading.
--- @prop padding number optional. Component-specific setting passed to the native control.
--- @example <GroupBox />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.GroupBox(props)
	props = props or {}
	local content = stackChildren(props, props.header)
	content.padding = props.padding or 12
	-- SwiftUI's GroupBox fills with the secondary system background.
	content.background = props.background or "secondaryBackground"
	content.cornerRadius = props.cornerRadius or 10
	content.clipsToBounds = true
	-- SwiftUI's GroupBox takes the width it is offered.
	content.fillWidth = true
	return UIKit.VStack(content)
end

--- Arranges controls as a settings or data-entry form.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop alignment value optional. Component-specific setting passed to the native control.
--- @prop spacing number optional. Component-specific setting passed to the native control.
--- @example <Form />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Form(props)
	props = props or {}
	local content = {
		spacing = props.spacing or 12,
		alignment = props.alignment or "leading",
	}
	for _, child in ipairs(props) do table.insert(content, child) end
	return applyLayout(UIKit.VStack(content), props)
end

--- Pairs a descriptive label with its value or child controls.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop label value optional. Component-specific setting passed to the native control.
--- @prop labelWeight value optional. System font weight for the label.
--- @prop spacing number optional. Component-specific setting passed to the native control.
--- @example <LabeledContent />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.LabeledContent(props)
	props = props or {}
	local row = { spacing = props.spacing or 12, alignment = "center" }
	if props.label and props.label ~= "" then
		table.insert(row, (UIKit.Text({ props.label, weight = props.labelWeight })))
	end
	for _, child in ipairs(props) do table.insert(row, child) end
	return applyLayout(UIKit.HStack(row), props)
end

--- Groups related controls into a compact row.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop alignment value optional. Component-specific setting passed to the native control.
--- @prop spacing number optional. Component-specific setting passed to the native control.
--- @example <ControlGroup />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.ControlGroup(props)
	props = props or {}
	local row = { spacing = props.spacing or 8, alignment = props.alignment or "center" }
	for _, child in ipairs(props) do table.insert(row, child) end
	return applyLayout(UIKit.HStack(row), props)
end

--- Shows a header that expands or collapses its child content.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop alignment value optional. Component-specific setting passed to the native control.
--- @prop expanded boolean optional. Component-specific setting passed to the native control.
--- @prop header table optional. Section or group heading.
--- @prop label value optional. Component-specific setting passed to the native control.
--- @prop spacing number optional. Component-specific setting passed to the native control.
--- @example <DisclosureGroup />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.DisclosureGroup(props)
	props = props or {}
	local content = UIKit.VStack({
		spacing = props.spacing or 8,
		alignment = props.alignment or "leading",
	})
	for _, child in ipairs(props) do content:add(child) end
	local container = UIKit.VStack { spacing = 8, alignment = "leading" }
	local expanded = props.expanded ~= false
	local button = UIKit.Button {
		title = props.label or props.header or "Details",
		action = function()
			expanded = not expanded
			content.hidden = not expanded
			container:layout()
		end,
	}
	container:add(button)
	container:add(content)
	content.hidden = not expanded
	return applyLayout(container, props)
end

local function outlineItems(ns, items, expanded)
	local views = {}
	for _, item in ipairs(items or {}) do
		local title = item.title or item.name or tostring(item)
		local children = item.children
		if type(children) == "table" and #children > 0 then
			local nested = ns.VStack { spacing = 4, alignment = "leading" }
			for _, child in ipairs(outlineItems(ns, children, expanded)) do
				nested:add(child)
			end
			table.insert(views, (ns.DisclosureGroup {
				label = title,
				expanded = expanded,
				nested,
			}))
		else
			table.insert(views, (ns.Text(title)))
		end
	end
	return views
end

--- Builds a nested disclosure hierarchy from tree data.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop alignment value optional. Component-specific setting passed to the native control.
--- @prop data table optional. Input rows or values consumed by the component.
--- @prop expanded boolean optional. Component-specific setting passed to the native control.
--- @prop items table optional. Component-specific setting passed to the native control.
--- @prop spacing number optional. Component-specific setting passed to the native control.
--- @example <OutlineGroup />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.OutlineGroup(props)
	props = props or {}
	local data = props.data or props.items or {}
	assert(type(data) == "table", "OutlineGroup requires data or items")
	local content = outlineItems(UIKit, data, props.expanded)
	content.spacing = props.spacing or 4
	content.alignment = props.alignment or "leading"
	return applyLayout(UIKit.VStack(content), props)
end

--- Layers child views in the same coordinate area.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @example <ZStack />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.ZStack(props)
	local view = bridge._zstack()
	if type(props) == "table" then
		applyLayout(view, props)
		addChildren(view, props)
	end
	return view
end

-- UIScrollViewKeyboardDismissMode for each SwiftUI ScrollDismissesKeyboardMode.
local KEYBOARD_DISMISS_MODES = { automatic = 0, never = 0, immediately = 1, interactively = 2 }

--- Adds native scrolling around one content view.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop content value optional. Rendered child content or the control’s text value.
--- @prop contentHeight number optional. Scroll content height; zero lets the content size itself.
--- @prop contentWidth number optional. Scroll content width; zero lets the content size itself.
--- @prop horizontal boolean optional. Component-specific setting passed to the native control.
--- @prop scrollDismissesKeyboard string optional. `automatic`, `immediately`, `interactively` or `never`, as SwiftUI's modifier.
--- @prop vertical boolean optional. Component-specific setting passed to the native control.
--- @example <ScrollView />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.ScrollView(props)
	assert(type(props) == "table", "ScrollView requires a property table")
	local content = props.content or props[1]
	assert(type(content) == "userdata", "ScrollView requires one content view")
	local view = bridge._scrollView(content, props.contentWidth or 0,
		props.contentHeight or 0, props.horizontal == true, props.vertical ~= false)
	if props.scrollOnKeyboard then view.scrollOnKeyboard = true end
	-- SwiftUI scrollDismissesKeyboard. `interactively` lets the keyboard
	-- follow a downward drag as Messages does; `immediately` dismisses it when
	-- a drag begins. `automatic` keeps UIKit's default, which leaves it up.
	local dismissMode = KEYBOARD_DISMISS_MODES[props.scrollDismissesKeyboard or "automatic"]
	assert(dismissMode, "ScrollView scrollDismissesKeyboard must be automatic, immediately, interactively or never")
	view.keyboardDismissMode = dismissMode
	-- SwiftUI scrollTargetBehavior: `viewAligned` settles on a child of the
	-- content stack; `paging` pages by the visible width.
	if props.scrollTargetBehavior then view.scrollTargetBehavior = props.scrollTargetBehavior end
	return applyLayout(view, props)
end

--- Draws a circular arc in screen coordinates.
---
--- Angles are degrees, clockwise from east, in a y-down view. Equal angles
--- close the circle. `stroke` is a semantic color name.
--- @prop cornerRadius number optional. Draws the arc as a filled sector of its band with corners rounded this many points.
--- @prop endAngle number optional. Ending angle in degrees.
--- @prop height number optional. Component-specific setting passed to the native control.
--- @prop lineCap string optional. `butt` or `round`.
--- @prop diameter number optional. With `fitDiameter`, the circle's diameter in units.
--- @prop inset number optional. Draws the arc as a filled sector of its band, every edge moved in by half this many points, so neighbours are this far apart.
--- @prop fitDiameter number optional. Scales the arc to its frame: the frame's shorter side spans this many units, and `diameter` and `lineWidth` are in those units.
--- @prop lineWidth number optional. Stroke width in points.
--- @prop startAngle number optional. Starting angle in degrees.
--- @prop stroke string optional. Semantic stroke color.
--- @prop strokeAlpha number optional. Stroke opacity from 0 to 1.
--- @prop width number optional. Component-specific setting passed to the native control.
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Arc(props)
	props = props or {}
	if props.width and not props.fixedWidth then props.fixedWidth = props.width end
	if props.height and not props.fixedHeight then props.fixedHeight = props.height end
	local width = props.fixedWidth or 48
	local height = props.fixedHeight or width
	local view = bridge._arc(width, height)
	view.startAngle = props.startAngle or 0
	view.endAngle = props.endAngle or 0
	if props.lineWidth then view.lineWidth = props.lineWidth end
	if props.stroke then view.stroke = props.stroke end
	if props.strokeAlpha then view.strokeAlpha = props.strokeAlpha end
	if props.lineCap then view.lineCap = props.lineCap end
	if props.diameter then view.diameter = props.diameter end
	if props.fitDiameter then view.fitDiameter = props.fitDiameter end
	if props.inset then view.inset = props.inset end
	if props.cornerRadius then view.cornerRadius = props.cornerRadius end
	return applyLayout(view, props)
end

require("ui.meshgradient").install(UIKit, bridge, applyLayout)
require("ui.lazy").install(UIKit, bridge, applyLayout)
require("ui.webpage").install(UIKit, bridge, applyLayout)
-- Local notifications (see ui/notifications.lua).
require("ui.notifications").install(UIKit, bridge)

--- Draws a pie or donut chart from `SectorMark` records (SwiftUI Charts).
--- @prop innerRadius number optional. Hole radius as a fraction of the outer radius (0 draws a pie).
--- @prop angularInset number optional. Gap between neighbouring sectors, in points.
--- @prop scalable boolean optional. Lays the sectors out in `diameter` units and scales them to fill the room the chart is given, centered.
--- @prop diameter number optional. With `scalable`, the chart's geometry in units (default 360).
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.SectorChart(props)
	return require("ui.sectors").chart(UIKit, props)
end

--- Pins the second child to a safe-area edge while the first child uses the remaining space.
---
--- The bottom edge includes the hosting controller's safe-area inset. Use a flexible
--- scroll view as the first child and the persistent control as the second child.
--- @prop edge string optional. Currently `bottom`.
--- @prop minimumBottomInset number optional. Minimum resting clearance on devices without a bottom safe-area inset.
--- @prop keyboardBottomInset number optional. Clearance above the software keyboard.
--- @prop horizontalInset number optional. Horizontal clearance while the keyboard is visible.
--- @prop matchBottomHorizontalInset boolean optional. Match resting horizontal clearance to the bottom safe-area inset.
--- @platform UIKit.
function UIKit.SafeAreaInset(props)
	props = props or {}
	assert(props.edge == nil or props.edge == "bottom", "SafeAreaInset currently supports edge=bottom")
	assert(type(props[1]) == "userdata" and type(props[2]) == "userdata" and props[3] == nil,
		"SafeAreaInset requires content and inset children")
	local accessory = UIKit.VStack {
		spacing = 0, fillWidth = true, paddingHorizontal = props.horizontalInset or 0, props[2],
	}
	accessory.safeAreaInsetBottom = true
	accessory.minimumBottomInset = props.minimumBottomInset or 0
	accessory.keyboardBottomInset = props.keyboardBottomInset or 0
	accessory.horizontalInset = props.horizontalInset or 0
	accessory.matchBottomHorizontalInset = props.matchBottomHorizontalInset == true
	return applyLayout(UIKit.VStack {
		spacing = 0, fillWidth = true, fillHeight = true, props[1], accessory,
	}, props)
end

--- Edits a single line of text.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop accessibilityLabel value optional. Component-specific setting passed to the native control.
--- @prop bezeled boolean optional. Shows the native bezel when true.
--- @prop color string optional. Text color: a semantic color name or a `#light|#dark` hex pair.
--- @prop disabled boolean optional. Component-specific setting passed to the native control.
--- @prop editable boolean optional. Allows text editing when true.
--- @prop onChange function optional. Callback invoked when the value changes.
--- @prop onCommand function optional. Callback invoked for the corresponding keyboard command.
--- @prop onFocus function optional. Callback invoked when editing begins and the keyboard is shown.
--- @prop placeholder string optional. Component-specific setting passed to the native control.
--- @prop style string optional. `plain` removes the field border; `roundedBorder` keeps the system field bezel.
--- @prop secure boolean optional. Masks entered text when true.
--- @prop size number optional. Component-specific setting passed to the native control.
--- @prop value table optional. Current selected, edited, or measured value.
--- @prop weight value optional. Component-specific setting passed to the native control.
--- @example <TextField />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.TextField(props)
	if type(props) ~= "table" then props = { value = tostring(props or "") } end
	assert(props.style == nil or props.style == "plain" or props.style == "roundedBorder",
		"TextField style must be 'plain' or 'roundedBorder'")
	local field = bridge._textField(props.value or props[1] or "")
	field.placeholder = props.placeholder or ""
	field.borderStyle = (props.style == "plain" or props.bezeled == false) and 0 or 3
	field.secureTextEntry = props.secure == true
	field.enabled = props.disabled ~= true and props.editable ~= false
	if props.size then field.font = bridge._font(props.size, props.weight, false, props.design) end
	if props.color then field.textColor = bridge._systemColor(props.color) end
	if props.accessibilityLabel then field.accessibilityLabel = props.accessibilityLabel end
	bridge._textFieldCallbacks(field, props.onChange, props.onCommand, props.onFocus)
	field:sizeToFit()
	-- SwiftUI text fields accept the available width while keeping native height.
	field.fillWidth = true
	return applyLayout(field, props)
end

--- Edits multiline text.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop drawsBackground boolean optional. Draws the control’s background when true.
--- @prop editable boolean optional. Allows text editing when true.
--- @prop italic boolean optional. Component-specific setting passed to the native control.
--- @prop onChange function optional. Receives the text after each edit.
--- @prop placeholder string optional. Prompt shown in the system placeholder color while the editor is empty.
--- @prop selectable boolean optional. Allows text or rows to be selected when true.
--- @prop size number optional. Component-specific setting passed to the native control.
--- @prop text string optional. Initial or displayed text value.
--- @prop value table optional. Current selected, edited, or measured value.
--- @prop weight value optional. Component-specific setting passed to the native control.
--- @prop wrapMode string optional. Text wrapping mode.
--- @example <TextEditor />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.TextEditor(props)
	props = props or {}
	local v = bridge._textEditor(props.text or props.value or "",
		props.editable, props.selectable, props.drawsBackground)
	if props.size and props.size > 0 then
		v.font = bridge._font(props.size, props.weight, props.italic, props.design)
	end
	if props.wrapMode == false then
		v.textContainer.lineBreakMode = 1
	end
	-- SwiftUI `TextEditor(text:)`: each edit hands the new text to the page.
	if props.onChange then bridge._textEditorCallbacks(v, props.onChange) end
	if props.placeholder then v.placeholder = props.placeholder end
	if props.accessibilityLabel then v.accessibilityLabel = props.accessibilityLabel end
	return applyLayout(v, props)
end

--- Displays source with native, rule-driven syntax coloring and optional editing.
--- @prop language string required. Language key in `syntaxRules.languages`.
--- @prop syntaxRules table required. Colors, regular-expression matches and embedded-language regions.
--- @prop size number optional. Monospaced font size.
--- @prop text string required. Source text.
--- @example <CodeView language="lua" text="source" syntaxRules="rules" />
--- @platform UIKit UITextView with attributed TextKit storage.
function UIKit.CodeView(props)
	props = props or {}
	local v = bridge._codeView(props.text or "", props.language or "lua", props.syntaxRules or {})
	v.editable = props.editable == true
	if props.onChange then bridge._textEditorCallbacks(v, props.onChange) end
	if props.size and props.size > 0 then v.font = bridge._font(props.size, "regular", false, "monospaced") end
	return applyLayout(v, props)
end

-- The host streams files from the packager instead of holding them, but
-- SceneKit imports models from disk: stage each model, the materials its
-- OBJ names and their textures where it can read them, and point the record
-- at the staged copy. Records already pointing at a local path pass through.
local stagedModels = {}

local function stageFile(path)
	local body, err = bridge._readFile(path)
	if not body then error(err or ("cannot read " .. path), 0) end
	return bridge._stageAsset(path, body), body
end

local function stageModel(path)
	if stagedModels[path] then return stagedModels[path] end
	local local_, body = stageFile(path)
	local dir = path:match("^(.*)/[^/]*$") or "."
	for name in body:gmatch("mtllib%s+([^\r\n]+)") do
		local _, mtl = stageFile(dir .. "/" .. name)
		for texture in mtl:gmatch("map_%w+%s+([^\r\n]+)") do stageFile(dir .. "/" .. texture) end
	end
	stagedModels[path] = local_
	return local_
end

local function stageRecords(records)
	for _, record in ipairs(records) do
		if type(record.model) == "string" and record.model:sub(1, 1) ~= "/" and bridge._readFile then
			record.model = stageModel(record.model)
		end
		if record.items then stageRecords(record.items) end
	end
end

--- Displays a SceneKit scene described by `Node`, `Camera` and `Light` records.
---
--- Like SwiftUI's `SceneView`, the view fills its proposal. The records form
--- the scene graph and reconcile by `id` when the template renders again:
--- nodes keep their pose and running behaviours, changed attributes apply in
--- place, and `transition` plays when a node is inserted or removed. Game
--- state moves nodes every frame with `view.nodeStates = {{id, x, y, z, yaw,
--- pitch, roll, scale, opacity, hidden}, ...}` (angles in degrees) without
--- describing the scene again.
--- @prop background string optional. Color behind the scene (semantic name or `#rrggbb`).
--- @prop onKey function optional. `onKey(view, key, pressed) -> handled`: presses and releases, never repeats; the view takes the keyboard when it appears.
--- @prop onFrame function optional. `onFrame(view, dt)` once per displayed frame while the view is in a window, `dt` in seconds.
--- @prop onSwipe function optional. `onSwipe(view, direction)` with `left`, `right`, `up` or `down`, sent as soon as a drag (a finger, or the mouse) has travelled far enough.
--- @prop onTap function optional. `onTap(view)` when a press is released without travelling. A drag is one swipe or one tap, never both.
--- @prop showsStatistics boolean optional. Shows SceneKit's frame-rate and draw-call overlay.
--- @example <SceneView background="#8fd3f4"><Camera position="0 6 8" lookAt="0 0 0" /><Light type="directional" rotation="-60 30 0" castsShadow="true" /><Node model="assets/coin.obj" spin="90" /></SceneView>
--- @platform UIKit.
function UIKit.SceneView(props)
	props = props or {}
	local records = {}
	for _, child in ipairs(props) do
		if type(child) ~= "table" or not child.sceneKind then
			error("SceneView accepts only Node, Camera and Light records")
		end
		table.insert(records, child)
	end
	stageRecords(records)
	local view = bridge._sceneView(props.onKey, props.onFrame, props.onSwipe, props.onTap)
	if props.background then bridge._sceneBackground(view, props.background) end
	if props.showsStatistics then view.showsStatistics = true end
	if props.virtualGamepad then view.virtualGamepad = true end
	UIKit.sceneGraph(view, records)
	-- A 3-D viewport has no intrinsic size and fills its proposal.
	view.fillWidth, view.fillHeight = true, true
	local layout = {}
	for key, value in pairs(props) do
		if type(key) ~= "number" and key ~= "onKey" and key ~= "onFrame" and key ~= "onSwipe" and key ~= "onTap" and key ~= "background"
			and key ~= "virtualGamepad" then layout[key] = value end
	end
	return applyLayout(view, layout)
end

--- Reconciles a SceneView's graph with new `Node`, `Camera` and `Light` records.
---
--- The XML reconciler calls this when a template renders new records; a
--- model that cannot load or an unknown geometry raises an error naming the node.
function UIKit.sceneGraph(view, records)
	stageRecords(records)
	local problems = bridge._sceneGraph(view, records)
	if #problems > 0 then error("SceneView: " .. table.concat(problems, "; "), 2) end
	return true
end

--- Provides native search input and search-specific behavior.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop accessibilityLabel value optional. Component-specific setting passed to the native control.
--- @prop placeholder string optional. Component-specific setting passed to the native control.
--- @prop value table optional. Current selected, edited, or measured value.
--- @example <SearchField />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.SearchField(props)
	props = props or {}
	local v = bridge._searchField(props.value or props[1] or "",
		props.placeholder or "Search")
	if props.accessibilityLabel then
		v.accessibilityLabel = props.accessibilityLabel
	end
	bridge._textFieldCallbacks(v, props.onChange, props.onCommand)
	v.fillWidth = true
	return applyLayout(v, props)
end

--- Combines an icon and title in a standard platform label.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop accessibilityLabel value optional. Component-specific setting passed to the native control.
--- @prop alignment value optional. Component-specific setting passed to the native control.
--- @prop color color optional. Component-specific setting passed to the native control.
--- @prop iconSize number optional. Component-specific setting passed to the native control.
--- @prop iconWeight value optional. System symbol weight for the label icon.
--- @prop italic boolean optional. Component-specific setting passed to the native control.
--- @prop lineLimit number optional. Maximum number of visible text lines.
--- @prop lines number optional. Maximum number of visible text lines.
--- @prop reservesSpace boolean optional. Always as tall as `lines` lines, so shorter text never moves siblings (SwiftUI `.lineLimit(n, reservesSpace: true)`).
--- @prop size number optional. Component-specific setting passed to the native control.
--- @prop spacing number optional. Component-specific setting passed to the native control.
--- @prop systemImage string optional. Component-specific setting passed to the native control.
--- @prop symbolSize number optional. SF Symbol point size for an image-only button.
--- @prop truncation string optional. Text truncation position: `head`, `middle`, or `tail`.
--- @prop minimumScaleFactor number optional. Smallest fraction of `size` the text shrinks to when space is short.
--- @prop weight value optional. Component-specific setting passed to the native control.
--- @prop wrapping boolean optional. Component-specific setting passed to the native control.
--- @platform UIKit uses the UIKit implementation.
function UIKit.Label(arg)
	local text
	local props
	if type(arg) == "table" then
		text = arg[1] or arg.text or arg.value or ""
		props = arg
	elseif type(arg) == "string" then
		text = arg
	else
		text = tostring(arg)
	end
	-- An empty symbol name is no symbol, so templates can bind it conditionally.
	if type(props) == "table" and props.systemImage and props.systemImage ~= "" then
		local row = {
			spacing = props.spacing or 6,
			alignment = "center",
			UIKit.SystemImage({
				name = props.systemImage,
				accessibilityLabel = props.accessibilityLabel,
				size = props.iconSize or props.size,
				weight = props.iconWeight or props.weight,
				color = props.color,
			}),
			UIKit.Label({ text, size = props.size, weight = props.weight,
				italic = props.italic, design = props.design, color = props.color,
				monospacedDigit = props.monospacedDigit, fontName = props.fontName, smallCaps = props.smallCaps,
				lineLimit = props.lineLimit, reservesSpace = props.reservesSpace, truncation = props.truncation, wrapping = props.wrapping,
				minimumScaleFactor = props.minimumScaleFactor }),
		}
		return applyLayout(UIKit.HStack(row), props)
	end
	local v = bridge._label(text)
	if type(props) == "table" then
		if props.size and props.size > 0 then
			v.font = bridge._font(props.size, props.weight, props.italic, props.design,
				props.monospacedDigit == true, props.fontName, props.smallCaps == true)
		end
		local lines = props.lineLimit or props.lines
		if lines then
			v.numberOfLines = lines
			if lines > 1 then v.lineBreakMode = 0 end
		end
		if props.reservesSpace then v.reservesSpace = true end
		if props.wrapping then v.lineBreakMode = props.wrapping == "character" and 1 or 0 end
		if props.truncation then
			local modes = { head = 3, tail = 4, middle = 5 }
			v.lineBreakMode = modes[props.truncation] or 4
		end
		if props.color then
			v.textColor = bridge._systemColor(props.color)
		end
		if props.alignment then
			v.textAlignment = ({ leading = 0, center = 1, trailing = 2 })[props.alignment] or 0
		end
		if props.accessibilityLabel then v.accessibilityLabel = props.accessibilityLabel end
		-- SwiftUI `.minimumScaleFactor` is UILabel's own shrink-to-fit.
		if props.minimumScaleFactor then
			v.adjustsFontSizeToFitWidth = true
			v.minimumScaleFactor = props.minimumScaleFactor
		end
		v:sizeToFit()
	end
	return applyLayout(v, props)
end

UIKit.Text = UIKit.Label

local PARAGRAPH_ALIGNMENT = { leading = 4, center = 1, trailing = 2, justified = 3 }

--- Long-form prose set as a book sets it: selectable text with explicit
--- leading, optional hyphenation, and an optional dropped initial that the
--- following lines wrap around. Use `Label` for short text and UI copy.
--- @tag Paragraph
--- @prop text string required. The paragraph's text.
--- @prop size number optional. Body point size; defaults to 17.
--- @prop design string optional. `default`, `serif`, `rounded` or `monospaced`.
--- @prop fontName string optional. An OS-bundled face; falls back to `design`.
--- @prop color string optional. Semantic or hex text colour.
--- @prop lineSpacing number optional. Extra points between lines (SwiftUI `lineSpacing`).
--- @prop alignment string optional. `leading`, `center`, `trailing` or `justified`.
--- @prop hyphenation boolean optional. Hyphenates long words at line ends.
--- @prop figure string optional. Image beside the first lines, which wrap around it (as Zork Zero set a room's picture beside its description).
--- @prop figureLines number optional. Lines the square figure spans; defaults to 3.
--- @prop revealedCharacters number optional. Typewriter reveal: characters shown so far (as `utf8.len` counts them); -1, the default, shows all. Lines are those of the whole text, which takes its whole height however little is revealed.
--- @prop links table optional. Runs the reader can act on, from `<Hyperlink>` children: `{ location, length, label, items }`, where `location` (from 0) and `length` count characters as `utf8.len` does and `items` are `<MenuItem>` records. A link is marked with a thicker dotted underline and opens its menu when tapped.
--- @prop linkColor string optional. Colour of the rule under links; defaults to the tint.
--- @example <Paragraph text="Once upon a time…" design="serif" lineSpacing="5" figure="assets/hall.png" />
--- @platform UIKit non-scrolling UITextView (TextKit 1 exclusion paths). AppKit non-editable NSTextView.
function UIKit.Paragraph(props)
	props = props or {}
	local view = bridge._paragraph(props.text or props[1] or "")
	view.font = bridge._font(props.size or 17, props.weight, props.italic == true, props.design,
		false, props.fontName, props.smallCaps == true)
	if props.color then view.textColor = bridge._systemColor(props.color) end
	if props.lineSpacing then view.lineSpacing = props.lineSpacing end
	if props.hyphenation ~= nil then view.hyphenation = props.hyphenation end
	if props.alignment then view.textAlignment = PARAGRAPH_ALIGNMENT[props.alignment] or 4 end
	if props.selectable == false then view.selectable = false end
	-- The figure is an image view the paragraph floats; it never joins the
	-- layout tree, so the paragraph alone sizes and places it.
	if props.figure and props.figure ~= "" then
		if props.figureLines then view.figureLines = props.figureLines end
		view.figureView = UIKit.Image { props.figure, contentMode = "fill" }
	end
	if props.linkColor then view.linkColor = bridge._systemColor(props.linkColor) end
	if props.links then bridge._paragraphSetLinks(view, props.links) end
	if props.revealedCharacters then view.revealedCharacters = props.revealedCharacters end
	if props.accessibilityLabel then view.accessibilityLabel = props.accessibilityLabel end
	-- Prose fills the column it is given and wraps to it.
	view.fillWidth = true
	return applyLayout(view, props)
end

--- Displays prominent window or section title text.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Title(arg)
	return UIKit.Label({
		type(arg) == "table" and (arg[1] or arg.text) or arg,
		size = 22,
		weight = "bold",
	})
end

--- Displays a raster or vector image asset.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop contentMode string optional. Image scaling mode such as fit or fill.
--- @prop darkPath string optional. The image shown under a dark appearance; the view follows appearance changes.
--- @example <Image />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Image(arg)
	local path
	local props
	if type(arg) == "table" then
		path = arg[1] or arg.src or arg.path or ""
		props = arg
	elseif type(arg) == "string" then
		path = arg
	else
		path = tostring(arg)
	end
	local darkPath = props and props.darkPath
	if bridge._readFile then
		local body, err = bridge._readFile(path)
		if err then error(err) end
		local dark
		if darkPath then
			dark, err = bridge._readFile(darkPath)
			if err then error(err) end
		end
		local view = bridge._imageData(body, dark)
		if props and props.contentMode then view.contentModeName = props.contentMode end
		if props and props.resizable then
			view.fillWidth, view.fillHeight = true, true
		end
		return applyLayout(view, props)
	end
	local view = bridge._image(path, darkPath)
	if props and props.contentMode then view.contentModeName = props.contentMode end
	if props and props.resizable then
		view.fillWidth, view.fillHeight = true, true
	end
	return applyLayout(view, props)
end

--- Displays an SF Symbol using the platform image system.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @example <SystemImage />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.SystemImage(arg)
	if type(arg) ~= "table" then
		arg = { tostring(arg) }
	end
	local name = arg.name or arg[1] or ""
	local description = arg.accessibilityLabel or arg.label or name
	local size = arg.size or 17
	local weight = arg.weight or "regular"
	local color = arg.color or "primary"
	return applyLayout(
		bridge._systemImage(name, description, size, weight, color),
		arg)
end

--- Consumes flexible space between neighboring views.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @example <Spacer />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Spacer(props)
	return applyLayout(bridge._spacer(), props)
end

--- Indicates pages and allows selecting the current page.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop currentPage number optional. Zero-based index of the currently visible page.
--- @prop numberOfPages number optional. Component-specific setting passed to the native control.
--- @prop pages table optional. Page data used to construct the page control.
--- @platform UIKit uses the UIKit implementation.
function UIKit.PageControl(props)
	props = props or {}
	return applyLayout(bridge._pageControl(props.numberOfPages or props.pages or 0,
		props.currentPage or 0), props)
end

-- SwiftUI UnitPoint: x runs leading to trailing, y top to bottom.
local UNIT_POINTS = {
	topLeading = { 0, 0 }, top = { 0.5, 0 }, topTrailing = { 1, 0 },
	leading = { 0, 0.5 }, center = { 0.5, 0.5 }, trailing = { 1, 0.5 },
	bottomLeading = { 0, 1 }, bottom = { 0.5, 1 }, bottomTrailing = { 1, 1 },
}

--- Fills content with a linear gradient, as SwiftUI's LinearGradient.
---
--- With `colors` the gradient runs through those semantic colors, evenly
--- spaced from `startPoint` to `endPoint`, and follows light and dark
--- appearance. Without `colors` it is a vertical black fade for laying text
--- over artwork, shaped by the alpha props.
--- @prop colors table optional. Two or more color names, in order.
--- @prop startPoint string optional. Unit point the first color sits at: `top`, `bottom`, `leading`, `trailing`, `center` or a corner such as `topLeading`. Default `top`.
--- @prop endPoint string optional. Unit point the last color sits at. Default `bottom`.
--- @prop bottomAlpha number optional. Fade opacity at the bottom edge.
--- @prop middleAlpha number optional. Fade opacity at the middle stop.
--- @prop middleLocation number optional. Position of the fade's middle stop, from 0 to 1.
--- @prop topAlpha number optional. Fade opacity at the top edge.
--- @example <LinearGradient colors="systemIndigo,systemPink" startPoint="topLeading" endPoint="bottomTrailing" />
--- @platform AppKit and UIKit.
function UIKit.LinearGradient(props)
	props = props or {}
	local view = bridge._linearGradient(props.topAlpha or 0,
		props.middleAlpha or 0.5, props.middleLocation or 0.6,
		props.bottomAlpha or 0.82)
	if props.colors then
		local start = UNIT_POINTS[props.startPoint or "top"]
		local stop = UNIT_POINTS[props.endPoint or "bottom"]
		assert(start, "LinearGradient startPoint is not a unit point: " .. tostring(props.startPoint))
		assert(stop, "LinearGradient endPoint is not a unit point: " .. tostring(props.endPoint))
		bridge._linearGradientColors(view, props.colors, start[1], start[2], stop[1], stop[2])
	end
	-- Gradients have no intrinsic size and accept both proposed dimensions.
	view.fillWidth, view.fillHeight = true, true
	return applyLayout(view, props)
end

--- Hosts content on the requested update schedule.
--- @prop schedule string optional. `animation` animates a mesh child.
--- @prop content value required. Hosted view.
--- @platform AppKit and UIKit.
function UIKit.TimelineView(props)
	props = props or {}
	local content = props.content or props[1]
	assert(content, "TimelineView requires content")
	if props.schedule == "animation" then content.animated = true end
	return applyLayout(content, props)
end

--- Displays rows of data in a native table or list control.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop bordered boolean optional. Shows the native border when true.
--- @prop columns table optional. Column descriptors defining the table structure.
--- @prop data table optional. Input rows or values consumed by the component.
--- @prop header table optional. Section or group heading.
--- @prop height number optional. Component-specific setting passed to the native control.
--- @prop width number optional. Component-specific setting passed to the native control.
--- @example <List />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.List(props)
	local columns = props.columns
	if not columns or type(columns) ~= "table" then
		error("List requires a 'columns' property (array of {id, title})")
	end
	local width = props.width or 400
	local height = props.height or 200
	local tv = bridge._tableview(columns, width, height, {
		header = props.header ~= false,
		bordered = props.bordered == true,
	})
	if props.onSelect then tv:onSelect(props.onSelect) end
	if props.scrollDisabled then tv.scrollEnabled = false end
	if props.data then tv:replaceRows(props.data) end
	if props.reorderable then
		assert(type(props.onReorder) == "function",
			"List reorderable requires an onReorder callback")
		local Difference = require("ui.reorder").Difference
		tv:onRowMove(function(_, from, to)
			local difference = Difference.new()
			difference:move(from, to)
			props.onReorder(difference)
		end)
	end
	if props.onSwipeLeading then
		tv:onRowSwipe("leading", props.swipeLeadingTitle or "Archive",
			props.swipeLeadingRole or "normal", props.fullSwipe == true,
			function(_, index, row) props.onSwipeLeading(index, row) end)
	end
	if props.onSwipeTrailing then
		tv:onRowSwipe("trailing", props.swipeTrailingTitle or "Delete",
			props.swipeTrailingRole or "destructive", props.fullSwipe == true,
			function(_, index, row) props.onSwipeTrailing(index, row) end)
	end
	return applyLayout(tv, props)
end

--- A native swipeable table row for use inside a VStack or other stack.
function UIKit.SwipeRow(props)
	props = props or {}
	local view = UIKit.List {
		columns = { { id = "title", title = "" }, { id = "status", title = "" } },
		data = { { title = props.title or "", status = props.status or "" } },
		header = false,
		style = "plain",
		onSwipeLeading = props.onSwipeLeading and function(_, row)
			props.onSwipeLeading(props.rowId, row)
		end,
		onSwipeTrailing = props.onSwipeTrailing and function(_, row)
			props.onSwipeTrailing(props.rowId, row)
		end,
		swipeLeadingTitle = props.swipeLeadingTitle,
		swipeTrailingTitle = props.swipeTrailingTitle,
		swipeLeadingRole = props.swipeLeadingRole,
		swipeTrailingRole = props.swipeTrailingRole,
		fullSwipe = props.fullSwipe,
	}
	view.fixedHeight = props.rowHeight or view.rowHeight
	view.scrollEnabled = false
	return applyLayout(view, props)
end

--- Runs an action when the user activates a native button.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop accessibilityLabel value optional. Component-specific setting passed to the native control.
--- @prop action function optional. Component-specific setting passed to the native control.
--- @prop disabled boolean optional. Component-specific setting passed to the native control.
--- @prop role string optional. Semantic action role, such as destructive.
--- @prop foregroundStyle string optional. Semantic foreground color, such as `accent`.
--- @prop size number optional. Component-specific setting passed to the native control.
--- @prop style string optional. Component-specific setting passed to the native control.
--- @prop systemImage string optional. Component-specific setting passed to the native control.
--- @prop title value optional. Component-specific setting passed to the native control.
--- @prop truncation string optional. Text truncation position: `head`, `middle`, or `tail`.
--- @prop weight value optional. Component-specific setting passed to the native control.
--- @example <Button title="Example" />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Button(props)
	local title = type(props) == "table" and (props.title or props[1] or "") or ""
	local action = type(props) == "table" and props.action or nil
	local button
	local font = type(props) == "table" and props.size
		and bridge._font(props.size, props.weight, false, props.design) or nil
	local style = type(props) == "table" and props.style or nil
	-- A plain button draws its label in the tint, as it does on AppKit.
	local foreground = type(props) == "table" and props.foregroundStyle or nil
	if style == "plain" and not foreground and type(props) == "table" then foreground = props.tint end
	if action then
		button = bridge._button(title, action, style or "default",
			props.systemImage or "", props.role or "", font, props.content,
			props.symbolSize or 0, foreground, props.weight, props.controlSize)
	else
		button = bridge._button(title, nil, style or "default",
			props.systemImage or "", props.role or "", font, props.content,
			props.symbolSize or 0, foreground, props.weight, props.controlSize)
	end
	if type(props) == "table" and props.truncation then
		local modes = { head = 3, tail = 4, middle = 5 }
		button.titleLabel.lineBreakMode = modes[props.truncation] or 4
		button.titleLabel.numberOfLines = 1
	end
	if type(props) == "table" and props.disabled ~= nil then
		button.enabled = not props.disabled
	end
	if type(props) == "table" and props.accessibilityLabel then
		button.accessibilityLabel = props.accessibilityLabel
	end
	-- SwiftUI `.tint`: prominent styles fill with it, plain styles draw in it.
	if type(props) == "table" and props.tint then
		button.tintColor = bridge._systemColor(props.tint)
	end
	return applyLayout(button, props)
end

--- Embeds a view in the current system glass effect.
--- @tag GlassEffect
--- @prop content value required. The view rendered inside the glass effect.
--- @prop style string optional. `regular` or `clear`.
--- @prop interactive boolean optional. Enables native interactive glass feedback.
--- @prop cornerRadius number optional. Native glass corner radius; omitted uses a capsule. Does not clip content.
--- @example <GlassEffect style="regular"><VStack>...</VStack></GlassEffect>
--- @platform UIKit UIGlassEffect and UIVisualEffectView (iOS 26+).
function UIKit.GlassEffect(props)
	props = props or {}
	local content = props.content or props[1]
	assert(content, "GlassEffect requires content")
	local view = bridge._glassEffect(content, props.style or "regular",
		props.cornerRadius, props.interactive == true)
	if props.accessibilityLabel then view.accessibilityLabel = props.accessibilityLabel end
	return applyLayout(view, props)
end

--- Groups nearby native glass surfaces into one system effect.
--- @tag GlassEffectContainer
--- @prop content value required. View containing the glass surfaces.
--- @prop spacing number optional. Distance at which neighboring effects begin to merge.
--- @platform UIKit UIGlassContainerEffect and UIVisualEffectView (iOS 26+).
function UIKit.GlassEffectContainer(props)
	props = props or {}
	local content = props.content or props[1]
	assert(content, "GlassEffectContainer requires content")
	local layout = {}
	for key, value in pairs(props) do
		if key ~= "spacing" then layout[key] = value end
	end
	return applyLayout(bridge._glassEffectContainer(content, props.spacing or 0), layout)
end

--- Opens or navigates to a destination when activated.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop label value optional. Component-specific setting passed to the native control.
--- @prop title value optional. Component-specific setting passed to the native control.
--- @prop url string optional. Component-specific setting passed to the native control.
--- @example <Link />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Link(props)
	props = props or {}
	assert(props.url, "Link requires a URL")
	return applyLayout(bridge._link(props.title or props.label or props[1] or props.url,
		props.url), props)
end

--- Presents a native menu of related commands.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop children table optional. Component-specific setting passed to the native control.
--- @prop items table optional. Component-specific setting passed to the native control.
--- @prop title value optional. Component-specific setting passed to the native control.
--- @prop systemImage string optional. SF Symbol shown on the menu button.
--- @prop imagePath string optional. Image file shown on the menu button.
--- @prop style string optional. `plain` or native `glass` button appearance.
--- @prop symbolSize number optional. SF Symbol point size.
--- @prop accessibilityLabel string optional. VoiceOver label for an icon-only menu.
--- @example <Menu />
--- @platform UIKit uses the UIKit implementation.
function UIKit.Menu(props)
	props = props or {}
	local button = bridge._menu(props.items or props.children or {},
		-- SwiftUI labels a symbol-only menu with its image alone.
		props.title or (props.systemImage and "" or "Menu"), props.systemImage or "", props.style or "plain",
		props.symbolSize, props.imagePath or "", props.cornerRadius)
	if props.accessibilityLabel then button.accessibilityLabel = props.accessibilityLabel end
	return applyLayout(button, props)
end

local UNAVAILABLE = { spacing = 8, imageSize = 28, actionsTop = 8 }

--- Presents a native empty, unavailable, or no-results state.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop children views optional. Action controls shown beneath the message, SwiftUI's `actions:`.
--- @prop description value optional. Secondary explanatory text for an unavailable state.
--- @prop descriptionAlignment string optional. `center` (default), `leading` or `trailing` text alignment of the description.
--- @prop imageSize number optional. Symbol or image size in points.
--- @prop lines number optional. Maximum number of visible text lines.
--- @prop spacing number optional. Component-specific setting passed to the native control.
--- @prop systemImage string optional. Component-specific setting passed to the native control.
--- @prop title value optional. Component-specific setting passed to the native control.
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.ContentUnavailable(props)
	props = props or {}
	-- SwiftUI's ContentUnavailableView takes the space it is offered and
	-- centers its message in it. The spacers make the stack flexible along
	-- its main axis, so it fills the parent's height and centers vertically.
	local content = { spacing = props.spacing or UNAVAILABLE.spacing, alignment = "center", UIKit.Spacer() }
	if props.systemImage then
		table.insert(content, (UIKit.SystemImage {
			props.systemImage,
			size = props.imageSize or UNAVAILABLE.imageSize,
			color = "secondary",
			accessibilityLabel = props.title or "",
		}))
	end
	if props.title then table.insert(content, (UIKit.Title(props.title))) end
	if props.description then
		-- The description keeps to the middle half of the pane, a readable
		-- measure like SwiftUI's; the spacers share the other half equally.
		table.insert(content, (UIKit.HStack {
			UIKit.Spacer(),
			UIKit.Label {
				props.description,
				alignment = props.descriptionAlignment or "center",
				flexGrow = 2, flexBasis = 0, flexShrink = 1,
				color = "secondary",
				lines = props.lines or 0,
			},
			UIKit.Spacer(),
			spacing = 0,
			fillWidth = true,
		}))
	end
	-- SwiftUI's `actions:` slot: child controls sit beneath the message and
	-- are centered with it, not pinned to the pane's bottom edge.
	if props[1] then
		local actions = { spacing = UNAVAILABLE.spacing, alignment = "center", paddingTop = UNAVAILABLE.actionsTop }
		for _, action in ipairs(props) do table.insert(actions, action) end
		table.insert(content, (UIKit.VStack(actions)))
	end
	table.insert(content, (UIKit.Spacer()))
	local view = UIKit.VStack(content)
	-- Full width too, so the description's half is half of the pane.
	if props.fillWidth == nil then view.fillWidth = true end
	return applyLayout(view, props)
end

--- Displays content using a native visual material.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop content value optional. Rendered child content or the control’s text value.
--- @prop material string optional. Component-specific setting passed to the native control.
--- @platform UIKit uses the UIKit implementation.
function UIKit.MaterialView(props)
	props = props or {}
	local content = props.content or props[1]
	assert(type(content) == "userdata", "MaterialView requires one content view")
	return applyLayout(bridge._materialView(props.material or "regular", content), props)
end

--- Represents an on/off value with a native switch or checkbox.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop action function optional. Component-specific setting passed to the native control.
--- @prop disabled boolean optional. Component-specific setting passed to the native control.
--- @prop is_on value optional. Current on/off value (legacy spelling).
--- @prop label value optional. Component-specific setting passed to the native control.
--- @example <Toggle />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Toggle(props)
	local label = type(props) == "table" and (props.label or props[1] or "") or ""
	local is_on = type(props) == "table" and props.is_on or false
	local action = type(props) == "table" and props.action or nil
	local control
	-- SwiftUI `onChange`: the handler receives the switch's new state.
	if type(props) == "table" and type(props.onChange) == "function" then
		action = function() props.onChange(control.on == true) end
	end
	if action then
		control = bridge._toggle(label, is_on, action)
	else
		control = bridge._toggle(label, is_on)
	end
	if type(props) == "table" and props.disabled ~= nil then
		control.enabled = not props.disabled
	end
	if label == "" then return applyLayout(control, props) end
	local labelView = UIKit.Label(label)
	labelView.numberOfLines = 1
	labelView.lineBreakMode = 4
	local row = UIKit.HStack {
		alignment = "center",
		labelView,
		UIKit.Spacer(),
		control,
	}
	return applyLayout(row, props)
end

--- Selects a numeric value within a continuous range.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop disabled boolean optional. Component-specific setting passed to the native control.
--- @prop max number optional. Component-specific setting passed to the native control.
--- @prop min number optional. Component-specific setting passed to the native control.
--- @prop onChange function optional. Callback invoked when the value changes.
--- @prop value table optional. Current selected, edited, or measured value.
--- @example <Slider />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Slider(props)
	props = props or {}
	local slider, onChange
	-- The native target reports no arguments; the handler reads the new value
	-- from the control, as Toggle does.
	if type(props.onChange) == "function" then
		onChange = function() props.onChange(slider.value) end
	end
	slider = bridge._slider(props.min or 0, props.max or 1,
		props.value or props.min or 0, onChange)
	if props.disabled ~= nil then slider.enabled = not props.disabled end
	return applyLayout(slider, props)
end

--- Increments or decrements a numeric value.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop disabled boolean optional. Component-specific setting passed to the native control.
--- @prop max number optional. Component-specific setting passed to the native control.
--- @prop min number optional. Component-specific setting passed to the native control.
--- @prop onChange function optional. Callback invoked when the value changes.
--- @prop step number optional. Component-specific setting passed to the native control.
--- @prop value table optional. Current selected, edited, or measured value.
--- @example <Stepper />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Stepper(props)
	props = props or {}
	local stepper, onChange
	if type(props.onChange) == "function" then
		onChange = function() props.onChange(stepper.value) end
	end
	stepper = bridge._stepper(props.min or 0, props.max or 100,
		props.value or props.min or 0, props.step or 1, onChange)
	if props.disabled ~= nil then stepper.enabled = not props.disabled end
	return applyLayout(stepper, props)
end

--- Selects one value from a set of options.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop action function optional. Component-specific setting passed to the native control.
--- @prop disabled boolean optional. Component-specific setting passed to the native control.
--- @prop options table optional. Selectable options or menu entries.
--- @prop style string optional. Component-specific setting passed to the native control.
--- @prop value table optional. Current selected, edited, or measured value.
--- @example <Picker />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Picker(props)
	props = props or {}
	local picker = bridge._picker(props.options or {}, props.value or 0,
		props.onChange or props.action,
		props.style or "automatic")
	if props.disabled ~= nil then picker.userInteractionEnabled = not props.disabled end
	return applyLayout(picker, props)
end

--- Selects a date or time value.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop disabled boolean optional. Component-specific setting passed to the native control.
--- @prop onChange function optional. Callback invoked when the value changes.
--- @prop time value optional. Whether the date picker includes time selection.
--- @prop timestamp number optional. Date value represented as a Unix timestamp.
--- @example <DatePicker />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.DatePicker(props)
	props = props or {}
	local picker = bridge._datePicker(props.timestamp or props.time, props.onChange)
	if props.disabled ~= nil then picker.enabled = not props.disabled end
	return applyLayout(picker, props)
end

--- Selects a color using the platform color control.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop color color optional. Component-specific setting passed to the native control.
--- @prop disabled boolean optional. Component-specific setting passed to the native control.
--- @prop onChange function optional. Callback invoked when the value changes.
--- @example <ColorPicker />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.ColorPicker(props)
	props = props or {}
	local picker = bridge._colorPicker(props.color, props.onChange)
	if props.disabled ~= nil then picker.enabled = not props.disabled end
	return applyLayout(picker, props)
end

--- Draws a native separator between adjacent content.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop orientation string optional. Component-specific setting passed to the native control.
--- @example <Separator />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Separator(props)
	props = props or {}
	return applyLayout(bridge._separator(props.orientation or "horizontal"), props)
end

UIKit.Divider = UIKit.Separator

--- Shows determinate or indeterminate progress.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop value table optional. Current selected, edited, or measured value.
--- @prop tint color optional. Progress color for determinate progress or activity color for the spinner.
--- @example <ProgressView />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.ProgressView(props)
	props = props or {}
	local view
	if props.value ~= nil then
		view = bridge._progressView(props.value)
	else
		view = bridge._progressIndicator()
	end
	if props.tint then
		local color = bridge._systemColor(props.tint)
		if props.value ~= nil then view.progressTintColor = color else view.color = color end
	end
	-- A linear ProgressView takes the width it is offered; the spinner does not.
	if props.value ~= nil then view.fillWidth = true end
	return applyLayout(view, props)
end

--- Shows a value within a range as a read-only capacity bar (SwiftUI `Gauge`).
--- @platform AppKit NSLevelIndicator. UIKit UIProgressView.
function UIKit.Gauge(props)
	props = props or {}
	local low, high = props.minValue or 0, props.maxValue or 1
	local value = tonumber(props.value) or low
	local fraction = high > low and (math.max(low, math.min(high, value)) - low) / (high - low) or 0
	local view = bridge._progressView(fraction)
	if props.tint then view.progressTintColor = bridge._systemColor(props.tint) end
	if props.accessibilityLabel then view.accessibilityLabel = props.accessibilityLabel end
	view.fillWidth = true
	return applyLayout(view, props)
end

function UIKit.Group(children)
	children = children or {}
	children.__appkitGroup = true
	return children
end

--- Aligns child views into rows and columns.
---
--- This component is backed by the platform control or container. Prefer its XML tag in an `.etlua` template; keep view-tree construction out of controllers.
--- @prop alignment value optional. Component-specific setting passed to the native control.
--- @prop content value optional. Rendered child content or the control’s text value.
--- @prop spacing number optional. Component-specific setting passed to the native control.
--- @example <Grid />
--- @platform AppKit uses the AppKit implementation. UIKit uses the UIKit implementation.
function UIKit.Grid(props)
	props = props or {}
	local columnWidths = {}
	for _, row in ipairs(props) do
		for column, child in ipairs(row) do
			local size = child.size
			local width = size and size.width or 0
			columnWidths[column] = math.max(columnWidths[column] or 0, width)
		end
	end
	local rows = {}
	for _, row in ipairs(props) do
		local rowProps = { spacing = props.spacing, alignment = props.alignment }
		for column, child in ipairs(row) do
			if columnWidths[column] and columnWidths[column] > 0 then
				child.fixedWidth = columnWidths[column]
			end
			table.insert(rowProps, child)
		end
		table.insert(rows, (UIKit.HStack(rowProps)))
	end
	props.content = nil
	for i = #props, 1, -1 do props[i] = nil end
	for _, row in ipairs(rows) do table.insert(props, row) end
	return UIKit.VStack(props)
end

function UIKit.ForEach(data, content)
	local out = { __appkitGroup = true }
	if type(data) ~= "table" then return out end
	for i, item in ipairs(data) do
		table.insert(out, (content(item, i)))
	end
	return out
end

function UIKit.sleep(seconds)
	local co = coroutine.running()
	if not co then
		error("sleep() must be called from within a coroutine (use async())")
	end
	bridge._timerAfter(seconds, function()
		resumeCoroutine(co)
	end)
	coroutine.yield()
end

--- Seconds of monotonic system time, for measuring real intervals: a
--- `sleep` resumes late whenever the main run loop is busy.
function UIKit.uptime()
	return bridge._uptime()
end

--- Puts `text` on the general pasteboard, as AppKit.copyToClipboard does.
function UIKit.copyToClipboard(text)
	bridge._clipboardCopy(text)
end

function UIKit.async(fn)
	local co = coroutine.create(fn)
	resumeCoroutine(co)
end

function UIKit.fetch(url)
	local co = coroutine.running()
	if not co then
		error("fetch() must be called from within a coroutine (use async())")
	end
	local body, err = nil, nil
	bridge._httpGet(url, function(b, e)
		body, err = b, e
		resumeCoroutine(co)
	end)
	coroutine.yield()
	if err then error(err) end
	return body
end

function UIKit.json_parse(str)
	local obj, err = bridge._jsonParse(str)
	if err then error(err) end
	return obj
end

function UIKit.fetch_json(url)
	local body = UIKit.fetch(url)
	return UIKit.json_parse(body)
end


--- App-scoped secrets stored by Apple's Keychain, outside project documents.
UIKit.Credentials = {
	get = bridge._credentialRead,
	set = bridge._credentialWrite,
	remove = bridge._credentialRemove,
}

--- Share an explicit set of Documents files as an archive using the system sheet.
--- Each item has `source` (relative to Documents) or `text`, and `name` inside the archive.
function UIKit.shareFiles(items, name)
	return bridge._shareFiles(items, name)
end

function UIKit.importTextFiles(completion)
	return bridge._importTextFiles(completion)
end

return UIKit