view.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
#include <algorithm>
#include <concepts>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <type_traits>
#include <utility>
#include <variant>
#include <vector>
 
#include "../reactive/runtime.hpp"
#include "../reactive/signal.hpp"
#include "../util/datetime.hpp"
#include "alignment.hpp"
#include "button_emphasis.hpp"
#include "button_style.hpp"
 
/// @file
/// @brief The toolkit-agnostic view tree: props, node kinds and their builders.
///
/// Specified in `docs/spec/ui/view_tree.md`.
 
namespace morph::ui {
 
/// @brief A widget event handler taking no arguments.
using Action = std::function<void()>;
 
/// @brief The identity of a Switch case, a Select option, a ForEach or Table row and a drag payload.
///
/// Never a floating-point number: morph ids can exceed 2^53.
using Key = std::variant<std::int64_t, std::string>;
 
/// @brief The stable identity of a slot: a bound property a renderer can refer to by number.
///
/// Whoever builds the tree assigns slot ids; the interpreter numbers every bound property of a document, and a
/// code-generating renderer names the value it reads after it (`v.s17`). `Mounted` does not use them. A slot made
/// from a bare callable has no id.
using SlotId = std::uint32_t;
 
/// @brief A slot's read together with its id, as `ui::slot` makes it; a `Prop` made from it is a slot with that id.
/// @tparam F A callable taking no arguments.
template <typename F>
struct SlotBinding {
    /// @brief The slot's id.
    SlotId id = 0;
    /// @brief Reads the slot's value; every signal it reads is a dependency.
    F read;
};
 
/// @brief A slot with an id.
/// @tparam F A callable taking no arguments.
/// @param slotId The slot's id.
/// @param read Reads the value; every signal it reads is a dependency.
/// @return What a `Prop` takes as a slot with @p slotId.
template <typename F>
[[nodiscard]] SlotBinding<std::decay_t<F>> slot(SlotId slotId, F&& read) {
    return SlotBinding<std::decay_t<F>>{.id = slotId, .read = std::forward<F>(read)};
}
 
namespace detail {
 
/// @brief Whether a type is a `SlotBinding`: false here, true for the specialisation below.
/// @tparam T The type.
template <typename T>
struct IsSlotBinding : std::false_type {};
 
/// @brief A `SlotBinding` is one.
/// @tparam F The read's type.
template <typename F>
struct IsSlotBinding<SlotBinding<F>> : std::true_type {};
 
/// @brief Whether `From` may become a constant `Prop<To>`: an implicit conversion that does not silently change
/// the kind of value.
///
/// Two implicit conversions are refused because they compile and then show something else. A pointer, a string
/// literal included, converts to `bool` as "not null", so `Prop<bool>{"false"}` would be `true`. A floating-point
/// value converts to an integral type by truncation, so `Prop<std::int64_t>{2.9}` would be `2`. Other narrowing,
/// such as `int` to `std::size_t`, is kept: `Prop<std::size_t> count = 0` is the ordinary way to write a count.
///
/// `From` is the source type as deduced for a forwarding reference; `To` is the property's value type.
template <typename From, typename To>
concept ConstantConvertible = std::convertible_to<From, To> &&
                              !(std::is_same_v<std::remove_cv_t<To>, bool> && std::is_pointer_v<std::decay_t<From>>) &&
                              !(std::is_integral_v<To> && std::is_floating_point_v<std::remove_cvref_t<From>>) &&
                              !IsSlotBinding<std::remove_cvref_t<From>>::value;
 
}  // namespace detail
 
/// @brief A node property: a constant, or a slot — a reactive read, with a stable id when it was given one.
///
/// A constant is set on the widget once and creates no reactive node. A slot becomes an equality-gated
/// `reactive::Computed` plus an `reactive::Effect` calling one widget setter. An input whose value is a slot is
/// controlled: after a user's edit, the widget shows what the slot says. A constant is not re-asserted.
///
/// A braced list cannot initialise a `Prop`, because the constant constructor deduces its argument's type: name
/// the type, as in `.options = std::vector<ui::SelectOption>{{...}, {...}}`.
/// @tparam T The property's value type.
template <typename T>
class Prop {
public:
    /// @brief The value-initialised constant.
    Prop()
        requires std::default_initializable<T>
        : _value{std::in_place_index<0>} {}
 
    /// @brief A constant.
    ///
    /// A callable is never a constant, even when it converts to `T`: a captureless lambda converts to a function
    /// pointer and that to `bool`, so `Prop<bool>{[] { return false; }}` would otherwise be the constant `true`.
    ///
    /// A pointer does not become a `bool` constant and a floating-point value does not become an integral one; see
    /// `detail::ConstantConvertible`.
    /// @tparam U A non-callable type that converts to `T` without changing the kind of value.
    /// @param value The constant.
    template <typename U>
        requires(!std::invocable<U&>) && detail::ConstantConvertible<U, T>
    Prop(U&& value)
        // A string literal converting to `T` decays here; that is the conversion.
        // NOLINTNEXTLINE(cppcoreguidelines-pro-bounds-array-to-pointer-decay)
        : _value{std::in_place_index<0>, static_cast<T>(std::forward<U>(value))} {}
 
    /// @brief A slot without an id.
    ///
    /// The read must be callable: an empty `std::function` or a null function pointer is refused here, where the
    /// mistake is made, rather than when a mount first calls it.
    /// @tparam F A callable taking no arguments and returning something convertible to `T`.
    /// @param binding Evaluated by the mount inside a `Computed`; every signal it reads is a dependency.
    /// @throws std::invalid_argument when `binding` is an empty `std::function` or a null function pointer.
    template <typename F>
        requires std::invocable<F&> && std::convertible_to<std::invoke_result_t<F&>, T>
    Prop(F binding) : _value{std::in_place_index<1>, Slot{.id = std::nullopt, .read = std::move(binding)}} {
        refuseEmpty();
    }
 
    /// @brief A slot with an id, as `ui::slot` makes it.
    /// @tparam F A callable taking no arguments and returning something convertible to `T`.
    /// @param binding The id and the read.
    /// @throws std::invalid_argument when the read is an empty `std::function` or a null function pointer.
    template <typename F>
        requires std::invocable<F&> && std::convertible_to<std::invoke_result_t<F&>, T>
    Prop(SlotBinding<F> binding)
        : _value{std::in_place_index<1>, Slot{.id = binding.id, .read = std::move(binding.read)}} {
        refuseEmpty();
    }
 
    /// @brief Whether this is a slot.
    /// @return True for a slot, false for a constant.
    [[nodiscard]] bool isBound() const noexcept { return _value.index() == 1; }
 
    /// @brief The constant. Only valid when `!isBound()`.
    /// @return The constant.
    /// @throws std::bad_variant_access when this is a slot.
    [[nodiscard]] T const& constant() const { return std::get<0>(_value); }
 
    /// @brief The slot's read. Only valid when `isBound()`.
    /// @return The read.
    /// @throws std::bad_variant_access when this is a constant.
    [[nodiscard]] std::function<T()> const& binding() const { return std::get<1>(_value).read; }
 
    /// @brief The slot's id.
    /// @return The id given through `ui::slot`; `nullopt` for a constant and for a slot made from a bare callable.
    [[nodiscard]] std::optional<SlotId> slotId() const noexcept {
        Slot const* const bound = std::get_if<1>(&_value);
        return bound == nullptr ? std::nullopt : bound->id;
    }
 
    /// @brief The current value: the constant, or the slot read once.
    /// @return The value.
    [[nodiscard]] T evaluate() const { return isBound() ? std::get<1>(_value).read() : std::get<0>(_value); }
 
private:
    /// @brief A slot: its id, if it has one, and its read.
    struct Slot {
        /// @brief The id, or none.
        std::optional<SlotId> id;
        /// @brief The read; never empty.
        std::function<T()> read;
    };
 
    /// @brief Refuses a slot whose read is empty: an empty `std::function` or a null function pointer.
    /// @throws std::invalid_argument when the read is empty.
    void refuseEmpty() const {
        if (!std::get<1>(_value).read) {
            throw std::invalid_argument{"ui::Prop: a binding must not be empty"};
        }
    }
 
    std::variant<T, Slot> _value;
};
 
/// @brief How a `Text` is styled; each backend maps a role to its theme.
enum class TextRole : std::uint8_t {
    Normal,   ///< Body text.
    Muted,    ///< Secondary text.
    Heading,  ///< A section heading.
    Error,    ///< An error message.
    Success,  ///< A confirmation.
    Section,  ///< The heading of a group within a list: body size, bold and muted, below a `Heading`.
};
 
/// @brief How a `TextInput` edits.
enum class TextInputMode : std::uint8_t {
    SingleLine,  ///< One line; Enter submits.
    Multiline,   ///< Several lines.
    Password,    ///< One line, masked.
};
 
/// @brief How a `Select` presents its options.
enum class SelectStyle : std::uint8_t {
    Dropdown,  ///< A closed field that opens a list.
    Radio,     ///< Every option visible, one marked.
};
 
/// @brief The direction a stack arranges, or a scroll area scrolls, its content.
enum class Axis : std::uint8_t {
    Vertical,    ///< Top to bottom.
    Horizontal,  ///< Left to right.
};
 
/// @brief What a `DateTimeInput` edits.
enum class DateMode : std::uint8_t {
    Date,      ///< A calendar date; the time of day is midnight in the display zone.
    DateTime,  ///< A date and a time of day.
};
 
/// @brief Whether a `FilePicker` chooses an existing file or a file to write.
enum class FilePickerMode : std::uint8_t {
    Open,  ///< An existing file.
    Save,  ///< A file to create or overwrite.
};
 
/// @brief What a message or a mark conveys, mapped to the theme's colours.
enum class Tone : std::uint8_t {
    Neutral,  ///< Nothing in particular.
    Info,     ///< Information.
    Ok,       ///< Success.
    Warn,     ///< Something to check.
    Err,      ///< A failure.
};
 
/// @brief The edge a `Drawer` slides in from, in reading direction.
enum class Side : std::uint8_t {
    Start,  ///< The left edge in a left-to-right layout.
    End,    ///< The right edge in a left-to-right layout.
};
 
/// @brief Where one step of a `Steps` indicator stands.
enum class StepState : std::uint8_t {
    Pending,  ///< Not started.
    Active,   ///< In progress.
    Done,     ///< Completed.
    Failed,   ///< Stopped by a failure.
};
 
/// @brief How many rows of a `Table` the user can select.
enum class SelectionMode : std::uint8_t {
    None,      ///< Rows can be activated, not selected.
    Single,    ///< At most one row.
    Multiple,  ///< Any number of rows.
};
 
/// @brief How much space a widget asks for along one dimension, in backend units (a character cell on the TUI).
struct Sizing {
    /// @brief The sizing rule.
    enum class Kind : std::uint8_t {
        Content,  ///< As much as the content needs.
        Fixed,    ///< Exactly `amount` units.
        Stretch,  ///< A share of the leftover space, weighted by `amount`.
    };
    /// @brief The rule.
    Kind kind = Kind::Content;
    /// @brief Units for `Fixed`, weight for `Stretch`, unused for `Content`.
    int amount = 0;
 
    /// @brief Size to the content.
    /// @return The sizing.
    [[nodiscard]] static constexpr Sizing content() noexcept { return {}; }
 
    /// @brief A fixed size.
    /// @param units The size in backend units.
    /// @return The sizing.
    [[nodiscard]] static constexpr Sizing fixed(int units) noexcept { return {.kind = Kind::Fixed, .amount = units}; }
 
    /// @brief A share of the leftover space.
    /// @param weight The share's weight.
    /// @return The sizing.
    [[nodiscard]] static constexpr Sizing stretch(int weight = 1) noexcept {
        return {.kind = Kind::Stretch, .amount = weight};
    }
 
    /// @brief Memberwise equality.
    /// @return Whether both rules and amounts match.
    bool operator==(Sizing const&) const = default;
};
 
/// @brief A widget's size request in both dimensions, and the bounds its extent is clamped into.
///
/// A bound clamps the extent the sizing gives, whatever the sizing: a stretch child's share stops at its maximum
/// and a content or fixed child takes at least its minimum. A negative bound, a minimum above its maximum and a
/// fixed amount outside its bounds are refused at mount (`std::logic_error`).
struct LayoutHints {
    /// @brief Along the horizontal axis.
    Sizing width{};
    /// @brief Along the vertical axis.
    Sizing height{};
    /// @brief The least width, in backend units; `nullopt` for none.
    std::optional<int> minWidth;
    /// @brief The most width, in backend units; `nullopt` for none.
    std::optional<int> maxWidth;
    /// @brief The least height, in backend units; `nullopt` for none.
    std::optional<int> minHeight;
    /// @brief The most height, in backend units; `nullopt` for none.
    std::optional<int> maxHeight;
    /// @brief Where the node sits across its row's, column's or grid row's axis; `nullopt` takes the container's
    ///        `align`.
    std::optional<Align> alignSelf;
 
    /// @brief Memberwise equality.
    /// @return Whether the sizings, the bounds and the alignment match.
    bool operator==(LayoutHints const&) const = default;
};
 
/// @brief What assistive technology announces for a node.
struct Accessibility {
    /// @brief The accessible name; empty leaves the widget's own text as its name.
    Prop<std::string> name;
    /// @brief The role, such as `"heading"`; empty leaves the kind's own role. Set once.
    std::string role;
};
 
/// @brief A keyboard chord a node handles while focus is inside it.
struct KeyBinding {
    /// @brief The chord: modifiers (`Ctrl`, `Shift`, `Alt`, `Meta`) joined to a key name, such as `"Ctrl+S"`.
    std::string chord;
    /// @brief Called when the chord is pressed.
    Action onPress;
};
 
/// @brief The part every node carries: visibility, enablement, layout, drag-and-drop, accessibility, test identity,
///        tooltip, surface, keyboard chords and autofocus.
struct Common {
    /// @brief Whether the widget is shown.
    Prop<bool> visible = true;
    /// @brief Whether the widget accepts input.
    Prop<bool> enabled = true;
    /// @brief The size request; set once.
    LayoutHints layout{};
    /// @brief Engaged: the widget can be dragged, and a drop delivers this key.
    Prop<std::optional<Key>> dragKey;
    /// @brief Whether a drop of a key is accepted; empty accepts every key. Used only when `onDrop` is set.
    std::function<bool(Key const&)> accepts;
    /// @brief Set: the widget is a drop target, called with the dropped key.
    std::function<void(Key)> onDrop;
    /// @brief The accessible name and role.
    Accessibility a11y{};
    /// @brief The stable identifier an automated test finds the widget by; empty means none. Set once.
    std::string testId;
    /// @brief The name a focus request after mount finds the widget by (`Mounted::focus`), such as a document
    ///        element's id; empty means none. Set once.
    std::string focusId;
    /// @brief Text shown while the pointer rests on the widget; empty shows none.
    Prop<std::string> tooltip;
    /// @brief The named token set of the theme that styles this node and everything inside it; empty is the
    ///        theme's default. Set once.
    std::string surface;
    /// @brief Chords handled while focus is inside the node; the innermost node declaring a chord takes it. For a
    ///        chord listed twice, the first entry is the one called.
    std::vector<KeyBinding> keys;
    /// @brief Whether the widget takes keyboard focus when the content it is part of mounts; the first such widget
    ///        in document order wins.
    bool autofocus = false;
};
 
/// @brief The state of a value a user edits or reads: whether it may be changed, must be given, is wrong, or is
///        being recomputed.
///
/// On text, which no user edits, `readonly` changes nothing; the other three mark it as they mark an input. A
/// constant default calls no setter.
struct FieldState {
    /// @brief Whether the user may not change the value. A read-only field shows its value and can take focus and
    ///        have its text selected; it takes no edit, submit or commit.
    Prop<bool> readonly = false;
    /// @brief Whether the field is marked as one that must be given. Only a mark: whether a value is missing is the
    ///        application's to decide and show through `errors`.
    Prop<bool> required = false;
    /// @brief The messages shown with the field, in order; empty shows none. Which errors show, and when, is
    ///        decided before they reach this property.
    Prop<std::vector<std::string>> errors;
    /// @brief Whether the value shown is the last known one while a newer one is computed.
    Prop<bool> stale = false;
};
 
struct NodeData;
 
/// @brief A view-tree node: immutable, shared data.
using Node = std::shared_ptr<NodeData const>;
 
/// @brief Static or bound text.
struct Text {
    /// @brief The text, UTF-8.
    Prop<std::string> text;
    /// @brief The style.
    Prop<TextRole> role = TextRole::Normal;
    /// @brief Read-only, required, errors and stale.
    FieldState field{};
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A push button.
struct Button {
    /// @brief The caption.
    Prop<std::string> label;
    /// @brief How much it stands out; set once.
    ButtonEmphasis emphasis = ButtonEmphasis::Normal;
    /// @brief Called on activation.
    Action onClick;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
    /// @brief The name of an icon in the theme's icon set, drawn beside the caption; empty shows none. Set once.
    std::string icon;
    /// @brief A push button or a list entry; set once.
    ButtonStyle style = ButtonStyle::Push;
    /// @brief Whether a list entry is the current one. Only an `Item` takes it: the mount refuses a bound or `true`
    ///        value on a push button.
    Prop<bool> selected = false;
};
 
/// @brief An editable text field. The backend never reports its own `setText` back through `onChange`.
struct TextInput {
    /// @brief The text the field shows.
    Prop<std::string> value;
    /// @brief Called with the new text after every user edit.
    std::function<void(std::string)> onChange;
    /// @brief Called with the text when the user submits (Enter in single-line mode).
    std::function<void(std::string)> onSubmit;
    /// @brief Called with the text when the user commits it: Enter in single-line mode, or focus leaving the field
    ///        after an edit.
    std::function<void(std::string)> onCommit;
    /// @brief Shown while the field is empty.
    Prop<std::string> placeholder;
    /// @brief Single-line, multiline or password; set once.
    TextInputMode mode = TextInputMode::SingleLine;
    /// @brief The unit the input shows beside its text, such as `kg`; empty shows none. Only a single-line or
    ///        password input shows one: the mount refuses a multiline input with a unit.
    Prop<std::string> unit;
    /// @brief The name of an icon in the theme's icon set, drawn at the field's leading edge; empty shows none. Only
    ///        a single-line or password input shows one: the mount refuses a multiline input with an icon. Set once.
    std::string icon;
    /// @brief The fraction digits a number is entered with, for a backend or a kit to read; -1 when the input does
    ///        not hold a number. Set once; the mount refuses places on a multiline input.
    int decimals = -1;
    /// @brief The field's label: its visible caption while `showLabel`; a form's cell draws it otherwise, beside
    ///        the input. Empty: none.
    Prop<std::string> label;
    /// @brief Whether the input draws `label` as a visible caption itself; set once. A form leaves it false, since
    ///        its cell draws the caption.
    bool showLabel = false;
    /// @brief Read-only, required, errors and stale.
    FieldState field{};
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A labelled check box.
struct Checkbox {
    /// @brief The caption.
    Prop<std::string> label;
    /// @brief Whether it is checked.
    Prop<bool> checked;
    /// @brief Called with the new state when the user toggles it.
    std::function<void(bool)> onToggle;
    /// @brief Read-only, required, errors and stale.
    FieldState field{};
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief One option of a `Select`.
struct SelectOption {
    /// @brief The option's identity.
    Key key;
    /// @brief The caption.
    std::string label;
 
    /// @brief Memberwise equality.
    /// @return Whether key and label match.
    bool operator==(SelectOption const&) const = default;
};
 
/// @brief A choice of one option.
struct Select {
    /// @brief The options, in order.
    Prop<std::vector<SelectOption>> options;
    /// @brief The selected key, or none. A key outside `options` shows no selection.
    Prop<std::optional<Key>> selected;
    /// @brief Called with the key the user chose.
    std::function<void(Key)> onSelect;
    /// @brief Called when the user opens the dropdown, whether or not it has options to show; a radio group is never
    ///        opened. A hint, such as retrying a fetch of the options that failed: a backend may not report it.
    Action onOpen;
    /// @brief Dropdown or radio; set once.
    SelectStyle style = SelectStyle::Dropdown;
    /// @brief The field's label: its visible caption while `showLabel`; a form's cell draws it otherwise, beside
    ///        the input. Empty: none.
    Prop<std::string> label;
    /// @brief Whether the input draws `label` as a visible caption itself; set once. A form leaves it false, since
    ///        its cell draws the caption.
    bool showLabel = false;
    /// @brief Read-only, required, errors and stale.
    FieldState field{};
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief One entry of a `Menu`: its label and its handler in one place, so there are no parallel lists.
///
/// An entry with `items` opens a submenu and is not itself chosen.
struct MenuItem {
    /// @brief The caption.
    Prop<std::string> label;
    /// @brief Called when the entry is chosen.
    Action onSelect;
    /// @brief The name of an icon in the theme's icon map; empty shows none. Set once.
    std::string icon;
    /// @brief The chord shown beside the label, such as `"Ctrl+S"`; empty shows none. Set once. It only shows the
    ///        chord: the binding that handles it is a `KeyBinding` on a node.
    std::string keys;
    /// @brief Engaged: the entry is checkable and shows this check mark; `nullopt`: not checkable. Choosing a
    ///        checkable entry runs `onSelect`, and the mark changes only when this binding does.
    Prop<std::optional<bool>> checked;
    /// @brief Whether the entry can be chosen; a disabled entry's submenu cannot be opened.
    Prop<bool> enabled = true;
    /// @brief The submenu's entries; empty: the entry is chosen rather than opened.
    std::vector<MenuItem> items;
};
 
/// @brief A vertical list of commands.
struct Menu {
    /// @brief The entries, in order; the list itself is set once, each entry's label, check mark and enablement
    ///        may be bound.
    std::vector<MenuItem> items;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief The largest spacing step: a `gap` or `padding` names a step from 0 (none) to this, which each backend maps
///        to its own distance (the theme's `space.<step>` on Qt Quick, cells on the terminal).
inline constexpr int kMaxSpacingStep = 5;
 
/// @brief A `gap` or `padding` as the spacing step a backend receives.
/// @param value The value as written.
/// @return @p value clamped to `[0, kMaxSpacingStep]`.
[[nodiscard]] constexpr int spacingStep(int value) noexcept { return std::clamp(value, 0, kMaxSpacingStep); }
 
/// @brief Children stacked top to bottom.
struct Column {
    /// @brief The children, in order; a null child is skipped.
    std::vector<Node> children;
    /// @brief Space between children: a spacing step, 0 to `kMaxSpacingStep`.
    int gap = 0;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
    /// @brief Where the children sit across the column (horizontally); set once.
    Align align = Align::Stretch;
    /// @brief Where the spare height goes while no shown child stretches; set once.
    Justify justify = Justify::Start;
};
 
/// @brief Children laid out left to right.
struct Row {
    /// @brief The children, in order; a null child is skipped.
    std::vector<Node> children;
    /// @brief Space between children: a spacing step, 0 to `kMaxSpacingStep`.
    int gap = 0;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
    /// @brief A table row's tone: disengaged when none was given; an engaged `Prop` whose value is `nullopt` has no
    ///        tone at the moment. Only `table`'s row view sets it; the mount refuses it on a row outside a table.
    std::optional<Prop<std::optional<Tone>>> tone;
    /// @brief Where the children sit across the row (vertically); set once.
    Align align = Align::Stretch;
    /// @brief Where the spare width goes while no shown child stretches; set once.
    Justify justify = Justify::Start;
};
 
/// @brief One cell of a `Grid`.
struct GridCell {
    /// @brief The cell's content; a null node leaves no cell.
    Node node;
    /// @brief How many columns it spans.
    int span = 1;
};
 
/// @brief Cells laid out row-major in a fixed number of columns.
struct Grid {
    /// @brief The column count.
    int columns = 1;
    /// @brief The cells, row-major.
    std::vector<GridCell> cells;
    /// @brief Space between cells: a spacing step, 0 to `kMaxSpacingStep`.
    int gap = 0;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
    /// @brief Where each cell's content sits vertically in its row; set once. A grid's columns share its width, so
    ///        there is no spare length to justify.
    Align align = Align::Stretch;
};
 
/// @brief Empty space that takes what its layout hints ask for.
struct Spacer {
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A titled frame around one child; a collapsible one is an accordion section.
struct Panel {
    /// @brief The title.
    Prop<std::string> title;
    /// @brief Shown beside the title, collapsed or not; may be null.
    Node header;
    /// @brief Space between frame and child: a spacing step, 0 to `kMaxSpacingStep`.
    int padding = 0;
    /// @brief The content; may be null.
    Node child;
    /// @brief Whether the user can collapse it; set once.
    bool collapsible = false;
    /// @brief Whether it is collapsed; used only when `collapsible`.
    Prop<bool> collapsed = false;
    /// @brief Called with the collapsed state the user asked for; used only when `collapsible`.
    std::function<void(bool)> onToggle;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A scrollable viewport around one child.
struct Scroll {
    /// @brief The content; may be null.
    Node child;
    /// @brief The scroll direction; set once.
    Axis axis = Axis::Vertical;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief One case of a `Switch`.
struct SwitchCase {
    /// @brief The selector value this case answers.
    Key key;
    /// @brief The content; may be null.
    Node node;
};
 
/// @brief Shows the case whose key the selector yields; remounts only when that key changes.
struct Switch {
    /// @brief Which case to show.
    Prop<Key> selector;
    /// @brief The cases; the first one with the selected key wins.
    std::vector<SwitchCase> cases;
    /// @brief Shown when no case matches; may be null, and then nothing is shown.
    Node fallback;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief One page of `Tabs`.
struct Tab {
    /// @brief The tab's caption; set once.
    std::string label;
    /// @brief The page content, mounted the first time the tab is selected.
    Node node;
};
 
/// @brief A tab bar over pages.
struct Tabs {
    /// @brief The pages, in order; set once.
    std::vector<Tab> tabs;
    /// @brief The selected page's index; an index past the last page shows none.
    Prop<std::size_t> selected;
    /// @brief Called with the index the user picked, and with the page still shown when a picked page fails to mount.
    std::function<void(std::size_t)> onSelect;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A modal overlay; its content is mounted only while it is open.
struct Dialog {
    /// @brief Whether it is shown.
    Prop<bool> open;
    /// @brief The title.
    Prop<std::string> title;
    /// @brief The content; may be null.
    Node child;
    /// @brief Called when the user dismisses it (Esc on the TUI).
    Action onDismiss;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A progress indicator.
struct Busy {
    /// @brief Whether it animates.
    Prop<bool> active;
    /// @brief A caption beside it.
    Prop<std::string> label;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
namespace detail {
 
/// @brief One mounted row of a ForEach or a Table: the row's signal, and the view built from it once.
class RowSlot {
public:
    RowSlot() = default;
    virtual ~RowSlot() = default;
    RowSlot(RowSlot const&) = delete;
    RowSlot& operator=(RowSlot const&) = delete;
    RowSlot(RowSlot&&) = delete;
    RowSlot& operator=(RowSlot&&) = delete;
 
    /// @brief Sets the row's signal to an entry of its session's latest snapshot; an equal row notifies nobody.
    /// @param index A position in that snapshot.
    virtual void assign(std::size_t index) = 0;
 
    /// @brief The view built for this row when the slot was made.
    /// @return The row's node.
    [[nodiscard]] virtual Node view() const = 0;
};
 
/// @brief One mount's use of a ForEach: the latest snapshot of the rows, and a way to make row slots from it.
class ForEachSession {
public:
    ForEachSession() = default;
    virtual ~ForEachSession() = default;
    ForEachSession(ForEachSession const&) = delete;
    ForEachSession& operator=(ForEachSession const&) = delete;
    ForEachSession(ForEachSession&&) = delete;
    ForEachSession& operator=(ForEachSession&&) = delete;
 
    /// @brief Reads the rows (tracked, inside the mount's Effect), keeps them as the snapshot, and returns their
    ///        keys.
    /// @return One key per row, in order, duplicates included.
    [[nodiscard]] virtual std::vector<Key> pull() = 0;
 
    /// @brief Makes the slot for one snapshot entry, building its view. The mount calls it untracked.
    /// @param index A position in the latest snapshot.
    /// @return The slot. It refers to this session, which must outlive it.
    [[nodiscard]] virtual std::unique_ptr<RowSlot> makeRow(std::size_t index) = 0;
};
 
/// @brief A ForEach's row source, key function and row view, with the row type erased.
class ForEachModel {
public:
    ForEachModel() = default;
    virtual ~ForEachModel() = default;
    ForEachModel(ForEachModel const&) = delete;
    ForEachModel& operator=(ForEachModel const&) = delete;
    ForEachModel(ForEachModel&&) = delete;
    ForEachModel& operator=(ForEachModel&&) = delete;
 
    /// @brief Starts one mount's session.
    /// @param runtime The runtime the row signals belong to.
    /// @return The session. It refers to this model, which must outlive it.
    [[nodiscard]] virtual std::unique_ptr<ForEachSession> open(reactive::Runtime& runtime) const = 0;
};
 
/// @brief The typed model behind `forEach<RowT>` and `table<RowT>`.
/// @tparam RowT The row type; copyable. With an `operator==`, an unchanged row notifies nobody; without one, every
///         new snapshot notifies every kept row.
template <typename RowT>
class TypedForEach final : public ForEachModel {
public:
    /// @param rows Reads the rows; every signal it reads is a dependency of the ForEach.
    /// @param keyOf A row's identity.
    /// @param rowView Builds a row's view once, from a signal the mount keeps equal to the row.
    /// @throws std::invalid_argument when any of the three is empty, as a `Prop` refuses an empty binding.
    TypedForEach(std::function<std::vector<RowT>()> rows, std::function<Key(RowT const&)> keyOf,
                 std::function<Node(reactive::Signal<RowT> const&)> rowView)
        : _rows{nonEmpty(std::move(rows))},
          _keyOf{nonEmpty(std::move(keyOf))},
          _rowView{nonEmpty(std::move(rowView))} {}
 
    [[nodiscard]] std::unique_ptr<ForEachSession> open(reactive::Runtime& runtime) const override {
        return std::make_unique<Session>(runtime, *this);
    }
 
private:
    template <typename F>
    [[nodiscard]] static F nonEmpty(F function) {
        if (!function) {
            throw std::invalid_argument{"ui::forEach: the rows, the key function and the row view must not be empty"};
        }
        return function;
    }
 
    class Slot final : public RowSlot {
    public:
        Slot(reactive::Runtime& runtime, std::vector<RowT> const& snapshot, std::size_t index,
             TypedForEach const& model)
            : _snapshot{&snapshot}, _row{runtime, snapshot.at(index)}, _view{model._rowView(_row)} {}
 
        void assign(std::size_t index) override { _row.set(_snapshot->at(index)); }
        [[nodiscard]] Node view() const override { return _view; }
 
    private:
        std::vector<RowT> const* _snapshot;
        reactive::Signal<RowT> _row;
        Node _view;
    };
 
    class Session final : public ForEachSession {
    public:
        Session(reactive::Runtime& runtime, TypedForEach const& model) : _rt{&runtime}, _model{&model} {}
 
        [[nodiscard]] std::vector<Key> pull() override {
            _snapshot = _model->_rows();
            std::vector<Key> keys;
            keys.reserve(_snapshot.size());
            for (RowT const& entry : _snapshot) {
                keys.push_back(_model->_keyOf(entry));
            }
            return keys;
        }
 
        [[nodiscard]] std::unique_ptr<RowSlot> makeRow(std::size_t index) override {
            return std::make_unique<Slot>(*_rt, _snapshot, index, *_model);
        }
 
    private:
        reactive::Runtime* _rt;
        TypedForEach const* _model;
        std::vector<RowT> _snapshot;
    };
 
    std::function<std::vector<RowT>()> _rows;
    std::function<Key(RowT const&)> _keyOf;
    std::function<Node(reactive::Signal<RowT> const&)> _rowView;
};
 
}  // namespace detail
 
/// @brief When a keyed row list realizes a widget only for the rows in or near the visible range, instead of for
///        every row regardless of scroll position. A row's own reactive state (its signal, rebuilt from the
///        session on every change) is unaffected either way and is never released while its key exists; this
///        setting only decides whether a row's mounted widget is also kept alive off-screen.
struct Virtualization {
    /// @brief Below this many rows, every row's widget is realized regardless of scroll position, matching
    ///        today's behavior exactly; set once.
    std::size_t threshold = 2000;
    /// @brief How many rows beyond the visible range, on each side, keep a realized widget so a small scroll does
    ///        not have to realize a widget on every frame; set once.
    std::size_t overscan = 10;
};
 
/// @brief One widget per row of a keyed collection, updated in place when a row with the same key changes.
struct ForEach {
    /// @brief The rows, the key function and the row view, type-erased; null shows no rows.
    std::shared_ptr<detail::ForEachModel const> model;
    /// @brief The direction rows are stacked in; set once.
    Axis axis = Axis::Vertical;
    /// @brief Space between rows: a spacing step, 0 to `kMaxSpacingStep`.
    int gap = 0;
    /// @brief Visibility, enablement, layout, drag-and-drop of the row container.
    Common common{};
};
 
/// @brief One column of a `Table`.
struct TableColumn {
    /// @brief The header caption.
    std::string label;
    /// @brief The column's width request.
    Sizing width = Sizing::content();
    /// @brief The text style of this column's default cell; `Normal` renders unchanged. Has no effect on a column
    ///        with its own `.cell`, or on a `Table` constructed directly without going through the interpreter.
    TextRole role = TextRole::Normal;
};
 
/// @brief Keyed rows of cells under column headers. Each row's view is a `Row` whose children are the cells, one
///        per column.
struct Table {
    /// @brief The columns, in order; set once.
    std::vector<TableColumn> columns;
    /// @brief The rows, the key function and the row view, type-erased; null shows no rows.
    std::shared_ptr<detail::ForEachModel const> rows;
    /// @brief Whether the header row is drawn; set once. `false` suits several tables sharing one header, or a
    ///        header a document draws itself.
    bool showHeader = true;
    /// @brief The row count and margin above which a row's widget is realized only near the visible range; set
    ///        once. A row's own reactive state is unaffected either way. Only a backend that implements
    ///        `TableWidget::setOnVisibleRangeChanged` ever dewindows a row; every other backend realizes every
    ///        row regardless of this setting, exactly as before it existed.
    Virtualization virtualize{};
    /// @brief How many rows the user can select; set once.
    SelectionMode selectionMode = SelectionMode::None;
    /// @brief The selected rows' keys. A key with no row selects nothing until such a row appears.
    Prop<std::vector<Key>> selection;
    /// @brief Called with the keys the user selected.
    std::function<void(std::vector<Key>)> onSelectionChange;
    /// @brief Called with a row's key when the user activates it (Enter or a double click).
    std::function<void(Key)> onActivate;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A date, or a date and time, edited in a display zone and reported as an instant.
struct DateTimeInput {
    /// @brief The instant shown; `nullopt` (or an empty `Timestamp`) shows an empty field.
    Prop<std::optional<morph::time::Timestamp>> value;
    /// @brief Called with the instant the user entered, or `nullopt` when they cleared the field.
    std::function<void(std::optional<morph::time::Timestamp>)> onChange;
    /// @brief Date or date and time; set once.
    DateMode mode = DateMode::DateTime;
    /// @brief The display zone's offset from UTC, in minutes; set once.
    int offsetMinutes = 0;
    /// @brief The field's label: its visible caption while `showLabel`; a form's cell draws it otherwise, beside
    ///        the input. Empty: none.
    Prop<std::string> label;
    /// @brief Whether the input draws `label` as a visible caption itself; set once. A form leaves it false, since
    ///        its cell draws the caption.
    bool showLabel = false;
    /// @brief Read-only, required, errors and stale.
    FieldState field{};
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief An integer chosen on a range.
struct Slider {
    /// @brief The value shown.
    Prop<std::int64_t> value;
    /// @brief The smallest value; set once.
    std::int64_t minimum = 0;
    /// @brief The largest value; set once.
    std::int64_t maximum = 100;
    /// @brief The increment between neighbouring values; set once.
    std::int64_t step = 1;
    /// @brief Called with the value the user moved to.
    std::function<void(std::int64_t)> onChange;
    /// @brief Called with the value a finished move ended on: a release after a drag, a key step, or a wheel step.
    std::function<void(std::int64_t)> onCommit;
    /// @brief Read-only, required, errors and stale.
    FieldState field{};
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A file path, typed or chosen in the platform's file dialog.
struct FilePicker {
    /// @brief The path shown.
    Prop<std::string> path;
    /// @brief Open an existing file or name one to save; set once.
    FilePickerMode mode = FilePickerMode::Open;
    /// @brief Called with the path the user picked.
    std::function<void(std::string)> onPicked;
    /// @brief Read-only, required, errors and stale.
    FieldState field{};
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A button inside another kind, such as a banner's action: its caption beside its handler.
struct ActionButton {
    /// @brief The caption; empty shows no button.
    Prop<std::string> label;
    /// @brief Called when the button is activated.
    Action onClick;
};
 
/// @brief A message across the top of a region, with an optional action and an optional dismissal.
struct Banner {
    /// @brief What the message conveys.
    Prop<Tone> tone = Tone::Info;
    /// @brief The message.
    Prop<std::string> text;
    /// @brief The button beside the message; an empty label shows none.
    ActionButton action{};
    /// @brief Whether the user can dismiss it; set once.
    bool dismissible = false;
    /// @brief Called when the user dismisses it. The banner stays shown until the application hides it.
    Action onDismiss;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A short label marking a state, such as a count or a status.
struct Badge {
    /// @brief What the mark conveys.
    Prop<Tone> tone = Tone::Neutral;
    /// @brief The label.
    Prop<std::string> text;
    /// @brief The name of an icon in the theme's icon map; empty shows none. Set once.
    std::string icon;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A progress bar.
struct Progress {
    /// @brief How far along, from 0 to 1; a value outside is shown at the nearer end. `nullopt`: indeterminate.
    Prop<std::optional<double>> value;
    /// @brief A caption beside the bar.
    Prop<std::string> label;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief One step of a `Steps` indicator.
struct Step {
    /// @brief The caption.
    std::string label;
    /// @brief Where it stands.
    StepState state = StepState::Pending;
 
    /// @brief Memberwise equality.
    /// @return Whether label and state match.
    bool operator==(Step const&) const = default;
};
 
/// @brief The steps of a process in order, each with its state.
struct Steps {
    /// @brief The steps.
    Prop<std::vector<Step>> items;
    /// @brief The step to highlight, by position; `nullopt` or a position past the last highlights none.
    Prop<std::optional<std::size_t>> current;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief One row of a `KeyValue` list.
struct KeyValueItem {
    /// @brief The caption.
    std::string label;
    /// @brief The value, as text.
    std::string value;
 
    /// @brief Memberwise equality.
    /// @return Whether label and value match.
    bool operator==(KeyValueItem const&) const = default;
};
 
/// @brief Captions beside their values, one pair per row.
struct KeyValue {
    /// @brief The pairs, in order.
    Prop<std::vector<KeyValueItem>> items;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief What a region shows when it has nothing to show: a title, an explanation and an optional action.
struct EmptyState {
    /// @brief The title.
    Prop<std::string> title;
    /// @brief The explanation.
    Prop<std::string> text;
    /// @brief The name of an icon in the theme's icon map; empty shows none. Set once.
    std::string icon;
    /// @brief The button below the text; an empty label shows none.
    ActionButton action{};
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A panel that slides in from one edge over the content: a `Dialog` with a side, and the same rules.
struct Drawer {
    /// @brief Whether it is shown.
    Prop<bool> open;
    /// @brief The title.
    Prop<std::string> title;
    /// @brief The content; may be null.
    Node child;
    /// @brief Called when the user dismisses it (Esc on the TUI).
    Action onDismiss;
    /// @brief The edge it slides in from; set once.
    Side side = Side::End;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A row of buttons in the footer of the dialog or drawer whose content holds it: what a document's overlay
///        `actions` lower to. The mount refuses one anywhere else.
struct ActionBar {
    /// @brief The buttons, in order; a null child is skipped.
    std::vector<Node> children;
    /// @brief Visibility, enablement, layout, drag-and-drop of the row.
    Common common{};
};
 
/// @brief Panes side by side, or stacked, with handles the user drags to share the space between them.
struct Splitter {
    /// @brief The panes, in order; a null child is skipped.
    std::vector<Node> children;
    /// @brief The axis the panes are laid out along; set once.
    Axis orientation = Axis::Horizontal;
    /// @brief Each pane's size, in backend units, in order; empty shares the space equally. A list whose length
    ///        differs from the number of panes is shared out as an empty one.
    Prop<std::vector<int>> sizes;
    /// @brief Called with every pane's size after the user dragged a handle.
    std::function<void(std::vector<int>)> onResize;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A titled section the user opens and closes. Its header stays usable while it is closed.
struct Collapsible {
    /// @brief The title.
    Prop<std::string> title;
    /// @brief Whether the content is shown.
    Prop<bool> open = true;
    /// @brief Called with the state the user asked for.
    std::function<void(bool)> onToggle;
    /// @brief Shown beside the title, open or closed; may be null.
    Node header;
    /// @brief The content; may be null. Mounted once, and hidden while closed.
    Node child;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief A region that takes files dropped from the operating system.
struct DropZone {
    /// @brief The extensions it takes, such as `".csv"`, compared without regard to case; empty takes every file.
    ///        Set once.
    std::vector<std::string> accept;
    /// @brief Whether a drop may carry more than one file; set once.
    bool multiple = false;
    /// @brief Called with the paths of a drop it took. A drop with a file outside `accept`, or with several files
    ///        when not `multiple`, is refused whole.
    std::function<void(std::vector<std::string>)> onDrop;
    /// @brief The content shown inside the region; may be null.
    Node child;
    /// @brief Visibility, enablement, layout, drag-and-drop.
    Common common{};
};
 
/// @brief One prop a loaded custom component is given.
struct CustomProp {
    /// @brief The prop's name, as the component declares it.
    std::string name;
    /// @brief Its value: text for `string`, `int`, `exact` and `json`, which cross as text so that no value loses
    ///        precision; a `bool`; or a `number`.
    std::variant<Prop<std::string>, Prop<bool>, Prop<double>> value;
};
 
/// @brief A component the backend may load (spec 5 §10), with the built-in nodes shown when it does not.
///
/// `Mounted` asks `IViewBackend::createCustom` first and mounts the fallback only when the backend loads nothing.
/// The fallback carries its own `Common`.
struct Custom {
    /// @brief The component's name, as the document's `components` declares it.
    std::string name;
    /// @brief The built-in nodes shown in its place; never null.
    Node fallback;
    /// @brief The props a loaded component is given, bound as any other property is.
    std::vector<CustomProp> props;
    /// @brief The lowest version of a host component that will do.
    int minVersion = 0;
    /// @brief Called with an event a loaded component raises: its name and its payload as the backend reports it.
    std::function<void(std::string event, std::string payload)> onEvent;
};
 
/// @brief What a `Node` points at: exactly one node kind.
struct NodeData {
    /// @brief The node.
    std::variant<Text, Button, TextInput, Checkbox, Select, Menu, Column, Row, Grid, Spacer, Panel, Scroll, Switch,
                 Tabs, Dialog, Busy, ForEach, Table, DateTimeInput, Slider, FilePicker, Banner, Badge, Progress, Steps,
                 KeyValue, EmptyState, Drawer, Splitter, Collapsible, DropZone, Custom, ActionBar>
        kind;
};
 
namespace detail {
 
/// @brief Wraps one node aggregate into a shared node.
/// @tparam Kind The node aggregate type.
/// @param spec The node.
/// @return The shared node.
template <typename Kind>
[[nodiscard]] Node makeNode(Kind spec) {
    return std::make_shared<NodeData const>(NodeData{.kind = std::move(spec)});
}
 
}  // namespace detail
 
/// @brief Static or bound text.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node text(Text spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A push button.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node button(Button spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief An editable text field.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node textInput(TextInput spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A labelled check box.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node checkbox(Checkbox spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A choice of one option.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node select(Select spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A list of commands.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node menu(Menu spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief Children stacked top to bottom.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node column(Column spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief Children laid out left to right.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node row(Row spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief Cells in a fixed number of columns.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node grid(Grid spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief Empty space.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node spacer(Spacer spec = {}) { return detail::makeNode(std::move(spec)); }
 
/// @brief A titled frame, optionally collapsible.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node panel(Panel spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A scrollable viewport.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node scroll(Scroll spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief Shows the case the selector picks. Spelled `switchOf` because `switch` is a keyword.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node switchOf(Switch spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A tab bar over pages.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node tabs(Tabs spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A modal overlay.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node dialog(Dialog spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A progress indicator.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node busy(Busy spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A date or date-and-time field.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node dateTimeInput(DateTimeInput spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief An integer on a range.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node slider(Slider spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A file path field.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node filePicker(FilePicker spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A message across the top of a region.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node banner(Banner spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A short label marking a state.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node badge(Badge spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A progress bar.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node progress(Progress spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief The steps of a process.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node steps(Steps spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief Captions beside their values.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node keyValue(KeyValue spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief What a region shows when it has nothing to show.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node emptyState(EmptyState spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A panel that slides in from one edge.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node drawer(Drawer spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief An action bar node.
/// @param spec The bar.
/// @return The node.
[[nodiscard]] inline Node actionBar(ActionBar spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief Panes with handles the user drags.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node splitter(Splitter spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A titled section the user opens and closes.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node collapsible(Collapsible spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A region that takes dropped files.
/// @param spec The node.
/// @return The node.
[[nodiscard]] inline Node dropZone(DropZone spec) { return detail::makeNode(std::move(spec)); }
 
/// @brief A component loaded by name, mounted by `Mounted` as its fallback.
/// @param spec The node.
/// @return The node.
/// @throws std::invalid_argument when the fallback is null: a renderer that cannot load the component has nothing
///         else to show.
[[nodiscard]] inline Node custom(Custom spec) {
    if (!spec.fallback) {
        throw std::invalid_argument{"morph::ui::custom: the fallback of a custom node is null"};
    }
    return detail::makeNode(std::move(spec));
}
 
/// @brief A Switch over an enumeration: each enumerator becomes the `int64` key of its case.
///
/// Enumerators are compared as `int64`: an unsigned value above `INT64_MAX` wraps to a negative key, and distinct
/// enumerators still give distinct keys.
/// @tparam E The enumeration.
/// @param selector Which enumerator to show; every signal it reads is a dependency.
/// @param cases One node per enumerator shown.
/// @param fallback Shown when no case matches; may be null.
/// @return The node.
/// @throws std::invalid_argument when @p selector is empty, as a `Prop` refuses an empty binding.
template <typename E>
    requires std::is_enum_v<E>
[[nodiscard]] Node switchOn(std::function<E()> selector, std::vector<std::pair<E, Node>> cases, Node fallback = {}) {
    if (!selector) {
        throw std::invalid_argument{"ui::switchOn: the selector must not be empty"};
    }
    std::vector<SwitchCase> keyed;
    keyed.reserve(cases.size());
    for (auto& [value, node] : cases) {
        keyed.push_back(SwitchCase{.key = Key{static_cast<std::int64_t>(value)}, .node = std::move(node)});
    }
    Switch spec{
        .selector = [current = std::move(selector)] { return Key{static_cast<std::int64_t>(current())}; },
        .cases = std::move(keyed),
    };
    spec.fallback = std::move(fallback);
    return switchOf(std::move(spec));
}
 
/// @brief One widget per row of a keyed collection read through a binding (a `Query`'s `value()` included).
///
/// A kept key keeps its widget, which a changed row updates in place; a new key is mounted, a gone key unmounted, and
/// the rows are brought into the snapshot's order by moving as few widgets as possible.
/// @tparam RowT The row type; copyable.
/// @param rows Reads the rows; every signal it reads is a dependency.
/// @param keyOf A row's identity; a later duplicate of a key is reported and refused, and the first one is kept.
/// @param rowView Builds a row's view once, from a signal the mount keeps equal to the row. Read the signal inside
///        bindings: what the view reads directly while it is built is read once and never again.
/// @param axis The stacking direction.
/// @param gap Space between rows.
/// @return The node.
/// @throws std::invalid_argument when @p rows, @p keyOf or @p rowView is empty.
template <typename RowT>
[[nodiscard]] Node forEach(std::function<std::vector<RowT>()> rows, std::function<Key(RowT const&)> keyOf,
                           std::function<Node(reactive::Signal<RowT> const&)> rowView, Axis axis = Axis::Vertical,
                           int gap = 0) {
    return detail::makeNode(ForEach{
        .model =
            std::make_shared<detail::TypedForEach<RowT> const>(std::move(rows), std::move(keyOf), std::move(rowView)),
        .axis = axis,
        .gap = gap,
    });
}
 
/// @brief One widget per row of a keyed collection held in a signal.
/// @tparam RowT The row type; copyable.
/// @param rows The signal; it must outlive every mount of the node.
/// @param keyOf A row's identity; a later duplicate of a key is reported and refused, and the first one is kept.
/// @param rowView Builds a row's view once, from a signal the mount keeps equal to the row.
/// @param axis The stacking direction.
/// @param gap Space between rows.
/// @return The node.
/// @throws std::invalid_argument when @p keyOf or @p rowView is empty.
template <typename RowT>
[[nodiscard]] Node forEach(reactive::Signal<std::vector<RowT>> const& rows, std::function<Key(RowT const&)> keyOf,
                           std::function<Node(reactive::Signal<RowT> const&)> rowView, Axis axis = Axis::Vertical,
                           int gap = 0) {
    return forEach<RowT>([&rows] { return rows.get(); }, std::move(keyOf), std::move(rowView), axis, gap);
}
 
/// @brief Everything about a `table` beyond its columns and rows.
struct TableOptions {
    /// @brief Whether the header row is drawn.
    bool showHeader = true;
    /// @brief The row count and margin above which a row's widget is realized only near the visible range.
    Virtualization virtualize{};
    /// @brief How many rows the user can select.
    SelectionMode selectionMode = SelectionMode::None;
    /// @brief The selected rows' keys.
    Prop<std::vector<Key>> selection;
    /// @brief Called with the keys the user selected.
    std::function<void(std::vector<Key>)> onSelectionChange;
    /// @brief Called with a row's key when the user activates it.
    std::function<void(Key)> onActivate;
    /// @brief Visibility, enablement, layout, drag-and-drop of the table.
    Common common{};
};
 
/// @brief What a table's row view builds for one row: its cells, one per column, and its tone.
struct TableRowView {
    /// @brief The cells, one non-null node per column.
    std::vector<Node> cells;
    /// @brief The row's tone, bound in the row's own scope; disengaged for none.
    std::optional<Prop<std::optional<Tone>>> tone;
};
 
/// @brief A table of keyed rows: one `Row` of cells per row, under the column headers.
///
/// Rows are mounted, updated, unmounted and reordered as `forEach` does. A row whose cells are not exactly one
/// non-null node per column would shift the columns after it, so it is refused as a row that fails to mount is:
/// reported, left out, and tried again on the next change of the rows.
/// @tparam RowT The row type; copyable.
/// @param columns The columns, in order.
/// @param rows Reads the rows; every signal it reads is a dependency.
/// @param keyOf A row's identity; a later duplicate of a key is reported and refused, and the first one is kept.
/// @param cells Builds a row's cells once, one per column, from a signal the mount keeps equal to the row. Read the
///        signal inside bindings: what the cells read directly while they are built is read once and never again.
/// @param options Selection, activation and `Common`.
/// @return The node.
/// @throws std::invalid_argument when @p rows, @p keyOf or @p cells is empty.
template <typename RowT>
[[nodiscard]] Node table(std::vector<TableColumn> columns, std::function<std::vector<RowT>()> rows,
                         std::function<Key(RowT const&)> keyOf,
                         std::function<std::vector<Node>(reactive::Signal<RowT> const&)> cells,
                         TableOptions options = {}) {
    if (!rows || !keyOf || !cells) {
        throw std::invalid_argument{"ui::table: the rows, the key function and the cells must not be empty"};
    }
    std::function<TableRowView(reactive::Signal<RowT> const&)> rowView =
        [cellsOf = std::move(cells)](reactive::Signal<RowT> const& entry) {
            return TableRowView{.cells = cellsOf(entry), .tone = std::nullopt};
        };
    return table<RowT>(std::move(columns), std::move(rows), std::move(keyOf), std::move(rowView), std::move(options));
}
 
/// @brief A table of keyed rows whose row view gives each row its tone as well as its cells.
///
/// As the other `table`, with @p rowView answering a `TableRowView`: the tone binds in the row's own scope, and the
/// table is told it after the row's key and on every change.
/// @tparam RowT The row type; copyable.
/// @param columns The columns, in order.
/// @param rows Reads the rows; every signal it reads is a dependency.
/// @param keyOf A row's identity; a later duplicate of a key is reported and refused, and the first one is kept.
/// @param rowView Builds a row's cells, one per column, and its tone, once, from a signal the mount keeps equal to
///        the row.
/// @param options Selection, activation and `Common`.
/// @return The node.
/// @throws std::invalid_argument when @p rows, @p keyOf or @p rowView is empty.
template <typename RowT>
[[nodiscard]] Node table(std::vector<TableColumn> columns, std::function<std::vector<RowT>()> rows,
                         std::function<Key(RowT const&)> keyOf,
                         std::function<TableRowView(reactive::Signal<RowT> const&)> rowView,
                         TableOptions options = {}) {
    if (!rows || !keyOf || !rowView) {
        throw std::invalid_argument{"ui::table: the rows, the key function and the row view must not be empty"};
    }
    std::function<Node(reactive::Signal<RowT> const&)> rowNode =
        [viewOf = std::move(rowView), count = columns.size()](reactive::Signal<RowT> const& entry) {
            TableRowView made = viewOf(entry);
            if (made.cells.size() != count ||
                std::ranges::any_of(made.cells, [](Node const& cell) { return cell == nullptr; })) {
                throw std::invalid_argument{"ui::table: a row needs exactly one non-null cell per column"};
            }
            return row(Row{.children = std::move(made.cells), .tone = std::move(made.tone)});
        };
    Table spec{
        .rows =
            std::make_shared<detail::TypedForEach<RowT> const>(std::move(rows), std::move(keyOf), std::move(rowNode)),
        .showHeader = options.showHeader,
        .virtualize = options.virtualize,
        .selectionMode = options.selectionMode,
    };
    spec.columns = std::move(columns);
    spec.selection = std::move(options.selection);
    spec.onSelectionChange = std::move(options.onSelectionChange);
    spec.onActivate = std::move(options.onActivate);
    spec.common = std::move(options.common);
    return detail::makeNode(std::move(spec));
}
 
}  // namespace morph::ui