From 069dfb67cd854a28e7c5f1281c85bbc7d4f58e81 Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sat, 14 Nov 2026 20:03:01 +0100 Subject: [PATCH 01/38] Design a compiled, optionally shared, library for morph's UI layer Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- .../2026-11-14-compiled-ui-library-design.md | 216 ++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-14-compiled-ui-library-design.md diff --git a/docs/superpowers/specs/2026-11-14-compiled-ui-library-design.md b/docs/superpowers/specs/2026-11-14-compiled-ui-library-design.md new file mode 100644 index 000000000..06e15eaa0 --- /dev/null +++ b/docs/superpowers/specs/2026-11-14-compiled-ui-library-design.md @@ -0,0 +1,216 @@ +# A compiled library for morph's UI layer + +`morph::morph` is a header-only `INTERFACE` target. Every translation unit that reaches the UI layer re-parses and +re-checks the whole interpreter, document model and service code. That cost is now the largest single item in a build, +and it is what makes CI's GitHub-hosted runners run out of memory. This design moves the non-template code of the UI +layer into compiled sources, so it is paid once per build instead of once per translation unit. It then makes the +library buildable as a shared library, as a configure-time choice. + +## Why + +Measured on master `4e99bac6f`, clang 23.1.4, with the `clang-coverage` preset's flags. Each row is peak front-end +memory for a file containing one `#include` and nothing else: + +``` + 109 MB + 338 MB + 632 MB + 726 MB + 1818 MB + 1306 MB + 2291 MB +``` + +`examples/lims/screens/tests/test_lims_ignition_screen.cpp` peaks at 3432 MB, and its `#include` lines alone take +3106 MB. 74 of 596 objects in a `clang-coverage` build depend on `interpreter.hpp`. A hosted runner has 16 GB and +4 vCPUs. Linux legs die with exit 143 or "The hosted runner lost communication with the server", with no compiler +error. Issue #1118 records the measurements. + +`interpreter.hpp` is 11,077 lines with 174 `inline` functions and 3 templates. `document.hpp` is 5,648 lines with 85 +`inline` functions and no templates. Most of that code is not generic. + +## Goals + +- `morph::morph` becomes a compiled library. Its non-template UI code lives in `src/ui/*.cpp`. +- Including `` alone peaks well under 1 GB in the front end, measured as above. +- `test_lims_ignition_screen.cpp` peaks under 2 GB in a `clang-coverage` compile. +- Every CI leg passes on GitHub-hosted runners, gcc-release included. +- `-DMORPH_BUILD_SHARED=ON` builds `morph` as a shared library that works on Linux and Windows (part B). +- No behaviour changes. The public API, its headers and their include paths stay as they are. + +## Non-goals + +- Templates stay in headers. `author.hpp` (100 templates), `forms/forms.hpp` (111), `core/bridge.hpp` (41) and the + template parts of `mount.hpp` and `view.hpp` are not split. +- No ABI promise. A shared `morph` may only be loaded by code built against the same version, and its SONAME carries + the full version so a mismatch fails at load. +- `morph_client`, `morph_tui`, `morph_qt_impl` and `morph_qt_quick` stay `STATIC` in both modes. + +## Part A: the static library + +### What may move + +Code moves out of a header only when its meaning does not depend on the including translation unit. That excludes: + +1. **Templates and `constexpr`/`consteval` functions.** +2. **Code whose meaning depends on a per-target macro, directly or through an include.** `MORPH_CLIENT_ONLY`, + `MORPH_REQUIRE_VETTED_HMAC`, `MORPH_TRACY_ENABLED` and `NDEBUG` change what `core/bridge.hpp`, + `core/registry.hpp`, `core/effects.hpp`, `core/records.hpp`, `core/profiler.hpp`, + `core/detail/owner_probe.hpp`, `session/session_auth.hpp` and `journal/action_log_json.hpp` compile to. + `morph_tests` undefines `MORPH_REQUIRE_VETTED_HMAC`, and the `morph_client_only_*` probes build with + `MORPH_CLIENT_ONLY`. None of the UI headers below `#if` on these macros. Eleven of them include headers that do. A + moved body that calls into, or depends on the layout of, macro-sensitive code is compiled once with the library's + settings, so the lane checks each such call. Today only default arguments differ, which is harmless. A difference in + behaviour or layout is a stop-and-report finding. +3. **Code whose types come from the includer.** + +Everything else in the UI headers may move: free `inline` functions, member functions defined in a class body, and +`detail` helpers. A `detail` helper moves into the `.cpp`'s unnamed namespace only if a tree-wide search (`include`, +`src`, `examples`, `tests`) finds no other user. `theme.hpp`'s `detail::channelOf` (used by `interpreter.hpp`), +`detail::hexColor` (used by `src/tui/display_widgets.cpp`) and `detail::numberOf` (used by `message.hpp`) are known +cases. They keep a declaration in the header and get an out-of-line definition. + +A function that moves keeps its declaration, and its Doxygen block, in the header, with `MORPH_API` (below) on it. A +class with any moved member carries `MORPH_API` on the class. In part A `MORPH_API` expands to nothing. Putting it on +now means part B does not touch every moved declaration a second time. + +Moving bodies removes code from what includers see. A header that compiled only because a moved body pulled in an +include breaks. Each lane builds every target, Qt, Qt Quick and TUI included, after each header. + +The 13 headers in scope have no function-local statics and no `inline` variables, so a static library neither drops +nor duplicates any object they define. + +### Build and packaging + +- `add_library(morph STATIC)` replaces `add_library(morph INTERFACE)`. Include directories, link libraries and compile + definitions become `PUBLIC`. Both header file sets become `PUBLIC`, keep `VERIFY_INTERFACE_HEADER_SETS`, and stay in + the existing `install(TARGETS morph EXPORT morphTargets …)` rule, which gains an `ARCHIVE` destination. +- `GenerateExportHeader` produces `morph/export.hpp` in the binary directory. It is added to `morph` through a + `FILE_SET` whose base is that directory, so both the build and the install find it. A static build sets + `MORPH_STATIC_DEFINE` `PUBLIC`. +- Sources are listed explicitly beside the target. Every lane adds to that list, so its conflicts are expected and + trivial. Resolve them by keeping every line. +- **Instrumentation.** `apply_coverage(morph)` and `apply_sanitizers(morph)` are called on the target, as + `src/client/CMakeLists.txt` does for `morph_client`. Without them `src/ui` has no coverage mapping, and the + sanitizer legs stop instrumenting the UI layer. With them, every target linking `morph` must itself be built with the + same sanitizer, or the link fails on `__asan_init`. The skeleton commit audits every consumer of `morph`, including + `morph_guard_probe_deps`, the try_compile probes, examples and benches, and states the result. +- WASM's global `-fexceptions` already reaches a compiled target. Windows and WASM link the static library like any + other. One that needs special handling is a finding to report. + +### Coverage + +The skeleton commit, not a later one, makes the coverage machinery see `src/ui`, so no lane ever runs a gate that +silently left its code out. + +- `scripts/coverage.sh`: `SOURCES` gains `src/ui`. +- `scripts/check_branch_coverage.py` filters on `include/morph/` at line 197 and line 440. Both accept `src/ui`, and + `src/ui` is scored together with `include/morph/ui` under the existing `include/morph/ui` floor. The script's + self-tests cover the new prefix. +- The Codecov "framework" component, now `include/morph/**`, gains `src/ui/**`. +- `scripts/branch_partial_allowlist.json` entries for `document.hpp` and `expression.hpp` move with the code they + point at. Hints are checked with the checker's own resolver on each commit. +- **The control is the report itself.** `check_coverage_roots.sh` and `check_coverage_objects.sh` inspect binaries and + roots, not archives, so they cannot tell that the library went uninstrumented. Each lane shows `src/ui/*.cpp` lines + with non-zero counts in its lcov output, and states that it checked. + +### Order of work + +1. **Skeleton (lane 1, first commit, pushed alone).** Target conversion, `export.hpp`, instrumentation and the + consumer audit, all coverage changes, and one small `src/ui` source. The library builds and every test passes. +2. **Interpreter (lane 1).** Move `interpreter.hpp`'s non-template code to `src/ui/interpreter.cpp`. Then **measure** + before anything else starts. `ScreenCore`'s and the other classes' definitions stay in the header, and it still + includes `bridge.hpp` (632 MB alone) and `document.hpp` (726 MB). So the 1 GB goal may need include pruning, with + forward declarations and moving includes into the `.cpp`. Lane 1 reports the figure and prunes what it can. +3. **In parallel, from the skeleton commit:** + - **Document lane:** `document.hpp` and `expression.hpp`, with their allowlist entries. + - **Services lane:** `service.hpp`, `service_client.hpp`, `host.hpp`, `workspace.hpp`, `shell_frame.hpp`, + `shell_parts_model.hpp`, `backend.hpp`, `theme.hpp`, `explorer.hpp` and `navigator.hpp`. +4. **Measure again** and report against the goals. If a goal is missed, the next candidates are `core/remote.hpp` + (3,406 lines, one template) and the non-template parts of `mount.hpp`. That decision is made on the measurement. + +One commit per header, so a bad move can be dropped on its own. + +### Verification + +- Every target builds and every test passes, with clang and gcc locally, Qt, Qt Quick and TUI included. +- The front-end figures above are re-measured the same way, before and after. +- The lcov output shows `src/ui/*.cpp` with non-zero counts, and the `include/morph/ui` branch floor holds. +- `scripts/check_install_export.sh`'s consumer today calls only `Rational` and `client::defaultSignIn`, so it never + links moved code. It gains a call that does, such as parsing a ui/1 document. +- **Performance.** `tests/bench_mount.cpp` includes only `mount.hpp`, which does not move, so it measures nothing + here. Lane 1 runs a bench that drives the interpreter, or adds one, before and after. A regression over 10% is + reported. +- clang-tidy-diff lints every moved line as changed. Lanes run clang-tidy on what they move and fix what it reports. + That is part of the move, not a reason to skip it. +- Windows and gcc-release can only be judged by CI, and their results are reported as measured there. + +### Documentation + +These all say header-only, and are updated to say what is now true: `docs/ARCHITECTURE.md`, `docs/BUILDING.md`, +`docs/spec/VERSIONING.md`, `docs/spec/ui/service.md`, `docs/spec/core/profiler.md`, `docs/spec/core/bridge.md`, +`docs/spec/core/backend.md`, `docs/spec/journal/journal.md` and `docs/spec/forms/forms.md`. A lane greps `docs/` for +"header-only" rather than trusting this list. `docs/BUILDING.md`'s claim that `-I/include` alone compiles is +replaced with linking `morph::morph`. + +## Part B: a shared library + +Part B starts after part A's lanes land on the branch. It goes on the same branch, in its own commits. + +### The option + +`MORPH_BUILD_SHARED` (default `OFF`) chooses `add_library(morph SHARED)`. It is morph's own option, not +`BUILD_SHARED_LIBS`, because `BUILD_SHARED_LIBS` would also make Catch2, Lightweight and Tracy shared. Catch2 v3 is not +built to be a Windows DLL. + +### Singletons must have one home + +The core headers hold process-wide state as function-local statics and `inline` variables: + +- `logState()` in `core/logger.hpp` +- `defaultDispatcher()` and `defaultRegistry()` in `core/registry.hpp` +- `screenRegistry()` in `ui/author.hpp` +- the owner probe in `core/detail/owner_probe.hpp` +- the effects, records and execute registries in `core/effects.hpp`, `core/records.hpp` and `core/bridge.hpp` +- thread-locals in `session/session.hpp` + +With `morph` as a DLL, each module that includes these gets its own copy. With `VISIBILITY_INLINES_HIDDEN` on Linux +the same is true per shared object. The compiled UI code would then log through, and dispatch to, a different instance +than the application. So: + +- Each non-template accessor moves out of line into the library, with `MORPH_API`. This touches core headers, and is + allowed because the accessor's body does not depend on the macros listed in part A. The lane checks each one, and + one that does depend on them is a stop-and-report finding. +- A per-type registry that is a template static stays one per module. The lane lists each one, and states whether it + is only reached from the module that instantiates it, which is safe, or across the boundary. A crossing case is a + finding to report with a proposed fix. +- `typeid` comparisons across the boundary (`core/registry.hpp`) and exceptions thrown from the library and caught + outside need exported type information. A test that exercises each across the boundary is part of the work. + +### Build + +- The shared target uses `CXX_VISIBILITY_PRESET hidden` and `VISIBILITY_INLINES_HIDDEN ON`. A missing `MORPH_API` + then fails to link on Linux as well as Windows. +- `install(TARGETS morph …)` gains `LIBRARY` and `RUNTIME` destinations. +- **Position-independent code.** core-cpp's modules are `STATIC`. `CMAKE_POSITION_INDEPENDENT_CODE ON` reaches them + only when core-cpp is built in-tree. With `MORPH_BUILD_SHARED`, a `find_package(core-cpp)` hit on a prebuilt + copy stops the configure with an error saying why, rather than failing at link. +- **Windows DLL lookup.** `CMAKE_RUNTIME_OUTPUT_DIRECTORY` puts `morph.dll` beside the executables, so ctest and + `catch_discover_tests` (in `cmake/morph_add_rung.cmake` and `examples/common/CMakeLists.txt`) can load it. +- **MSVC.** C4251 (exported class with a member of an unexported type such as `std::string`) and C4275 (exported class + with an unexported base, such as `RtScope : std::enable_shared_from_this` and `ScopeEnv : Environment` in + `interpreter.hpp`) are disabled on `morph` and its users, with a comment giving the version rule as the reason. + `dllexport` on a class instantiates every special member. A class that fails to compile because of that is fixed by + exporting members instead of the class. + +### CI + +`Linux / clang-release` and `Windows / clangcl-debug` configure with `-DMORPH_BUILD_SHARED=ON`. Every other leg stays +static. `scripts/check_install_export.sh` runs once for each mode. + +### Verification + +- A local `-DMORPH_BUILD_SHARED=ON` build with hidden visibility links and passes every test on Linux. +- A test shows that the logger, the default dispatcher and the screen registry are the same object when reached from + the library and from the executable. +- Windows shared is judged by CI. From 71f5167a70384a2b3037a34bae62139e8bc8f450 Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sat, 14 Nov 2026 21:56:41 +0100 Subject: [PATCH 02/38] Compile morph::morph as a static library, with src/ui as its first source morph::morph is now add_library(morph STATIC) instead of an INTERFACE target. Include dirs, link libraries and compile definitions are PUBLIC, both header file sets are PUBLIC and still verified, and the install rule gains an ARCHIVE destination. GenerateExportHeader writes morph/export.hpp (MORPH_API) into the binary dir, shipped through its own FILE_SET so build and install both find it; MORPH_STATIC_DEFINE is PUBLIC. The package version file is no longer ARCH_INDEPENDENT, since the package now holds an archive. src/ui/library.cpp holds fragmentOf and routeOfFragment, moved out of route_history.hpp (declarations stay, marked MORPH_API). apply_warnings, apply_sanitizers and apply_coverage are applied to morph. Coverage machinery now sees src/ui: coverage.sh SOURCES, the Codecov framework component, and check_branch_coverage.py, which scores src/ui under the include/morph/ui floor (self-tests extended; the new case fails when the prefix handling is removed). check_install_export.sh's consumer now calls a function from the compiled archive. With library.cpp reduced to an empty namespace the consumer fails to link (undefined reference to morph::ui::fragmentOf), so the check proves compiled code is linked. Sanitizer consumer audit (clang, AF_SANITIZER=asan, linux-everything options): 54 executables link libmorph.a. Six had no -fsanitize at link: the four examples/vetted_hmac executables and the two lims_cross_module_effects probes. They linked only because no archive member of libmorph.a was pulled in; the first moved symbol they use would fail on __asan_init. They now call apply_sanitizers; the re-audit shows 54 of 54 instrumented. Examples, benches, fuzz and soak targets already carried an AF_SANITIZER block. morph_guard_probe_deps and the try_compile probes do not link morph::morph (they link its dependencies or only take its include directories), so they are unaffected. Docs and comments that called morph header-only now describe the compiled static library. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- CMakeLists.txt | 86 ++++++++++++++++++----------- cmake/morphConfig.cmake.in | 2 +- codecov.yml | 1 + docs/ARCHITECTURE.md | 6 +- docs/BUILDING.md | 17 +++--- docs/spec/VERSIONING.md | 4 +- docs/spec/core/profiler.md | 2 +- examples/lims/CMakeLists.txt | 3 + examples/vetted_hmac/CMakeLists.txt | 12 ++++ include/morph/core/model.hpp | 2 +- include/morph/core/profiler.hpp | 4 +- include/morph/ui/route_history.hpp | 12 +--- scripts/check_branch_coverage.py | 36 ++++++++++-- scripts/check_install_export.sh | 6 +- scripts/coverage.sh | 2 +- src/ui/library.cpp | 19 +++++++ tests/CMakeLists.txt | 6 +- 17 files changed, 154 insertions(+), 66 deletions(-) create mode 100644 src/ui/library.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index de5876dc0..961adcc54 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -109,7 +109,7 @@ option(MORPH_REQUIRE_VETTED_HMAC # -- so it stays emitted regardless. See docs/spec/core/registry.md, # "MORPH_CLIENT_ONLY". # -# On the INTERFACE of the morph target, not per-consumer: the macro changes +# PUBLIC on the morph target, not per-consumer: the macro changes # which registrars a model header emits, so two translation units disagreeing # about it would violate ODR. Off by default: the standard build is unaffected. # @@ -244,8 +244,8 @@ endif() # because CPM passes OPTIONS as normal variables, which a -D on the command # line cannot override. # -# The define and the link are INTERFACE: morph is header-only, so the macros -# expand in the consumer's own translation units, and every one of them has +# The define and the link are PUBLIC: the macros expand in the consumer's own +# translation units as well as in the library's, and every one of them has # to agree on MORPH_TRACY_ENABLED (see profiler.hpp on why that is an ODR # matter). option(MORPH_ENABLE_TRACY "Instrument morph's hot paths with Tracy profiler zones (fetches Tracy if not installed)" OFF) @@ -315,9 +315,8 @@ endif() # morph uses there. SYSTEM, so morph's warning set does not apply to # core-cpp's headers. # -# morph stays a header-only INTERFACE target, but core::base, core::net and -# core::platform are static libraries, so every consumer of morph now builds -# them -- or links an installed core-cpp's. +# core::base, core::net and core::platform are static libraries, so every +# consumer of morph builds them -- or links an installed core-cpp's. # # Found first, as glaze is, and fetched only when no installed core-cpp # satisfies the bound. MORPH_CORE_CPP_VERSION is that bound, stated once @@ -407,38 +406,71 @@ if(NOT WIN32 AND NOT EMSCRIPTEN) find_package(Threads REQUIRED) endif() -# ── Header-only library target ─────────────────────────────────────────────── -add_library(morph INTERFACE) +# ── Library target ─────────────────────────────────────────────────────────── +# A static library: the templates and the macro-sensitive core headers stay in +# headers, and what does not depend on a consumer's configuration is compiled +# once, in src/ui. +include(GenerateExportHeader) +add_library(morph STATIC + src/ui/library.cpp +) add_library(morph::morph ALIAS morph) -target_include_directories(morph INTERFACE +target_include_directories(morph PUBLIC $ $ ) -target_link_libraries(morph INTERFACE glaze::glaze core::base core::async core::net) +target_link_libraries(morph PUBLIC glaze::glaze core::base core::async core::net) +target_compile_features(morph PUBLIC cxx_std_23) if(NOT EMSCRIPTEN) - target_link_libraries(morph INTERFACE core::platform) + target_link_libraries(morph PUBLIC core::platform) endif() if(NOT WIN32 AND NOT EMSCRIPTEN) - target_link_libraries(morph INTERFACE Threads::Threads) + target_link_libraries(morph PUBLIC Threads::Threads) endif() if(MORPH_REQUIRE_VETTED_HMAC) - target_compile_definitions(morph INTERFACE MORPH_REQUIRE_VETTED_HMAC) + target_compile_definitions(morph PUBLIC MORPH_REQUIRE_VETTED_HMAC) endif() if(MORPH_CLIENT_ONLY) - target_compile_definitions(morph INTERFACE MORPH_CLIENT_ONLY) + target_compile_definitions(morph PUBLIC MORPH_CLIENT_ONLY) endif() if(MORPH_ENABLE_TRACY) - target_compile_definitions(morph INTERFACE MORPH_TRACY_ENABLED) - target_link_libraries(morph INTERFACE Tracy::TracyClient) + target_compile_definitions(morph PUBLIC MORPH_TRACY_ENABLED) + target_link_libraries(morph PUBLIC Tracy::TracyClient) +endif() + +# MORPH_API marks what a consumer calls into the compiled library. A static +# build defines MORPH_STATIC_DEFINE for the library and its consumers, which +# makes the macro empty. +generate_export_header(morph + BASE_NAME MORPH + EXPORT_MACRO_NAME MORPH_API + EXPORT_FILE_NAME "${CMAKE_CURRENT_BINARY_DIR}/generated/morph/export.hpp" +) +target_compile_definitions(morph PUBLIC MORPH_STATIC_DEFINE) +apply_warnings(morph) +# Every consumer of this archive carries an AF_SANITIZER block of its own, which is what makes instrumenting a static +# library safe: the link options are PRIVATE and do not propagate out of a static library. +if(DEFINED AF_SANITIZER) + apply_sanitizers(morph ${AF_SANITIZER}) +endif() +if(AF_COVERAGE) + apply_coverage(morph) endif() +target_sources(morph + PUBLIC + FILE_SET morph_generated_headers TYPE HEADERS + BASE_DIRS ${CMAKE_CURRENT_BINARY_DIR}/generated + FILES ${CMAKE_CURRENT_BINARY_DIR}/generated/morph/export.hpp +) + set_target_properties(morph PROPERTIES VERIFY_INTERFACE_HEADER_SETS ON ) target_sources(morph - INTERFACE + PUBLIC FILE_SET HEADERS BASE_DIRS include FILES @@ -625,7 +657,7 @@ target_sources(morph # *public* header generated from the prefix: a public header that needs an # uninstalled detail/ header fails to compile there, whatever this list says. target_sources(morph - INTERFACE + PUBLIC FILE_SET morph_detail_headers TYPE HEADERS BASE_DIRS include FILES @@ -1263,6 +1295,8 @@ if(MORPH_INSTALL) EXPORT morphTargets FILE_SET HEADERS DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}" FILE_SET morph_detail_headers DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}" + FILE_SET morph_generated_headers DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}" + ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}" ) # Optional components ship only when this configuration actually created @@ -1375,24 +1409,14 @@ if(MORPH_INSTALL) # SameMajorVersion follows docs/spec/VERSIONING.md, which is what decides # this: there, minor releases are "additive and source-compatible" and # only a major breaks the stable surface, so an install of 0.2 does - # satisfy a consumer asking for 0.1. ARCH_INDEPENDENT only while every - # installed component is header-only: without it CMake rejects an install - # made on a differently-sized-void* machine, which is exactly right once a - # compiled archive (morph_qt_impl, morph::tui, - # morph::qt_quick) is in the package. - set(_morph_arch_independent ARCH_INDEPENDENT) - if(TARGET morph_qt_impl - OR "tui" IN_LIST MORPH_INSTALLED_COMPONENTS OR "qt_quick" IN_LIST MORPH_INSTALLED_COMPONENTS - OR "client" IN_LIST MORPH_INSTALLED_COMPONENTS) - set(_morph_arch_independent "") - endif() + # satisfy a consumer asking for 0.1. Not ARCH_INDEPENDENT: the package + # holds a compiled archive (morph::morph), which is built for one + # pointer size. write_basic_package_version_file( "${CMAKE_CURRENT_BINARY_DIR}/morphConfigVersion.cmake" VERSION ${PROJECT_VERSION} COMPATIBILITY SameMajorVersion - ${_morph_arch_independent} ) - unset(_morph_arch_independent) install(FILES "${CMAKE_CURRENT_BINARY_DIR}/morphConfig.cmake" diff --git a/cmake/morphConfig.cmake.in b/cmake/morphConfig.cmake.in index 029f1a5bc..296187d9b 100644 --- a/cmake/morphConfig.cmake.in +++ b/cmake/morphConfig.cmake.in @@ -4,7 +4,7 @@ # configure_package_config_file(); see the "Install & export" section of the # root CMakeLists.txt. # -# morph is header-only, but it is *not* dependency-free: morph::morph carries +# morph::morph is a compiled static library and is *not* dependency-free: it carries # glaze::glaze (and Threads) in its interface, and morphTargets.cmake names # those imported targets literally. Resolving them here rather than leaving it # to the consumer is not a convenience -- an exported target file that names a diff --git a/codecov.yml b/codecov.yml index 21088f2c0..d09d7aed5 100644 --- a/codecov.yml +++ b/codecov.yml @@ -170,6 +170,7 @@ component_management: name: "morph framework (include/morph)" paths: - include/morph/** + - src/ui/** statuses: - type: project target: 97% diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bacdb691d..aa883be47 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -4,7 +4,7 @@ `morph` is a typed, asynchronous bridge between a GUI thread and business-object models. Models may live in-process (local mode) or in a remote server process (remote mode). The GUI code is identical in both cases — only the backend implementation changes. -The core library, `morph::morph`, is header-only (C++23, namespace `morph`). It depends on Glaze for JSON reflection and on [core-cpp](https://github.com/contour-terminal/core-cpp) for its event-loop timers, base64 and wakeup primitive; core-cpp's `core::base`, `core::net` and `core::platform` are static libraries, so a project that links `morph::morph` also builds those. The optional parts are separate targets, and some are compiled: the Qt integration (`morph::qt`), the terminal frontend (`morph::tui`), the Qt Quick frontend (`morph::qt_quick`) and the generic client (`morph::client`) are static libraries with sources under `src/`. +The core library, `morph::morph`, is a compiled static library (C++23, namespace `morph`); its templates and the macro-sensitive core headers stay in headers. It depends on Glaze for JSON reflection and on [core-cpp](https://github.com/contour-terminal/core-cpp) for its event-loop timers, base64 and wakeup primitive; core-cpp's `core::base`, `core::net` and `core::platform` are static libraries, so a project that links `morph::morph` also builds those. The optional parts are separate targets, and some are compiled: the Qt integration (`morph::qt`), the terminal frontend (`morph::tui`), the Qt Quick frontend (`morph::qt_quick`) and the generic client (`morph::client`) are static libraries with sources under `src/`. > **New to morph?** `docs/GETTING-STARTED.md` is the step-by-step tutorial that > comes before this document: it builds one small app end to end @@ -908,7 +908,7 @@ commitment morph makes **starting at 1.0** is fully specified in `docs/spec/VERSIONING.md` — this section is only a pointer, not a substitute. In short: the per-topic public namespaces above (everything outside a `detail` namespace) are the stable surface; because -morph is header-only or static there is no shared-object ABI to preserve, so the promise is *source* +morph is a set of headers and static libraries there is no shared-object ABI to preserve, so the promise is *source* compatibility, checked against both a symbol's signature and its `docs/spec/` documented behavior. @@ -916,7 +916,7 @@ documented behavior. | Decision | Rationale | |---|---| -| Header-only core library | Zero build-system friction; include and use. The core stays headers only; core-cpp's static modules are built with it, and only the optional frontends, client and Qt transport are compiled. | +| Mostly-header core library | Templates and the macro-sensitive core headers stay in headers, so consumers compile them under their own configuration; what does not depend on that is compiled once into `morph::morph`, a static library. core-cpp's static modules are built with it, as are the optional frontends, client and Qt transport. | | core-cpp for timers, base64 and wakeup | One implementation shared with the other Contour Terminal projects, including a WebAssembly subset whose host-driven loop runs `TimeoutScheduler` on the browser's main thread. | | Per-topic public namespaces with per-topic `detail::` | Minimal public surface — callers see only what they need; internals are clearly walled off. | | A strand per `ModelId` | Parallelism across models; serial within one model — model authors write single-threaded code. | diff --git a/docs/BUILDING.md b/docs/BUILDING.md index 67db9741f..e11bb93e2 100644 --- a/docs/BUILDING.md +++ b/docs/BUILDING.md @@ -12,8 +12,9 @@ - **[core-cpp](https://github.com/contour-terminal/core-cpp) 0.7**, fetched through CPM. morph's timers run on its event loop, coroutines build on its `Task`, and `morph::net` takes its base64 and wakeup primitive from it. - morph itself is header-only, but `core::base`, `core::net` and - `core::platform` are static libraries, so a project that links + `morph::morph` is a static library (templates and the macro-sensitive core + headers stay in headers), and `core::base`, `core::net` and + `core::platform` are static libraries too, so a project that links `morph::morph` builds them too. - **Optional:** Qt 6 (WebSocket transport, Qt Quick frontend), libunicode (terminal frontend, fetched if not installed), SQLite3 (durable offline @@ -122,12 +123,14 @@ next to morph's. target. `MORPH_INSTALL` defaults to `PROJECT_IS_TOP_LEVEL`, so a vendored morph adds nothing to your project's install. -### A bare include path (not recommended) +### A bare include path (not supported) -`-I/include` compiles, since morph is header-only, but then nothing -supplies what the interface target would: Glaze at the pinned version, core-cpp -and its static libraries, a C++23 standard library, the thread library, and each -optional subsystem's own dependencies. Prefer `find_package`. +`-I/include` is not enough: morph::morph is a compiled static library, and +a bare include path neither links it nor supplies what the target carries: the +generated `morph/export.hpp`, Glaze at the pinned version, core-cpp and its +static libraries, a C++23 standard library, the thread library, and each +optional subsystem's own dependencies. Link `morph::morph`, through +`find_package` or `add_subdirectory`. ## API reference diff --git a/docs/spec/VERSIONING.md b/docs/spec/VERSIONING.md index 90b87c394..41f077bd7 100644 --- a/docs/spec/VERSIONING.md +++ b/docs/spec/VERSIONING.md @@ -69,8 +69,8 @@ including a patch. ## Semantic versioning applies to source compatibility, not ABI -morph's core is **header-only**, and its optional compiled parts (the Qt -integration, the frontends, the generic client) are static libraries +morph's core is a static library over headers that carry its templates, and its optional +compiled parts (the Qt integration, the frontends, the generic client) are static libraries ([ARCHITECTURE.md](../ARCHITECTURE.md)): there is no shared-object ABI to preserve, and none is promised — every consumer recompiles against the headers on every release. What semantic versioning diff --git a/docs/spec/core/profiler.md b/docs/spec/core/profiler.md index ed445e4e9..fc999707d 100644 --- a/docs/spec/core/profiler.md +++ b/docs/spec/core/profiler.md @@ -142,7 +142,7 @@ that turns it, under that thread's own name. ## One definition everywhere -morph is header-only, so these macros change the bodies of inline functions. +These macros change the bodies of inline functions, and most of morph is templates and inline functions in headers. A program in which one translation unit is compiled with `MORPH_TRACY_ENABLED` and another without it holds two definitions of the same inline function — an ODR violation the linker resolves by keeping one, diff --git a/examples/lims/CMakeLists.txt b/examples/lims/CMakeLists.txt index 04d36e820..6d07c0982 100644 --- a/examples/lims/CMakeLists.txt +++ b/examples/lims/CMakeLists.txt @@ -91,6 +91,9 @@ if(MORPH_BUILD_TESTS AND NOT EMSCRIPTEN) add_executable(lims_cross_module_effects_${_variant} tests/compile_checks/cross_module_effects_probe.cpp) target_link_libraries(lims_cross_module_effects_${_variant} PRIVATE ladder_lims_lib) set_target_properties(lims_cross_module_effects_${_variant} PROPERTIES EXPORT_COMPILE_COMMANDS OFF) + if(DEFINED AF_SANITIZER) + apply_sanitizers(lims_cross_module_effects_${_variant} ${AF_SANITIZER}) + endif() add_test(NAME lims.cross_module_effects.${_variant} COMMAND lims_cross_module_effects_${_variant}) endforeach() target_compile_definitions(lims_cross_module_effects_refused PRIVATE LIMS_PROBE_DECLARES_LEDGER_EFFECT=1) diff --git a/examples/vetted_hmac/CMakeLists.txt b/examples/vetted_hmac/CMakeLists.txt index 0b7bc3577..f78cb3200 100644 --- a/examples/vetted_hmac/CMakeLists.txt +++ b/examples/vetted_hmac/CMakeLists.txt @@ -26,6 +26,9 @@ if(MORPH_BUILD_HMAC_EXAMPLE_LIBSODIUM) add_executable(morph_vetted_hmac_libsodium_demo libsodium_adapter_demo.cpp) target_link_libraries(morph_vetted_hmac_libsodium_demo PRIVATE morph::morph PkgConfig::SODIUM) apply_bigobj(morph_vetted_hmac_libsodium_demo) + if(DEFINED AF_SANITIZER) + apply_sanitizers(morph_vetted_hmac_libsodium_demo ${AF_SANITIZER}) + endif() # Deliberately NOT calling apply_warnings() here — libsodium's public # headers are not -Weverything/-Werror clean and would fail the strict # build (same rationale as examples/bank/CMakeLists.txt's ORM headers). @@ -47,6 +50,9 @@ if(MORPH_BUILD_HMAC_EXAMPLE_LIBSODIUM) target_link_libraries(morph_vetted_hmac_libsodium_tests PRIVATE morph::morph PkgConfig::SODIUM morph_test_main) apply_bigobj(morph_vetted_hmac_libsodium_tests) + if(DEFINED AF_SANITIZER) + apply_sanitizers(morph_vetted_hmac_libsodium_tests ${AF_SANITIZER}) + endif() list(APPEND CMAKE_MODULE_PATH ${Catch2_DIR}) include(Catch) @@ -62,6 +68,9 @@ if(MORPH_BUILD_HMAC_EXAMPLE_OPENSSL) add_executable(morph_vetted_hmac_openssl_demo openssl_adapter_demo.cpp) target_link_libraries(morph_vetted_hmac_openssl_demo PRIVATE morph::morph OpenSSL::Crypto) apply_bigobj(morph_vetted_hmac_openssl_demo) + if(DEFINED AF_SANITIZER) + apply_sanitizers(morph_vetted_hmac_openssl_demo ${AF_SANITIZER}) + endif() # Deliberately NOT calling apply_warnings() here — OpenSSL's public # headers are not -Weverything/-Werror clean and would fail the strict # build (same rationale as examples/bank/CMakeLists.txt's ORM headers). @@ -79,6 +88,9 @@ if(MORPH_BUILD_HMAC_EXAMPLE_OPENSSL) target_link_libraries(morph_vetted_hmac_openssl_tests PRIVATE morph::morph OpenSSL::Crypto morph_test_main) apply_bigobj(morph_vetted_hmac_openssl_tests) + if(DEFINED AF_SANITIZER) + apply_sanitizers(morph_vetted_hmac_openssl_tests ${AF_SANITIZER}) + endif() list(APPEND CMAKE_MODULE_PATH ${Catch2_DIR}) include(Catch) diff --git a/include/morph/core/model.hpp b/include/morph/core/model.hpp index db9d50aae..127a8f07c 100644 --- a/include/morph/core/model.hpp +++ b/include/morph/core/model.hpp @@ -16,7 +16,7 @@ // strand.hpp defines no symbol this header uses. It is kept deliberately: // consumers (tests/test_model.cpp among them) reach -// morph::exec::detail::ModelId through it, and for a header-only public library +// morph::exec::detail::ModelId through it, and for a public library whose headers carry most of its code, // dropping a transitive include is a source-breaking change for its users -- // not worth the tidiness. The include above is the real gap it was // masking; this file uses std::same_as and `concept` without including it. diff --git a/include/morph/core/profiler.hpp b/include/morph/core/profiler.hpp index 28d5896d7..b94474852 100644 --- a/include/morph/core/profiler.hpp +++ b/include/morph/core/profiler.hpp @@ -30,8 +30,8 @@ /// zones would then close out of order with the open one. /// /// @par Every translation unit must agree -/// morph is header-only, so these macros change the bodies of inline -/// functions. A program in which one translation unit sees +/// The macros change the bodies of inline functions, and most of morph is +/// templates and inline functions in headers. A program in which one translation unit sees /// `MORPH_TRACY_ENABLED` and another does not holds two different definitions /// of the same inline function, which is an ODR violation: the linker keeps /// one of them, silently. CMake consumers get agreement by construction, diff --git a/include/morph/ui/route_history.hpp b/include/morph/ui/route_history.hpp index 4a6a5c6fe..626724077 100644 --- a/include/morph/ui/route_history.hpp +++ b/include/morph/ui/route_history.hpp @@ -3,6 +3,7 @@ #include #include +#include #include #include #include @@ -46,19 +47,12 @@ class IHistory { /// @brief The URL fragment that holds a route. /// @param route The route. /// @return `#/` followed by the route. -[[nodiscard]] inline std::string fragmentOf(std::string_view route) { - std::string fragment{"#/"}; - fragment += route; - return fragment; -} +[[nodiscard]] MORPH_API std::string fragmentOf(std::string_view route); /// @brief The route a URL fragment holds. /// @param fragment The fragment, with its `#`. /// @return The route after `#/`, or empty for a fragment of any other form. -[[nodiscard]] inline std::string routeOfFragment(std::string_view fragment) { - constexpr std::string_view prefix{"#/"}; - return fragment.starts_with(prefix) ? std::string{fragment.substr(prefix.size())} : std::string{}; -} +[[nodiscard]] MORPH_API std::string routeOfFragment(std::string_view fragment); /// @brief Keeps the route of the screen a shell shows in a history, and opens the route of an entry the user moves /// to (spec 3 §10). diff --git a/scripts/check_branch_coverage.py b/scripts/check_branch_coverage.py index b90223b7d..2cc2b4846 100644 --- a/scripts/check_branch_coverage.py +++ b/scripts/check_branch_coverage.py @@ -189,15 +189,29 @@ def parse_lcov(path, repo_root): return files +# The compiled half of morph::ui lives in src/ui and is scored with the headers under include/morph/ui, under the same +# floor: moving code from a header to a translation unit must not move it out of the gate. +COMPILED_UI_PREFIX = "src/ui/" + + +def subsystem_of(path): + """The FLOORS key a source path is scored under, or None when the gate does not score it.""" + if path.startswith(COMPILED_UI_PREFIX): + return "include/morph/ui" + if not path.startswith("include/morph/"): + return None + parts = path.split("/") + return "/".join(parts[:3]) if len(parts) > 3 else TOP_LEVEL_BUCKET + + def summarise(files): """subsystem -> [arms, taken, partial lines], plus per-file partial counts.""" subsystems = collections.defaultdict(lambda: [0, 0, 0]) per_file = collections.Counter() for path, lines in files.items(): - if not path.startswith("include/morph/"): + subsystem = subsystem_of(path) + if subsystem is None: continue - parts = path.split("/") - subsystem = "/".join(parts[:3]) if len(parts) > 3 else TOP_LEVEL_BUCKET bucket = subsystems[subsystem] for record in lines.values(): bucket[0] += len(record["arms"]) @@ -437,7 +451,7 @@ def partial_line_set(files): """{(path, line)} for every line that ran and left an arm untaken.""" partials = set() for path, lines in files.items(): - if not path.startswith("include/morph/"): + if subsystem_of(path) is None: continue for number, record in lines.items(): if record["hits"] > 0 and record["arms"] and not all(record["arms"]): @@ -721,6 +735,20 @@ def with_partial_line(arms=(True, False)): else: note("ok: a subsystem with no floor of its own is rejected") + # 4b. A compiled source under src/ui is scored under include/morph/ui's floor: a + # below-floor src/ui file fails the gate even though every header is fine, and + # a covered one is accepted. Without the prefix the file is not in any bucket. + sunk_ui = {"src/ui/sunk.cpp": [(n, 1, [True, False]) for n in range(10, 400)]} + code, output = run(_every_subsystem(sunk_ui)) + if code == 0 or "include/morph/ui branch coverage" not in output: + fail("a below-floor src/ui source was not scored under include/morph/ui", output) + else: + note("ok: src/ui sources are scored under the include/morph/ui floor") + if subsystem_of("src/ui/interpreter.cpp") != "include/morph/ui" or subsystem_of("src/tui/x.cpp") is not None: + fail("subsystem_of maps src/ui wrongly, or scores src/tui") + else: + note("ok: subsystem_of maps src/ui and nothing else under src/") + # 5. A partial line is a line that RAN with an untaken arm -- not a line that # never ran. Conflating the two would let this gate report partials where # the line data already says "miss", and miss them where it says "hit". diff --git a/scripts/check_install_export.sh b/scripts/check_install_export.sh index d856b9ba8..b08aff015 100755 --- a/scripts/check_install_export.sh +++ b/scripts/check_install_export.sh @@ -152,7 +152,7 @@ if [ "$skip_header_set_verification" -eq 0 ]; then fi fi -# morph is header-only, but morph::morph links core-cpp's static modules, and +# morph::morph is a static library that links core-cpp's static modules, and # morph's install installs them with core-cpp's package. They have to be built # first: installing an unbuilt tree fails with "file INSTALL cannot find". run_step "the library did not build" \ @@ -270,6 +270,10 @@ int main() { if (!morph::client::defaultSignIn(morph::ui::Value{reply}).has_value()) { return 1; } + // A call into morph::morph's own archive, so the consumer links compiled morph code rather than only its headers. + if (morph::ui::routeOfFragment(morph::ui::fragmentOf("orders/42")) != "orders/42") { + return 1; + } std::printf("morph %d.%d.%d consumed from the install prefix\n", MORPH_VERSION_MAJOR, MORPH_VERSION_MINOR, MORPH_VERSION_PATCH); return 0; diff --git a/scripts/coverage.sh b/scripts/coverage.sh index 819ddae9b..3e664ee8b 100644 --- a/scripts/coverage.sh +++ b/scripts/coverage.sh @@ -205,7 +205,7 @@ done <<< "$_MORPH_LADDER_RUNGS" # source-tree path named here, so moc output is excluded automatically — # no separate exclusion mechanism needed. Demo src/, system headers and # fetched dependencies are excluded the same way. -SOURCES=(include/morph) +SOURCES=(include/morph src/ui) # examples/common only when this configure also built the ladder # (MORPH_BUILD_LADDER=ON -- see the "coverage leg only" Qt install step in # ci.yml), so this script still works unchanged for a plain diff --git a/src/ui/library.cpp b/src/ui/library.cpp new file mode 100644 index 000000000..1ec5c550b --- /dev/null +++ b/src/ui/library.cpp @@ -0,0 +1,19 @@ +// SPDX-License-Identifier: Apache-2.0 +#include +#include +#include + +namespace morph::ui { + +std::string fragmentOf(std::string_view route) { + std::string fragment{"#/"}; + fragment += route; + return fragment; +} + +std::string routeOfFragment(std::string_view fragment) { + constexpr std::string_view prefix{"#/"}; + return fragment.starts_with(prefix) ? std::string{fragment.substr(prefix.size())} : std::string{}; +} + +} // namespace morph::ui diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index c42b01131..7bdc8d7d7 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -510,10 +510,10 @@ endif() # # NOTE (deviation from the plan): try_compile()'s LINK_LIBRARIES only accepts # system libraries and *Imported* targets from the calling project (see the -# try_compile() docs) — `morph` is a plain (non-imported) INTERFACE library +# try_compile() docs) — `morph` is a plain (non-imported) library # defined in this same project, so `LINK_LIBRARIES morph::morph` fails with -# "the target was not found" (confirmed experimentally). Since morph and glaze -# are both header-only for this probe's purposes, we instead read their +# "the target was not found" (confirmed experimentally). Since the probe only +# includes headers from morph and glaze, we instead read their # INTERFACE_INCLUDE_DIRECTORIES via get_target_property() — which works for # any target, imported or not, because it queries the calling project's own # configure state rather than the try_compile scratch project — and forward From 31bb0d4874daa2e374a1f31203686d614ac12dbe Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sat, 14 Nov 2026 21:57:29 +0100 Subject: [PATCH 03/38] Set the GCC -O3 memory target for the compiled UI library Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- .../specs/2026-11-14-compiled-ui-library-design.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/superpowers/specs/2026-11-14-compiled-ui-library-design.md b/docs/superpowers/specs/2026-11-14-compiled-ui-library-design.md index 06e15eaa0..395d4bbff 100644 --- a/docs/superpowers/specs/2026-11-14-compiled-ui-library-design.md +++ b/docs/superpowers/specs/2026-11-14-compiled-ui-library-design.md @@ -34,7 +34,11 @@ error. Issue #1118 records the measurements. - `morph::morph` becomes a compiled library. Its non-template UI code lives in `src/ui/*.cpp`. - Including `` alone peaks well under 1 GB in the front end, measured as above. - `test_lims_ignition_screen.cpp` peaks under 2 GB in a `clang-coverage` compile. -- Every CI leg passes on GitHub-hosted runners, gcc-release included. +- Every CI leg passes on GitHub-hosted runners, gcc-release included, with no cap on build parallelism beyond one + compile per CPU. Under `g++ -O3 -DNDEBUG` the UI test files peak at 4.7-5.7 GB each today + (`tests/test_ui_shell_parts.cpp` 5657 MB, `test_ui_workspace.cpp` 5598 MB, `test_ui_author.cpp` 5356 MB, + `test_ui_host.cpp` 5253 MB, `test_ui_interpreter_{commands,detail,control}.cpp` about 4675 MB). Four at once must fit + in 16 GB, so each must come down below about 3.5 GB. - `-DMORPH_BUILD_SHARED=ON` builds `morph` as a shared library that works on Linux and Windows (part B). - No behaviour changes. The public API, its headers and their include paths stay as they are. From 7ae22c30704a3b91294037c7f82c2965db72a636 Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sat, 14 Nov 2026 23:30:05 +0100 Subject: [PATCH 04/38] Move the interpreter's non-template code into src/ui/interpreter.cpp Every out-of-class `inline` member definition, every in-class member body of two or more lines, and the `detail` free functions move to the compiled library. Classes with a moved member, and the structs among them, carry MORPH_API. A free function that something outside the interpreter calls (tests, host.hpp, the inspector, the workspace) keeps its documented declaration in the header with MORPH_API. One nothing else calls moves into an unnamed namespace in the .cpp, together with the helper types and the named constants only moved bodies read. One-line accessors stay in the header so a hot reader keeps inlining. Templates and constexpr stay; kMaxInlineFileBytes is unchanged. tests/bench_interpreter.cpp (hidden, tag [.benchmark][interpreter]) mounts a ui/1 document with a 200-row table and times a state change; bench_mount never reaches the interpreter. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- CMakeLists.txt | 1 + include/morph/ui/interpreter.hpp | 8641 +----------------------------- src/ui/interpreter.cpp | 8539 +++++++++++++++++++++++++++++ tests/CMakeLists.txt | 1 + tests/bench_interpreter.cpp | 66 + 5 files changed, 8810 insertions(+), 8438 deletions(-) create mode 100644 src/ui/interpreter.cpp create mode 100644 tests/bench_interpreter.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 961adcc54..c5022c84e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -412,6 +412,7 @@ endif() # once, in src/ui. include(GenerateExportHeader) add_library(morph STATIC + src/ui/interpreter.cpp src/ui/library.cpp ) add_library(morph::morph ALIAS morph) diff --git a/include/morph/ui/interpreter.hpp b/include/morph/ui/interpreter.hpp index de309224b..86d5a010d 100644 --- a/include/morph/ui/interpreter.hpp +++ b/include/morph/ui/interpreter.hpp @@ -14,6 +14,7 @@ #include #include #include +#include #include #include #include @@ -136,7 +137,7 @@ using Evaluator = std::function(std::string const /// is ignored unless a `QueueingDispatcher` wraps it. A shared binding without a key is bound unattached, which the /// bridge refuses at the first call; the interpreter never binds one, since a `"shared"` alias is a stateless model's /// and binds privately. -class BridgeDispatcher final : public Dispatcher { +class MORPH_API BridgeDispatcher final : public Dispatcher { public: /// @brief Dispatches through @p bridge, and evaluates through @p evaluator. /// @param bridge The bridge. Borrowed: it must outlive every channel. @@ -152,9 +153,7 @@ class BridgeDispatcher final : public Dispatcher { /// @param instanceKey For a shared binding, the key to attach to; empty to stay unattached. /// @return The channel; destroying it deregisters the binding. [[nodiscard]] std::shared_ptr bind(std::string const& typeId, bridge::BindSharing sharing, - std::string const& instanceKey) override { - return std::make_shared(*_bridge, _cbExec, _evaluator, typeId, sharing, instanceKey); - } + std::string const& instanceKey) override; private: class Channel final : public ModelChannel { @@ -168,21 +167,9 @@ class BridgeDispatcher final : public Dispatcher { _handler{bridge, cbExec, typeId, sharing, instanceKey} {} [[nodiscard]] async::Completion execute(std::string const& actionId, std::string const& bodyJson, - CallOptions options) override { - if (options.evaluate) { - if (_evaluator) { - return _evaluator(_typeId, actionId, bodyJson); - } - auto [refused, promise] = async::Completion::makeSettleable(_cbExec); - promise.reject(std::make_exception_ptr(std::runtime_error{"evaluate needs the UI service"})); - return std::move(refused); - } - return _handler.execute(actionId, bodyJson); - } + CallOptions options) override; - [[nodiscard]] ChannelFacts facts() const override { - return ChannelFacts{.instanceId = _handler.instanceId(), .primary = _handler.primary()}; - } + [[nodiscard]] ChannelFacts facts() const override; private: exec::IExecutor* _cbExec; @@ -246,7 +233,7 @@ inline constexpr std::size_t kMaxInlineFileBytes = (wire::kMaxEnvelopeBytes - (s /// @brief What the application answers for the commands a document cannot carry out alone (spec 6). Every default /// answers "not supported", which the interpreter reports as a diagnostic. -class InterpreterHost { +class MORPH_API InterpreterHost { public: InterpreterHost() = default; InterpreterHost(InterpreterHost const&) = delete; @@ -264,32 +251,19 @@ class InterpreterHost { /// @param onCancel Called when such a screen closes without a value. /// @return Whether the host opened it. virtual bool navigate(NavigateRequest const& request, std::function onResult, - std::function onCancel) { - static_cast(request); - static_cast(onResult); - static_cast(onCancel); - return false; - } + std::function onCancel); /// @brief Ends the screen that ran `return` or `close: self`. /// @param screen The screen's id. /// @param result The value of `return`; `std::nullopt` for `close: self`. /// @return Whether the screen was opened as something that can end. - virtual bool closeSelf(std::string const& screen, std::optional result) { - static_cast(screen); - static_cast(result); - return false; - } + virtual bool closeSelf(std::string const& screen, std::optional result); /// @brief Runs a command the application registered (`host/1`). /// @param name The command. /// @param args Its arguments; `null` when none. /// @return Whether the command exists. - virtual bool hostCommand(std::string const& name, Value const& args) { - static_cast(name); - static_cast(args); - return false; - } + virtual bool hostCommand(std::string const& name, Value const& args); /// @brief Switches to a backend the application's source lists (`AppSource::switchBackend`, spec 6 §9). /// @@ -299,19 +273,12 @@ class InterpreterHost { /// @param done Called once with nothing when the switch committed, or with why it failed. Not called when the /// backend is not listed. /// @return Whether it is listed. - virtual bool switchBackend(std::string const& name, std::function)> done) { - static_cast(name); - static_cast(done); - return false; - } + virtual bool switchBackend(std::string const& name, std::function)> done); /// @brief The document reset a customization point, or all of them; the host forgets the stored choice. /// @param screen The screen's id. /// @param point The point, or `all`. - virtual void resetPrefs(std::string const& screen, std::string const& point) { - static_cast(screen); - static_cast(point); - } + virtual void resetPrefs(std::string const& screen, std::string const& point); /// @brief Stores the active locale as a preference. The interpreter has already re-resolved every `t`. /// @param locale The BCP 47 locale. @@ -321,19 +288,12 @@ class InterpreterHost { /// @param text The message. /// @param role `info`, `success`, `warning` or `error`; empty for the default. /// @return Whether it was shown. - virtual bool notify(std::string const& text, std::string const& role) { - static_cast(text); - static_cast(role); - return false; - } + virtual bool notify(std::string const& text, std::string const& role); /// @brief Installs the session the reply of a sign-in mutation carries, and reloads the catalog. /// @param reply The mutation's reply, secret fields included. /// @return Whether the host installed it. - virtual bool signIn(Value const& reply) { - static_cast(reply); - return false; - } + virtual bool signIn(Value const& reply); /// @brief Ends the session. The interpreter has already cleared the session's query cache. virtual void signOut() {} @@ -342,11 +302,7 @@ class InterpreterHost { /// @param name The app state's name. /// @param value The value. /// @return Whether the app document declares it. - virtual bool setAppValue(std::string const& name, Value const& value) { - static_cast(name); - static_cast(value); - return false; - } + virtual bool setAppValue(std::string const& name, Value const& value); /// @brief Sends a file through the server's file side channel (`files/1`). /// @param file What the user picked or dropped. @@ -354,12 +310,7 @@ class InterpreterHost { /// @param done Called once with the file's reference, or the failure's text. /// @return Whether the host can send files. virtual bool upload(Value const& file, std::function progress, - std::function)> done) { - static_cast(file); - static_cast(progress); - static_cast(done); - return false; - } + std::function)> done); /// @brief Sends a file through the server's file side channel, knowing the mutation that will reference it. The /// interpreter calls this one; the default calls `upload(file, …)`, so a host that overrides only that @@ -369,9 +320,7 @@ class InterpreterHost { /// @param done Called once with the file's reference, or the failure's text. /// @return Whether the host can send files. virtual bool uploadFor(UploadRequest const& request, std::function progress, - std::function)> done) { - return upload(request.file, std::move(progress), std::move(done)); - } + std::function)> done); /// @brief Fetches a file by reference to save it, or to a local temporary reference for a viewer. /// @param file The file's reference. @@ -380,13 +329,7 @@ class InterpreterHost { /// @param done Called once with the local reference (`preview`) or `null` (`dialog`), or the failure. /// @return Whether the host can fetch files. virtual bool download(Value const& file, std::string const& option, Value const& name, - std::function)> done) { - static_cast(file); - static_cast(option); - static_cast(name); - static_cast(done); - return false; - } + std::function)> done); /// @brief Reads a file's bytes for `upload` into bytes. A host reads the file's size first and refuses one over /// @p maxBytes without reading it; the interpreter refuses a reply over the cap as well. @@ -395,12 +338,7 @@ class InterpreterHost { /// @param done Called once with the file, or the failure's text. /// @return Whether the host can read files. virtual bool readFile(Value const& file, std::size_t maxBytes, - std::function)> done) { - static_cast(file); - static_cast(maxBytes); - static_cast(done); - return false; - } + std::function)> done); /// @brief Saves a file a document holds the bytes of, for `download` from bytes. /// @param file The file. @@ -408,22 +346,13 @@ class InterpreterHost { /// @param done Called once with the local reference (`preview`) or `null` (`dialog`), or the failure. /// @return Whether the host can save files. virtual bool saveFile(InlineFile const& file, std::string const& option, - std::function)> done) { - static_cast(file); - static_cast(option); - static_cast(done); - return false; - } + std::function)> done); /// @brief The user chose at a customization point through a `customize` editor; the host stores the choice. /// @param screen The screen's id. /// @param point The point. /// @param value The choice. - virtual void preferenceChanged(std::string const& screen, std::string const& point, Value const& value) { - static_cast(screen); - static_cast(point); - static_cast(value); - } + virtual void preferenceChanged(std::string const& screen, std::string const& point, Value const& value); /// @brief A call was refused with error kind `denied`: the permitted set is a snapshot, so the host asks the /// server again and calls `Session::setPermitted`. @@ -469,111 +398,23 @@ namespace detail { /// @brief The text of a failure. /// @param error The failure. /// @return `what()`, or `unknown error`. -[[nodiscard]] inline std::string failureText(std::exception_ptr const& error) { - try { - std::rethrow_exception(error); - } catch (std::exception const& failure) { - return failure.what(); - } catch (...) { - return "unknown error"; - } -} - -/// @brief A failure's action refusal, as a document reads it. -/// @param error The failure. -/// @return `{"code": c, "args": [{"name": n, "value": v}, ...]}` when it is an `ActionRefusal`, else `null`. -[[nodiscard]] inline Value refusalValue(std::exception_ptr const& error) { - try { - std::rethrow_exception(error); - } catch (model::ActionRefusal const& refusal) { - ValueList args; - for (model::RefusalArg const& arg : refusal.args()) { - args.emplace_back(ValueRecord{{"name", Value{arg.name}}, {"value", Value{arg.value}}}); - } - return Value{ValueRecord{{"code", Value{refusal.code()}}, {"args", Value{std::move(args)}}}}; - } catch (...) { - return Value{}; - } -} +[[nodiscard]] MORPH_API std::string failureText(std::exception_ptr const& error); /// @brief The default error kinds: the bridge's own failures, a server's refusal (`denied`), and `error` for the rest. /// @param error The failure. /// @return The kind. -[[nodiscard]] inline std::string defaultErrorKind(std::exception_ptr const& error) { - try { - std::rethrow_exception(error); - } catch (backend::DisconnectedError const&) { - return "offline"; - } catch (backend::TimeoutError const&) { - return "timeout"; - } catch (backend::ClientTimeoutError const&) { - return "timeout"; - } catch (backend::BackendChangedError const&) { - return "backendChanged"; - } catch (model::ActionRefusal const&) { - // An action's own refusal is an answer about its data, whatever its message says, never the authoriser's. - return "error"; - } catch (wire::UnauthorizedError const&) { - // A refused control request (register, attach): its text carries the request's name before the refusal. - return "denied"; - } catch (std::runtime_error const& refused) { - // The authoriser says no to an execute with this one text; no exception type tells it from another failure. - return std::string_view{refused.what()} == wire::kUnauthorizedMessage ? "denied" : "error"; - } catch (...) { - return "error"; - } -} +[[nodiscard]] MORPH_API std::string defaultErrorKind(std::exception_ptr const& error); /// @brief A value's JSON text, with record fields in name order: a cache key's canonical body. /// @param value The value. /// @return The text. -[[nodiscard]] inline std::string canonicalJson(Value const& value) { - return glz::write_json(valueToJson(value)).value_or(std::string{}); -} - -/// @brief A value with the field at @p path replaced, creating records along the way. -/// @param base The value written into. -/// @param path The field path. -/// @param value The new value at the path. -/// @return The new value. -// NOLINTNEXTLINE(misc-no-recursion): one level per path segment -[[nodiscard]] inline Value withPath(Value const& base, std::span path, Value value) { - if (path.empty()) { - return value; - } - ValueRecord fields; - if (ValueRecord const* const record = base.asRecord()) { - fields = *record; - } - Value const inner = base.field(path.front()) != nullptr ? *base.field(path.front()) : Value{}; - fields.insert_or_assign(path.front(), withPath(inner, path.subspan(1), std::move(value))); - return Value{std::move(fields)}; -} - -/// @brief A row's identity for `patch` and `optimistic`: its `id` field. -/// @param row The row. -/// @return The `id` field, or `null`. -[[nodiscard]] inline Value rowId(Value const& row) { - Value const* const found = row.field("id"); - return found == nullptr ? Value{} : *found; -} +[[nodiscard]] MORPH_API std::string canonicalJson(Value const& value); /// @brief Writes @p with over a row: the fields of a record over a record's, otherwise the whole row. /// @param row The row. /// @param with The new content. /// @return The new row. -[[nodiscard]] inline Value mergeRow(Value const& row, Value const& with) { - ValueRecord const* const fields = row.asRecord(); - ValueRecord const* const over = with.asRecord(); - if (fields == nullptr || over == nullptr) { - return with; - } - ValueRecord merged = *fields; - for (auto const& [name, field] : *over) { - merged.insert_or_assign(name, field); - } - return Value{std::move(merged)}; -} +[[nodiscard]] MORPH_API Value mergeRow(Value const& row, Value const& with); /// @brief Why a patch left a query's value as it was. enum class PatchMiss : std::uint8_t { @@ -588,189 +429,15 @@ enum class PatchMiss : std::uint8_t { /// @param with The new content, merged over the row. /// @return The new value, or why it is unchanged. // NOLINTBEGIN(bugprone-easily-swappable-parameters): a list, a key and a row are distinct roles of one type. -[[nodiscard]] inline std::expected patchRows(Value const& value, std::string_view listMember, - Value const& key, Value const& with) { - // NOLINTEND(bugprone-easily-swappable-parameters) - ValueRecord const* const record = listMember.empty() ? nullptr : value.asRecord(); - if (!listMember.empty() && (record == nullptr || !record->contains(listMember))) { - return std::unexpected(PatchMiss::NoList); - } - Value const* const rows = record == nullptr ? &value : &record->find(listMember)->second; - ValueList const* const items = rows->asList(); - if (items == nullptr) { - return std::unexpected(PatchMiss::NoList); - } - if (key.isNull()) { - return std::unexpected(PatchMiss::NoRow); - } - ValueList out = *items; - bool found = false; - for (Value& row : out) { - if (rowId(row) == key) { - row = mergeRow(row, with); - found = true; - } - } - if (!found) { - return std::unexpected(PatchMiss::NoRow); - } - if (record == nullptr) { - return Value{std::move(out)}; - } - ValueRecord patched = *record; - patched.insert_or_assign(std::string{listMember}, Value{std::move(out)}); - return Value{std::move(patched)}; -} - -/// @brief What a patch that found no list reports. -/// @param query The query it patches. -/// @param listMember The record member it names; empty when none. -/// @return The diagnostic's reason. -[[nodiscard]] inline std::string patchMissReason(std::string_view query, std::string_view listMember) { - if (listMember.empty()) { - return "the value of `" + std::string{query} + - "` is not a list, so the patch changes nothing; `at` names the record member that holds the list"; - } - return "the value of `" + std::string{query} + "` has no list at `" + std::string{listMember} + - "`, so the patch changes nothing"; -} +[[nodiscard]] MORPH_API std::expected patchRows(Value const& value, std::string_view listMember, + Value const& key, Value const& with); /// @brief Removes the named fields from a record, and from each record of a list. /// @param value The value. /// @param fields The field names. /// @return The value without them. // NOLINTNEXTLINE(misc-no-recursion): one level per nested list or record of the value. -[[nodiscard]] inline Value withoutFields(Value const& value, std::vector const& fields) { - if (fields.empty()) { - return value; - } - if (ValueRecord const* const record = value.asRecord()) { - ValueRecord kept = *record; - for (std::string const& field : fields) { - kept.erase(field); - } - return Value{std::move(kept)}; - } - if (ValueList const* const items = value.asList()) { - ValueList kept; - kept.reserve(items->size()); - for (Value const& item : *items) { - kept.push_back(withoutFields(item, fields)); - } - return Value{std::move(kept)}; - } - return value; -} - -/// @brief The members of a catalog record path: `"header.rows"` is `header`, then `rows`; `""` is none. -/// @param path The path. -/// @return Its members in order. -[[nodiscard]] inline std::vector pathMembers(std::string_view path) { - std::vector members; - for (auto const part : std::views::split(path, '.')) { - if (!part.empty()) { - members.emplace_back(part.begin(), part.end()); - } - } - return members; -} - -/// @brief The rows of a keyed record that a value holds at a path. -/// -/// A list on the way is looked through, as the result walker looks through a `std::vector`. At the path's end a -/// record with the key field is a row, and a record without it is a map whose values are the rows. -/// @param value The value. -/// @param path The members still to follow. -/// @param keyField The record's key field. -/// @param out Where the rows go. -// NOLINTNEXTLINE(misc-no-recursion): one level per path member or nested list. -inline void keyedRowsAt(Value const& value, std::span path, std::string_view keyField, - std::vector& out) { - if (ValueList const* const items = value.asList()) { - for (Value const& item : *items) { - keyedRowsAt(item, path, keyField, out); - } - return; - } - ValueRecord const* const record = value.asRecord(); - if (record == nullptr) { - return; - } - if (!path.empty()) { - if (auto const found = record->find(path.front()); found != record->end()) { - keyedRowsAt(found->second, path.subspan(1), keyField, out); - } - return; - } - if (record->contains(keyField)) { - out.push_back(&value); - return; - } - for (auto const& [name, item] : *record) { - static_cast(name); - if (ValueRecord const* const row = item.asRecord(); row != nullptr && row->contains(keyField)) { - out.push_back(&item); - } - } -} - -/// @brief New rows by the canonical text of their key. -using RowsByKey = std::map>; - -/// @brief Merges new rows over the rows with the same key that a value holds at a path. -/// @param value The value. -/// @param path The members still to follow. -/// @param keyField The record's key field. -/// @param rows The new rows. -/// @return The new value, or nothing when no row matched. -// NOLINTNEXTLINE(misc-no-recursion): one level per path member or nested list. -[[nodiscard]] inline std::optional patchKeyedRows(Value const& value, std::span path, - std::string_view keyField, RowsByKey const& rows) { - if (ValueList const* const items = value.asList()) { - ValueList out = *items; - bool changed = false; - for (Value& item : out) { - if (auto patched = patchKeyedRows(item, path, keyField, rows)) { - item = std::move(*patched); - changed = true; - } - } - return changed ? std::optional{Value{std::move(out)}} : std::nullopt; - } - ValueRecord const* const record = value.asRecord(); - if (record == nullptr) { - return std::nullopt; - } - if (!path.empty()) { - auto const found = record->find(path.front()); - if (found == record->end()) { - return std::nullopt; - } - auto patched = patchKeyedRows(found->second, path.subspan(1), keyField, rows); - if (!patched) { - return std::nullopt; - } - ValueRecord out = *record; - out.insert_or_assign(path.front(), std::move(*patched)); - return Value{std::move(out)}; - } - if (auto const key = record->find(keyField); key != record->end()) { - auto const row = rows.find(canonicalJson(key->second)); - return row == rows.end() ? std::nullopt : std::optional{mergeRow(value, *row->second)}; - } - ValueRecord out = *record; - bool changed = false; - for (auto& [name, item] : out) { - static_cast(name); - if (ValueRecord const* const row = item.asRecord(); row != nullptr && row->contains(keyField)) { - if (auto patched = patchKeyedRows(item, {}, keyField, rows)) { - item = std::move(*patched); - changed = true; - } - } - } - return changed ? std::optional{Value{std::move(out)}} : std::nullopt; -} +[[nodiscard]] MORPH_API Value withoutFields(Value const& value, std::vector const& fields); /// @brief One optimistic write still waiting for its reply. struct OptimisticLayer { @@ -785,7 +452,7 @@ struct OptimisticLayer { }; /// @brief One entry of the session's query cache (spec 5 §5): one request in flight, one value, one error. -struct CacheEntry { +struct MORPH_API CacheEntry { /// @brief An empty entry. /// @param runtime The runtime its signals belong to. explicit CacheEntry(reactive::Runtime& runtime) @@ -846,10 +513,7 @@ struct CacheEntry { /// @brief The catalog entry of a record the entry holds. /// @param record The record's wire name. /// @return It, or `nullptr` when the entry does not hold the record. - [[nodiscard]] ActionRecordInfo const* holding(std::string_view record) const { - auto const found = std::ranges::find(records, record, &ActionRecordInfo::record); - return found == records.end() ? nullptr : &*found; - } + [[nodiscard]] ActionRecordInfo const* holding(std::string_view record) const; }; /// @brief The rows of a keyed record a value holds, at each of the record's paths. @@ -857,15 +521,12 @@ struct CacheEntry { /// @param paths The record's paths. /// @param keyField The record's key field. /// @return The rows. -[[nodiscard]] inline std::vector keyedRowsOf(Value const& value, std::vector const& paths, - std::string_view keyField) { - std::vector rows; - for (std::string const& path : paths) { - std::vector const members = pathMembers(path); - keyedRowsAt(value, members, keyField, rows); - } - return rows; -} +[[nodiscard]] MORPH_API std::vector keyedRowsOf(Value const& value, + std::vector const& paths, + std::string_view keyField); + +/// @brief New rows by the canonical text of their key. +using RowsByKey = std::map>; /// @brief Merges new rows into a value at each of the record's paths. /// @param value The value. @@ -873,32 +534,17 @@ struct CacheEntry { /// @param keyField The record's key field. /// @param rows The new rows by key. /// @return The new value, or nothing when no row matched. -[[nodiscard]] inline std::optional patchHeldRows(Value const& value, std::vector const& paths, - std::string_view keyField, RowsByKey const& rows) { - std::optional patched; - for (std::string const& path : paths) { - std::vector const members = pathMembers(path); - auto next = patched ? patchKeyedRows(*patched, members, keyField, rows) - : patchKeyedRows(value, members, keyField, rows); - if (next) { - patched = std::move(next); - } - } - return patched; -} +[[nodiscard]] MORPH_API std::optional patchHeldRows(Value const& value, std::vector const& paths, + std::string_view keyField, RowsByKey const& rows); /// @brief The entries one change marks stale, each once, in the order they were found. -struct Marks { +struct MORPH_API Marks { /// @brief The entries. std::vector entries; /// @brief Adds an entry, unless it is already there. /// @param entry The entry. - void add(CacheEntry& entry) { - if (std::ranges::find(entries, &entry) == entries.end()) { - entries.push_back(&entry); - } - } + void add(CacheEntry& entry); }; class QueryRuntime; @@ -940,7 +586,7 @@ struct HostCommands { /// /// It belongs to the runtime's owner, outlives every screen mounted on it, and is cleared by `signOut` and on a /// principal change. -class Session { +class MORPH_API Session { public: /// @brief An empty session. /// @param runtime The runtime. Borrowed. @@ -981,16 +627,7 @@ class Session { /// permitted set: the two have different owners, and a catalog refresh must not drop the client's commands. /// @param action The action id, or `host:`. /// @return Whether it is permitted. - [[nodiscard]] bool can(std::string_view action) const { - static constexpr std::string_view kHostPrefix = "host:"; - if (action.starts_with(kHostPrefix)) { - return _hostCommandNames.get().contains(action.substr(kHostPrefix.size())); - } - if (action == "context") { - return _contextOffered.get(); - } - return _permitted.get().contains(action); - } + [[nodiscard]] bool can(std::string_view action) const; /// @brief Says whether a scope switcher with at least one option is installed, which is when `{"can": "context"}` /// holds and the `setContext` command can run. @@ -1014,26 +651,14 @@ class Session { /// @brief Chooses the number, money and date facts apart from the language. The choice stays through later /// `setLocale` calls, until an empty tag clears it. /// @param tag The BCP 47 tag whose facts apply; empty follows the language. - void setFormatLocale(std::string tag) { - _formatLocale = std::move(tag); - applyFacts(_format.peek()->locale); - } + void setFormatLocale(std::string tag); /// @brief The facts a locale scope writes in: the session's with @p tag's row of the locale table (separators, /// sign, currency placement) and the date patterns the application declared, else that row's. The facts /// come from the tag alone, whatever `setFormatLocale` chose. A tracked read of the session's facts. /// @param tag The scope's BCP 47 tag. /// @return The facts; `locale` is @p tag, and a tag the table does not list writes with `en`'s row. - [[nodiscard]] std::shared_ptr scopedFormatting(std::string_view tag) const { - FormatContext next = *_format.get(); - LocaleFacts const& facts = localeFacts(tag); - next.locale = std::string{tag}; - next.numeric = facts.numeric; - next.currency = facts.currency; - next.datePattern = _declaredDate.empty() ? std::string{facts.datePattern} : _declaredDate; - next.dateTimePattern = _declaredDateTime.empty() ? std::string{facts.dateTimePattern} : _declaredDateTime; - return std::make_shared(std::move(next)); - } + [[nodiscard]] std::shared_ptr scopedFormatting(std::string_view tag) const; /// @brief The session's own facts, shared. A tracked read. /// @return They. @@ -1043,9 +668,7 @@ class Session { /// reported it before. The answer is true once per tag for the session's lifetime. /// @param tag The tag. /// @return Whether to report it now. - [[nodiscard]] bool firstUnlistedLocale(std::string const& tag) { - return findLocaleFacts(tag) == nullptr && _unlistedLocales.insert(tag).second; - } + [[nodiscard]] bool firstUnlistedLocale(std::string const& tag); /// @brief The tag chosen with `setFormatLocale`. /// @return It; empty when the facts follow the language. @@ -1054,13 +677,7 @@ class Session { /// @brief Replaces the formatting facts; every `t` and display function re-evaluates. `{"env": "locale"}` follows /// the facts' locale. /// @param format The facts. - void setFormatting(FormatContext format) { - // One batch, so an effect never sees the new `env.locale` beside the old facts, and runs once. - _runtime->batch([this, &format] { - setEnvironmentValue("locale", Value{format.locale}); - _format.set(std::make_shared(std::move(format))); - }); - } + void setFormatting(FormatContext format); /// @brief The formatting facts. A tracked read. /// @return They. @@ -1075,14 +692,7 @@ class Session { /// one is not declared: the active locale's pattern applies, and ISO where the locale has none. /// @param date The date pattern, such as `dd-MMM-yyyy`. /// @param dateTime The date-and-time pattern, such as `dd-MMM-yyyy HH:mm`. - void setDatePatterns(std::string date, std::string dateTime) { - _declaredDate = std::move(date); - _declaredDateTime = std::move(dateTime); - FormatContext next = *_format.peek(); - next.datePattern = _declaredDate.empty() ? _localeDate : _declaredDate; - next.dateTimePattern = _declaredDateTime.empty() ? _localeDateTime : _declaredDateTime; - setFormatting(std::move(next)); - } + void setDatePatterns(std::string date, std::string dateTime); /// @brief Changes the active locale and installs its facts from the locale table (`localeFacts`): the separators /// and currency symbols, and the date patterns the application did not declare @@ -1092,29 +702,18 @@ class Session { /// @brief Replaces the message catalogue, keeping the other formatting facts; every `t` re-resolves. /// @param translations The provider, such as `MessageCatalogues::provider()`; empty shows every fallback. - void setTranslations(render::TranslationProvider translations) { - FormatContext next = *_format.peek(); - next.translations = std::move(translations); - setFormatting(std::move(next)); - } + void setTranslations(render::TranslationProvider translations); /// @brief Sets the `env` values (`widthClass`, `platform`, `online`, `backend`). `locale` is the formatting /// facts' locale and is always present: a `locale` in @p values is replaced by it. /// @param values The values. - void setEnvironment(ValueRecord values) { - values.insert_or_assign("locale", Value{_format.peek()->locale}); - _env.set(std::move(values)); - } + void setEnvironment(ValueRecord values); /// @brief Sets one `env` value and keeps the others, so a client that learns its width class does not drop the /// `backend` a switch set, nor a switch the width class. /// @param name The value's name, such as `widthClass`. /// @param value The value. - void setEnvironmentValue(std::string const& name, Value value) { - ValueRecord env = _env.peek(); - env.insert_or_assign(name, std::move(value)); - _env.set(std::move(env)); - } + void setEnvironmentValue(std::string const& name, Value value); /// @brief Sets the `session` values (`principal`, `userName`, …). /// @param values The values. @@ -1127,32 +726,18 @@ class Session { /// @brief Sets the client's host commands: the names `{"can": "host:name"}` answers for, and what runs them. A /// session without a runner asks `InterpreterHost::hostCommand`. /// @param commands The names and the runner. - void setHostCommands(HostCommands commands) { - _hostCommandRunner = std::move(commands.run); - _hostCommandNames.set(std::move(commands.available)); - } + void setHostCommands(HostCommands commands); /// @brief What runs host commands. /// @return It; empty when the application set none. [[nodiscard]] std::function const& hostCommandRunner() - const noexcept { - return _hostCommandRunner; - } + const noexcept; /// @brief Reads `env`, `session` or `host`. A tracked read. /// @param form `Env`, `Session` or `Host`. /// @param name The name. /// @return The value, or `null`. - [[nodiscard]] Value client(ExprKind form, std::string_view name) const { - ValueRecord const& values = [&]() -> ValueRecord const& { - if (form == ExprKind::Env) { - return _env.get(); - } - return form == ExprKind::Session ? _sessionValues.get() : _hostValues.get(); - }(); - auto const found = values.find(name); - return found == values.end() ? Value{} : found->second; - } + [[nodiscard]] Value client(ExprKind form, std::string_view name) const; /// @brief The app document's scope, which `{"ref": "app.name"}` reads and `{"set": "app.name"}` writes; set by /// `Interpreter::mountApp` for as long as the `AppRoot` lives. @@ -1164,20 +749,7 @@ class Session { void setAppScope(detail::RtScope const* scope) noexcept { _appScope = scope; } /// @brief Drops every cache entry: `signOut` and a principal change (spec 5 §5, "Isolation"). - void clear() { - _runtime->batch([this] { - for (auto const& [key, entry] : _entries) { - static_cast(key); - ++entry->generation; - entry->evict.cancel(); - countTopics(*entry, -1); - } - _entries.clear(); - for (detail::QueryRuntime* const query : _mounted) { - detachQuery(*query); - } - }); - } + void clear(); /// @brief Carries out a committed backend switch (spec 6 §9), in one batch: every mounted screen's /// `onBackendChange` runs first, then every entry is marked stale and the mounted queries refetch, and @@ -1201,13 +773,7 @@ class Session { /// @param action The action. /// @param body The body. void prefetch(std::shared_ptr const& channel, std::string const& token, std::string const& typeId, - std::string const& action, Value const& body) { - auto entry = acquire(token, typeId, action, false, body); - if (!entry->pending.peek() && (!entry->hasValue.peek() || entry->stale)) { - fetch(entry, channel); - } - release(entry); - } + std::string const& action, Value const& body); /// @brief The number of entries in the cache. /// @return It. @@ -1226,16 +792,7 @@ class Session { /// @brief Runs @p body as a user event: what it writes counts as the user's. /// @param body The body. - void asUser(std::function const& body) { - ++_userDepth; - try { - body(); - } catch (...) { - --_userDepth; - throw; - } - --_userDepth; - } + void asUser(std::function const& body); /// @brief The cache key of a query. /// @param token The alias's instance token. @@ -1245,9 +802,7 @@ class Session { /// @param body The canonical body. /// @return The key. [[nodiscard]] static std::string cacheKey(std::string const& token, std::string const& typeId, - std::string const& action, bool evaluate, std::string const& body) { - return typeId + '\x1f' + token + '\x1f' + (evaluate ? "evaluate:" : "") + action + '\x1f' + body; - } + std::string const& action, bool evaluate, std::string const& body); /// @brief Finds or makes an entry and counts one more user. /// @param token The alias's instance token. @@ -1257,123 +812,34 @@ class Session { /// @param body The body. /// @return The entry. std::shared_ptr acquire(std::string const& token, std::string const& typeId, - std::string const& action, bool evaluate, Value const& body) { - std::string const text = detail::canonicalJson(body); - std::string key = cacheKey(token, typeId, action, evaluate, text); - auto found = _entries.find(key); - if (found == _entries.end()) { - auto entry = std::make_shared(*_runtime); - entry->key = key; - entry->typeId = typeId; - entry->action = action; - entry->body = text; - entry->evaluate = evaluate; - entry->instanceToken = token; - if (_options.catalog.action) { - if (auto const info = _options.catalog.action(action)) { - entry->secretFields = info->secretFields; - if (!evaluate) { - entry->records = info->records; - } - } - } - countTopics(*entry, +1); - found = _entries.emplace(std::move(key), std::move(entry)).first; - } - ++found->second->users; - found->second->evict.cancel(); - return found->second; - } + std::string const& action, bool evaluate, Value const& body); /// @brief Counts one user less; an entry nobody uses is dropped after `keepUnused`. /// @param entry The entry. - void release(std::shared_ptr const& entry) { - if (--entry->users > 0 || _options.scheduler == nullptr) { - return; - } - std::weak_ptr const weak = entry; - entry->evict = _options.scheduler->after(_options.keepUnused, [this, weak] { - auto const held = weak.lock(); - if (held && held->users == 0) { - countTopics(*held, -1); - _entries.erase(held->key); - flushWatches(); - } - }); - } + void release(std::shared_ptr const& entry); /// @brief Sends an entry's request under a new generation; a reply of an older generation is dropped. /// @param entry The entry. /// @param channel The channel to send it through; `nullptr` fails the request at once. - void fetch(std::shared_ptr const& entry, std::shared_ptr const& channel) { - // The watch goes out before the read, on the same connection, so a change committed after the read is - // seen as an event. - flushWatches(); - std::uint64_t const generation = ++entry->generation; - if (channel == nullptr) { - settleFailure(*entry, "the model alias has no instance", "error"); - return; - } - entry->pending.set(true); - std::weak_ptr const weak = entry; - try { - auto completion = channel->execute(entry->action, entry->body, CallOptions{.evaluate = entry->evaluate}); - completion - .then([this, weak, generation](std::string const& reply) { - auto const held = weak.lock(); - if (held && held->generation == generation) { - settleReply(*held, reply); - } - }) - .onError([this, weak, generation](std::exception_ptr const& error) { - auto const held = weak.lock(); - if (held && held->generation == generation) { - settleFailure(*held, detail::failureText(error), classify(error), detail::refusalValue(error)); - } - }); - } catch (...) { - std::exception_ptr const error = std::current_exception(); - settleFailure(*entry, detail::failureText(error), classify(error), detail::refusalValue(error)); - } - } + void fetch(std::shared_ptr const& entry, std::shared_ptr const& channel); /// @brief Writes an entry's confirmed value and re-applies its optimistic layers over it. /// @param entry The entry. /// @param confirmed The confirmed value. - void confirm(detail::CacheEntry& entry, Value const& confirmed) { - entry.confirmed = detail::withoutFields(confirmed, entry.secretFields); - showLayers(entry); - } + void confirm(detail::CacheEntry& entry, Value const& confirmed); /// @brief Recomputes what an entry shows from its confirmed value and its layers. /// @param entry The entry. - void showLayers(detail::CacheEntry& entry) { - Value shown = entry.confirmed; - for (detail::OptimisticLayer const& layer : entry.layers) { - if (auto patched = detail::patchRows(shown, layer.at, layer.key, layer.with)) { - shown = std::move(*patched); - } - } - noteWrite(); - entry.value.set(std::move(shown)); - } + void showLayers(detail::CacheEntry& entry); /// @brief The error kind of a failure. /// @param error The failure. /// @return The kind. - [[nodiscard]] std::string classify(std::exception_ptr const& error) const { - return _options.classify ? _options.classify(error) : detail::defaultErrorKind(error); - } + [[nodiscard]] std::string classify(std::exception_ptr const& error) const; /// @brief The clock. /// @return Now. - [[nodiscard]] std::chrono::milliseconds now() const { - if (_options.clock) { - return _options.clock(); - } - return std::chrono::duration_cast( - std::chrono::steady_clock::now().time_since_epoch()); - } + [[nodiscard]] std::chrono::milliseconds now() const; /// @brief Registers a mounted query, which a reconnect and a backend switch refetch. /// @param query The query. @@ -1431,46 +897,13 @@ class Session { /// @brief Marks an entry stale. While its fetch is in flight, the entry also refetches once that fetch settles, /// because the fetch may have read before the change. /// @param entry The entry. - static void markStale(detail::CacheEntry& entry) { - entry.stale = true; - if (entry.pending.peek()) { - entry.refetchAfter = true; - } - } + static void markStale(detail::CacheEntry& entry); private: // A cap of 0 moves nothing inline, and one above the largest would not fit an envelope once encoded. - [[nodiscard]] static SessionOptions checkedOptions(SessionOptions options) { - if (options.maxInlineFileBytes == 0 || options.maxInlineFileBytes > kMaxInlineFileBytes) { - throw std::invalid_argument{"morph::ui::Session: maxInlineFileBytes is " + - std::to_string(options.maxInlineFileBytes) + "; it is 1 to " + - std::to_string(kMaxInlineFileBytes) + " (kMaxInlineFileBytes)"}; - } - return options; - } + [[nodiscard]] static SessionOptions checkedOptions(SessionOptions options); - void settleReply(detail::CacheEntry& entry, std::string const& reply) { - auto json = parseJson(reply); - auto value = json ? valueFromJson(*json) : std::unexpected(json.error()); - if (!value) { - settleFailure(entry, "the reply is not a document value: " + value.error(), "error"); - return; - } - _runtime->batch([&] { - confirm(entry, *value); - entry.hasValue.set(true); - entry.error.set({}); - entry.errorKind.set({}); - entry.refusal.set(Value{}); - entry.pending.set(false); - entry.fetchedAt = now(); - entry.stale = entry.refetchAfter; - if (entry.refetchAfter) { - entry.refetchAfter = false; - refetchMounted(entry); - } - }); - } + void settleReply(detail::CacheEntry& entry, std::string const& reply); /// @brief Refetches an entry through the mounted queries that use it; one fetch even when several do. /// @param entry The entry. @@ -1528,15 +961,7 @@ class Session { /// @param marks Where they go. void markInstanceChange(wire::InstanceTopic const& instance, detail::Marks& marks); - void settleFailure(detail::CacheEntry& entry, std::string text, std::string kind, Value refusal = Value{}) { - _runtime->batch([&] { - noteWrite(); - entry.error.set(std::move(text)); - entry.errorKind.set(std::move(kind)); - entry.refusal.set(std::move(refusal)); - entry.pending.set(false); - }); - } + void settleFailure(detail::CacheEntry& entry, std::string text, std::string kind, Value refusal = Value{}); static void detachQuery(detail::QueryRuntime& query); @@ -1550,18 +975,7 @@ class Session { std::set> _watchInstances; // Installs the facts of @p locale's row, or of the chosen format locale's row where one is chosen, and names // @p locale as the language. - void applyFacts(std::string locale) { - LocaleFacts const& facts = localeFacts(_formatLocale.empty() ? locale : _formatLocale); - _localeDate = std::string{facts.datePattern}; - _localeDateTime = std::string{facts.dateTimePattern}; - FormatContext next = *_format.peek(); - next.locale = std::move(locale); - next.numeric = facts.numeric; - next.currency = facts.currency; - next.datePattern = _declaredDate.empty() ? _localeDate : _declaredDate; - next.dateTimePattern = _declaredDateTime.empty() ? _localeDateTime : _declaredDateTime; - setFormatting(std::move(next)); - } + void applyFacts(std::string locale); std::set> _unwatchInstances; reactive::Signal> _format; @@ -1799,7 +1213,7 @@ struct ElementState { }; /// @brief One check at run time. -struct CheckRuntime { +struct MORPH_API CheckRuntime { /// @brief The declaration. CheckDecl const* decl = nullptr; /// @brief Whether `assert` is `false`. @@ -1816,12 +1230,7 @@ struct CheckRuntime { CheckRuntime& operator=(CheckRuntime&&) = delete; /// @brief Leaves its targets. - ~CheckRuntime() { - for (ElementState* const target : targets) { - std::erase(target->checks, this); - target->checksVersion.set(target->checksVersion.peek() + 1); - } - } + ~CheckRuntime(); }; /// @brief One declared name of a run-time scope. @@ -1858,7 +1267,7 @@ struct BoundaryRuntime { /// /// It lives while anything that reads it does: the view nodes lowered in it hold it by `shared_ptr`, a reply or /// a timer holds it weakly. It belongs to a `ScreenCore`, which outlives it. -class RtScope : public std::enable_shared_from_this { +class MORPH_API RtScope : public std::enable_shared_from_this { public: /// @brief An empty scope. /// @param screen The screen. @@ -1879,36 +1288,15 @@ class RtScope : public std::enable_shared_from_this { /// @brief Resolves a name, innermost scope first. /// @param name The name. /// @return The declaration, or `nullptr`. - [[nodiscard]] NameRef const* find(std::string_view name) const { - for (RtScope const* scope = this; scope != nullptr; scope = scope->parent.get()) { - auto const found = scope->names.find(name); - if (found != scope->names.end()) { - return &found->second; - } - } - return nullptr; - } + [[nodiscard]] NameRef const* find(std::string_view name) const; /// @brief The innermost row, from this scope outwards. /// @return The row signal, or `nullptr`. - [[nodiscard]] reactive::Signal const* innermostRow() const { - for (RtScope const* scope = this; scope != nullptr; scope = scope->parent.get()) { - if (scope->row != nullptr) { - return scope->row; - } - } - return nullptr; - } + [[nodiscard]] reactive::Signal const* innermostRow() const; /// @brief The innermost scope that decides when errors show and is submitted: a dialog's, or the screen's. /// @return The scope. - [[nodiscard]] RtScope const& policyScope() const { - RtScope const* scope = this; - while (scope->submitted == nullptr && scope->parent != nullptr) { - scope = scope->parent.get(); - } - return *scope; - } + [[nodiscard]] RtScope const& policyScope() const; /// @brief Whether every element of the scope is valid and no blocking check of it fails. A tracked read. /// @return It. @@ -1967,7 +1355,7 @@ class RtScope : public std::enable_shared_from_this { }; /// @brief The `Environment` the evaluator reads through: a scope chain and the names bound at one place. -class ScopeEnv final : public Environment { +class MORPH_API ScopeEnv final : public Environment { public: /// @brief Reads @p scope. /// @param scope The scope. @@ -1985,13 +1373,7 @@ class ScopeEnv final : public Environment { /// @brief Reads the innermost row. /// @param path The path. /// @return The value. - [[nodiscard]] Value row(std::span path) const override { - if (_row != nullptr) { - return walk(*_row, path); - } - reactive::Signal const* const current = _scope->innermostRow(); - return current == nullptr ? Value{} : walk(current->get(), path); - } + [[nodiscard]] Value row(std::span path) const override; /// @brief Reads a query or mutation form. /// @param form The form. @@ -2035,113 +1417,27 @@ class ScopeEnv final : public Environment { /// @param bindings The names bound here; may be `nullptr`. /// @param expr The expression; `nullptr` evaluates to `null`. /// @return The value. -[[nodiscard]] inline Value evalIn(RtScope const& scope, Bindings const* bindings, ExprPtr const& expr) { - if (!expr) { - return Value{}; - } - ScopeEnv const env{scope, bindings}; - return evaluate(*expr, env); -} +[[nodiscard]] MORPH_API Value evalIn(RtScope const& scope, Bindings const* bindings, ExprPtr const& expr); /// @brief Whether a value counts as given for `required`: not `null`, not an empty string or list. /// @param value The value. /// @return It. -[[nodiscard]] inline bool engaged(Value const& value) { - if (value.isNull()) { - return false; - } - if (std::string const* const text = value.asString()) { - return !text->empty(); - } - if (ValueList const* const items = value.asList()) { - return !items->empty(); - } - return true; -} +[[nodiscard]] MORPH_API bool engaged(Value const& value); /// @brief A value as text for a widget: a string as itself, a number in the locale, a timestamp in ISO 8601, /// `null` as nothing, anything else as JSON. /// @param value The value. /// @param format The formatting facts. /// @return The text. -[[nodiscard]] inline std::string textOf(Value const& value, FormatContext const& format) { - if (value.isNull()) { - return {}; - } - if (std::string const* const text = value.asString()) { - return *text; - } - if (bool const* const flag = value.asBool()) { - return *flag ? "true" : "false"; - } - // A number that cannot be rounded at its own places shows as its exact JSON rather than as a clamped value. - if (Quantity const* const quantity = value.asQuantity()) { - auto number = formatNumber(value, withoutGrouping(format.numeric)); - return number ? *number + " " + unitDisplay(quantity->unit, format.units) : canonicalJson(value); - } - if (auto number = formatNumber(value, withoutGrouping(format.numeric))) { - return *std::move(number); - } - if (time::DateTime const* const instant = value.asTimestamp()) { - return instant->toIso8601(); - } - return canonicalJson(value); -} - -/// @brief A value as a view key: an `int` or a string as itself, anything else as its JSON text. -/// @param value The value. -/// @return The key. -[[nodiscard]] inline Key keyOf(Value const& value) { - if (std::int64_t const* const number = value.asInt()) { - return Key{*number}; - } - if (std::string const* const text = value.asString()) { - return Key{*text}; - } - return Key{canonicalJson(value)}; -} +[[nodiscard]] MORPH_API std::string textOf(Value const& value, FormatContext const& format); /// @brief A view key as a value. /// @param key The key. /// @return An `int` or a string. -[[nodiscard]] inline Value valueOfKey(Key const& key) { - if (std::int64_t const* const number = std::get_if(&key)) { - return Value{*number}; - } - return Value{std::get(key)}; -} - -/// @brief A list of strings out of a value: a string, a list of strings, or nothing. -/// @param value The value. -/// @return The strings. -[[nodiscard]] inline std::vector stringsOf(Value const& value) { - std::vector out; - if (std::string const* const text = value.asString()) { - out.push_back(*text); - } else if (ValueList const* const items = value.asList()) { - for (Value const& item : *items) { - if (std::string const* const element = item.asString()) { - out.push_back(*element); - } - } - } - return out; -} - -/// @brief A list of strings as a value. -/// @param texts The strings. -/// @return The list. -[[nodiscard]] inline Value listOfStrings(std::vector const& texts) { - ValueList items; - items.reserve(texts.size()); - for (std::string const& text : texts) { - items.emplace_back(text); - } - return Value{std::move(items)}; -} +[[nodiscard]] MORPH_API Value valueOfKey(Key const& key); /// @brief A query at run time (spec 5 §5): a key over the scope, an entry of the session's cache, latest wins. -class QueryRuntime { +class MORPH_API QueryRuntime { public: /// @brief A query of @p scope, not yet started. /// @param decl The declaration. @@ -2195,19 +1491,10 @@ class QueryRuntime { void refetchCurrent(); /// @brief Marks its entry stale and refetches it. - void invalidate() { - if (auto const& current = _entry.peek()) { - current->stale = true; - } - refetch(); - } + void invalidate(); /// @brief Forgets its entry without releasing it: the session dropped the cache. - void detach() { - _entry.set(nullptr); - _carried.set(Value{}); - _target = {}; - } + void detach(); /// @brief The current entry. A tracked read. /// @return It, or `nullptr` while idle. @@ -2232,9 +1519,7 @@ class QueryRuntime { std::string token; Value body; std::string bodyText; - bool operator==(Target const& other) const { - return idle == other.idle && token == other.token && bodyText == other.bodyText; - } + bool operator==(Target const& other) const; }; void switchTo(Target const& target); @@ -2259,7 +1544,7 @@ class QueryRuntime { using RunDone = std::function; /// @brief A mutation at run time (spec 5 §5): concurrency, optimistic writes and the reply's effects. -class MutationRuntime { +class MORPH_API MutationRuntime { public: /// @brief A mutation of @p scope. /// @param decl The declaration. @@ -2373,16 +1658,6 @@ struct CommandCtx { std::shared_ptr boundary; }; -/// @brief A command context without its scope: what a callback the host keeps may hold, so that the host never -/// keeps a scope alive past its screen. The callback holds the scope weakly and puts it back. -/// @param ctx The context. -/// @return The context, its scope dropped. -[[nodiscard]] inline CommandCtx detached(CommandCtx const& ctx) { - CommandCtx kept = ctx; - kept.scope = nullptr; - return kept; -} - /// @brief Called once when a command finishes: whether it succeeded. using Done = std::function; @@ -2480,62 +1755,6 @@ struct HeadToolModel { std::function submit; }; -/// @brief Collects the `onClick` lists of menu entries, submenus included. -/// @param entries The entries. -/// @param lists Where they go, in document order. -// NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. -inline void menuCommandLists(std::span entries, std::vector& lists) { - for (DocNodePtr const& entry : entries) { - if (Commands const* const commands = entry->event("onClick")) { - lists.push_back(commands); - } - menuCommandLists(entry->partList("items"), lists); - } -} - -/// @brief Collects the command lists of a screen's head: its actions', its menu entries' and its tools'. -/// @param doc The screen's document. -/// @param lists Where they go, in document order. -inline void headCommandLists(Document const& doc, std::vector& lists) { - for (DocNodePtr const& action : doc.actions) { - if (Commands const* const commands = action->event("onClick")) { - lists.push_back(commands); - } - } - menuCommandLists(doc.menu, lists); - for (DocNodePtr const& tool : doc.tools) { - for (std::string_view const key : {"onChange", "onSubmit", "onChoose"}) { - if (Commands const* const commands = tool->event(key)) { - lists.push_back(commands); - } - } - } -} - -/// @brief A kind's key spec, from the kind table. -/// @param kind The kind spec. -/// @param key The key. -/// @return The spec, or `nullptr` when the kind has no such key of its own. -[[nodiscard]] inline KeySpec const* keySpec(KindSpec const& kind, std::string_view key) { - for (KeySpec const& spec : kind.keys) { - if (spec.key == key) { - return &spec; - } - } - return nullptr; -} - -/// @brief Whether a node kind keeps per-element state even without an id: the inputs, dialogs, tables and the forms -/// engine's screens. -/// @param kind The kind. -/// @return It. -[[nodiscard]] inline bool statefulKind(std::string_view kind) { - static constexpr std::array kStateful = { - "textInput", "checkbox", "select", "dateTimeInput", "slider", "filePicker", - "dialog", "drawer", "table", "form", "collection", "wizard"}; - return listed(kStateful, kind); -} - /// @brief How many command lists the inspector's log keeps. inline constexpr std::size_t kCommandLogSize = 256; @@ -2545,60 +1764,7 @@ inline constexpr std::size_t kPruneLoweredAt = 256; /// @brief The key a command is written with. /// @param kind The command's kind. /// @return Its key, such as `refetch`. -[[nodiscard]] inline std::string commandKey(CommandKind kind) { - switch (kind) { - case CommandKind::Set: - return "set"; - case CommandKind::Reset: - return "reset"; - case CommandKind::Run: - return "run"; - case CommandKind::Refetch: - return "refetch"; - case CommandKind::Open: - return "open"; - case CommandKind::Close: - return "close"; - case CommandKind::Navigate: - return "navigate"; - case CommandKind::Return: - return "return"; - case CommandKind::Focus: - return "focus"; - case CommandKind::Host: - return "host"; - case CommandKind::SwitchBackend: - return "switchBackend"; - case CommandKind::ResetPrefs: - return "resetPrefs"; - case CommandKind::SetLocale: - return "setLocale"; - case CommandKind::SetContext: - return "setContext"; - case CommandKind::Notify: - return "notify"; - case CommandKind::Seq: - return "seq"; - case CommandKind::All: - return "all"; - case CommandKind::If: - return "if"; - case CommandKind::CancelClose: - return "cancelClose"; - case CommandKind::Retry: - return "retry"; - case CommandKind::SignIn: - return "signIn"; - case CommandKind::SignOut: - return "signOut"; - case CommandKind::Upload: - return "upload"; - case CommandKind::Download: - return "download"; - default: - return "unknown"; - } -} +[[nodiscard]] MORPH_API std::string commandKey(CommandKind kind); /// @brief What the horizontal positions of a chart's points have been, across every series. struct ChartAxisKinds { @@ -2638,7 +1804,7 @@ struct ChartRawPoint { /// @brief One mounted screen's interpreter: its document, diagnostics, slots and preferences, and the code that /// declares scopes, lowers nodes and runs commands. -class ScreenCore { +class MORPH_API ScreenCore { public: /// @brief The core of a screen about to mount. /// @param doc The document. @@ -2647,26 +1813,7 @@ class ScreenCore { /// @param options The interpreter's options. /// @param mount The mount's options. ScreenCore(std::shared_ptr doc, Session& owner, Dispatcher& calls, - InterpreterOptions const& options, MountOptions const& mount) - : session{owner}, - dispatcher{calls}, - host{options.host}, - onDiagnostic{options.diagnostics}, - borrowed{mount.borrowed}, - depth{mount.depth}, - prefs{session.runtime()}, - submitted{session.runtime(), false}, - pendingWork{session.runtime(), 0}, - recording{owner.options().developmentTools == DevelopmentTools::On}, - _doc{std::move(doc)} { - ValueRecord defaults; - for (auto const& [name, point] : _doc->customize) { - defaults.insert_or_assign(name, point.defaultValue); - } - prefDefaults = defaults; - prefs.set(std::move(defaults)); - session.attachScreen(*this); - } + InterpreterOptions const& options, MountOptions const& mount); ScreenCore(ScreenCore const&) = delete; ScreenCore& operator=(ScreenCore const&) = delete; @@ -2677,18 +1824,7 @@ class ScreenCore { /// @brief Runs a lifecycle list in the document's own scope, as a screen's or app document's own command list. /// @param key The lifecycle key, such as `onBackendChange`. - void runLifecycleOf(std::string_view key) { - auto const found = _doc->lifecycle.find(key); - auto const scope = rootScope.lock(); - if (found == _doc->lifecycle.end() || !scope) { - return; - } - CommandCtx const ctx{.scope = scope, - .bindings = std::make_shared(), - .cancelClose = std::make_shared(false), - .boundary = nullptr}; - runList(found->second, ctx, {}); - } + void runLifecycleOf(std::string_view key); /// @brief The document. /// @return It. @@ -2701,20 +1837,7 @@ class ScreenCore { /// @brief Reports a diagnostic once per path. /// @param path Where. /// @param reason What. - void report(std::string_view path, std::string_view reason) { - if (inspecting) { - return; - } - std::string key = std::string{path} + '\x1f' + std::string{reason}; - if (!reported.insert(std::move(key)).second) { - return; - } - Refusal const refusal{.document = _doc->id, .path = std::string{path}, .reason = std::string{reason}}; - diagnostics.push_back(refusal); - if (onDiagnostic) { - onDiagnostic(refusal); - } - } + void report(std::string_view path, std::string_view reason); /// @brief The next slot id: the interpreter numbers every bound property of the document. /// @return It. @@ -2733,19 +1856,7 @@ class ScreenCore { /// @brief Makes a state's signal from its init, once. /// @param scope The scope that declares it. /// @param slot The state. - void initState(RtScope const& scope, StateSlot& slot) const { - if (slot.value || slot.initializing) { - return; - } - if (std::optional keptValue = keptState(scope, *slot.decl)) { - slot.value = std::make_unique>(runtime(), std::move(*keptValue)); - return; - } - slot.initializing = true; - Value init = runtime().untracked([&] { return evalIn(scope, nullptr, slot.decl->init); }); - slot.value = std::make_unique>(runtime(), std::move(init)); - slot.initializing = false; - } + void initState(RtScope const& scope, StateSlot& slot) const; /// @brief Reads an element value. A tracked read. /// @param element The element. @@ -2781,18 +1892,7 @@ class ScreenCore { /// @param commands The list; `nullptr` runs nothing. /// @param ctx Where it was lowered. /// @param event The event's payload. - void runEvent(Commands const* commands, LowerCtx const& ctx, Value event) { - if (commands == nullptr || commands->empty()) { - return; - } - auto bindings = std::make_shared(*ctx.bindings); - bindings->push_back(Binding{.name = "event", .read = [event = std::move(event)] { return event; }}); - CommandCtx const command{.scope = ctx.scope, - .bindings = std::move(bindings), - .cancelClose = std::make_shared(false), - .boundary = ctx.boundary}; - session.asUser([&] { runtime().batch([&] { runList(*commands, command, {}); }); }); - } + void runEvent(Commands const* commands, LowerCtx const& ctx, Value event); /// @brief Lowers a list of `actionButton` parts into reactive models: label, icon, enabled and visible bound in /// @p ctx's scope, and a run function that runs the part's `onClick` there as a user event. @@ -2940,17 +2040,7 @@ class ScreenCore { /// @param scope The scope that declares the state. /// @param decl The declaration. /// @return The value, or nothing for a state that starts from its init. - [[nodiscard]] std::optional keptState(RtScope const& scope, StateDecl const& decl) const { - if (keptStates.empty() || rootScope.lock().get() != &scope) { - return std::nullopt; - } - auto const found = keptStates.find(decl.name); - if (found == keptStates.end() || found->second.type != decl.type.name() || - !decl.type.admits(found->second.value)) { - return std::nullopt; - } - return found->second.value; - } + [[nodiscard]] std::optional keptState(RtScope const& scope, StateDecl const& decl) const; private: void wireElement(ElementState& element); @@ -3095,10 +2185,7 @@ class ScreenCore { std::optional inlineDownload(Command const& command, CommandCtx const& ctx, Value const& file, Value const& name); void runUpload(Command const& command, CommandCtx const& ctx, Value const& file, Done done); - bool unsupported(Command const& command, std::string_view what) { - report(command.path, std::string{what} + " is not supported by the host"); - return false; - } + bool unsupported(Command const& command, std::string_view what); /// @brief A bound property: a constant for a literal, a numbered slot otherwise. template @@ -3134,24 +2221,10 @@ class ScreenCore { } /// @brief Evaluates an expression once, untracked: a property the view tree sets once. - [[nodiscard]] Value once(LowerCtx const& ctx, ExprPtr const& expr) const { - return runtime().untracked([&] { return evalIn(*ctx.scope, ctx.bindings.get(), expr); }); - } + [[nodiscard]] Value once(LowerCtx const& ctx, ExprPtr const& expr) const; /// @brief Keeps a command list in the inspector's log. - void logList(Commands const& commands) { - CommandLogEntry entry{.event = {}, .commands = {}, .batch = runtime().core()->currentBatch()}; - std::string_view const first = commands.front().path; - entry.event = std::string{first.substr(0, first.rfind('/') == std::string_view::npos ? 0 : first.rfind('/'))}; - for (Command const& command : commands) { - entry.commands.push_back( - LoggedCommand{.kind = commandKey(command.kind), .target = command.target, .path = command.path}); - } - if (commandLog.size() == kCommandLogSize) { - commandLog.pop_front(); - } - commandLog.push_back(std::move(entry)); - } + void logList(Commands const& commands); std::shared_ptr _doc; SlotId _slots = 1; @@ -3285,7 +2358,7 @@ struct HeadTool { /// /// Neither copyable nor movable. It belongs to the runtime's owner; the runtime, the session, the dispatcher and /// the backend outlive it. Destroying it runs `onUnmount`, unmounts the view and releases every scope. -class Screen { +class MORPH_API Screen { public: Screen(Screen const&) = delete; Screen& operator=(Screen const&) = delete; @@ -3293,30 +2366,11 @@ class Screen { Screen& operator=(Screen&&) = delete; /// @brief Runs `onUnmount`, then unmounts. - ~Screen() { - try { - if (Commands const* const commands = lifecycleList("onUnmount")) { - runCommands(*commands); - } - } catch (...) { // NOLINT(bugprone-empty-catch): a destructor has no one to report to. - } - _core->focusElement = {}; - _mounted.reset(); - _headActions.clear(); - _headStatus.clear(); - _headMenu.clear(); - _headTools.clear(); - _scope.reset(); - } + ~Screen(); /// @brief The root widget. /// @return It, valid as long as the screen. - [[nodiscard]] Widget& root() const { - if (!_mounted) { - throw std::logic_error{"the screen is not mounted"}; - } - return _mounted->root(); - } + [[nodiscard]] Widget& root() const; /// @brief The document's id. /// @return It. @@ -3326,13 +2380,7 @@ class Screen { /// test inspects. /// @param expression The expression's JSON. /// @return The value; `null` for an expression that does not parse. - [[nodiscard]] Value read(Json const& expression) const { - auto parsed = parseExpression(expression); - if (!parsed) { - return Value{}; - } - return detail::evalIn(*_scope, nullptr, *parsed); - } + [[nodiscard]] Value read(Json const& expression) const; /// @brief Evaluates the document's `title`. /// @return It, or `null`. @@ -3353,19 +2401,7 @@ class Screen { /// @brief The aliases of the screen's own scope that hold an instance now. One still binding is left out, and so /// is one of a nested scope, which is mounted per row or per opening and so names no one instance. /// @return Them, in declaration order. - [[nodiscard]] std::vector boundAliases() const { - std::vector bound; - for (auto const& alias : _scope->models) { - if (alias->channel == nullptr) { - continue; - } - ChannelFacts facts = alias->channel->facts(); - if (facts.instanceId != 0) { - bound.push_back(BoundAlias{.decl = alias->decl, .facts = std::move(facts)}); - } - } - return bound; - } + [[nodiscard]] std::vector boundAliases() const; /// @brief Whether the screen's shown root lays itself at the page's edges (`pageEdge`). A tracked read: it starts /// at the view's root, and while the node is a `switch` it moves to the case shown now (the default when @@ -3421,55 +2457,17 @@ class Screen { /// @brief The head's status badges that are visible now, in order. A tracked read. /// @return They. - [[nodiscard]] std::vector status() const { - std::vector shown; - for (detail::BadgeModel const& badge : _headStatus) { - if (badge.visible.evaluate()) { - shown.push_back(HeadBadge{ - .text = badge.text.evaluate(), .tone = badge.tone.evaluate(), .icon = badge.icon.evaluate()}); - } - } - return shown; - } + [[nodiscard]] std::vector status() const; /// @brief The head's actions that are visible now, in order, each with whether it is enabled. A tracked read. /// @return They. - [[nodiscard]] std::vector actions() const { - std::vector shown; - for (detail::ActionModel const& action : _headActions) { - if (action.visible.evaluate()) { - shown.push_back(HeadAction{.id = action.id, - .label = action.label.evaluate(), - .icon = action.icon.evaluate(), - .iconOnly = action.iconOnly.evaluate(), - .emphasis = action.emphasis, - .enabled = action.enabled.evaluate()}); - } - } - return shown; - } + [[nodiscard]] std::vector actions() const; /// @brief Runs a head action's `onClick` as a user event in the screen scope, in one batch. /// @param actionId The action's id. /// @return Whether it ran: `false`, with a diagnostic, for an id the head does not hold, or holds hidden or /// disabled. - bool runAction(std::string_view actionId) { - auto const found = std::ranges::find(_headActions, actionId, &detail::ActionModel::id); - if (found == _headActions.end()) { - _core->report("/actions", "head action " + std::string{actionId} + " is unknown"); - return false; - } - auto const [visible, enabled] = - runtime().untracked([&] { return std::pair{found->visible.evaluate(), found->enabled.evaluate()}; }); - if (!visible || !enabled) { - _core->report(found->path, "head action " + found->id + (visible ? " is disabled" : " is hidden")); - return false; - } - if (found->run) { - found->run(); - } - return true; - } + bool runAction(std::string_view actionId); /// @brief The head menu's visible entries, in order, each with whether it is enabled. A separator that hidden /// entries leave first, last or next to another is left out, as a menu's mount leaves it out. A tracked @@ -3479,56 +2477,18 @@ class Screen { /// @brief Evaluates the document's `menuLabel`, the accessible name of the head menu's trigger. /// @return It, or "More actions" when the document declares none. - [[nodiscard]] std::string menuLabel() const { - if (!_core->doc().menuLabel) { - return "More actions"; - } - return detail::textOf(detail::evalIn(*_scope, nullptr, _core->doc().menuLabel), _scope->formatting()); - } + [[nodiscard]] std::string menuLabel() const; /// @brief Runs a head menu entry's `onClick` as a user event in the screen scope, in one batch. /// @param entryId The entry's id. /// @return Whether it ran: `false`, with a diagnostic, for an id the menu does not hold, or holds hidden or /// disabled (the entry itself or a submenu it is in). - bool chooseMenuEntry(std::string_view entryId) { - FoundEntry const found = runtime().untracked([&] { return findHeadEntry(_headMenu, entryId, FoundEntry{}); }); - if (found.model == nullptr) { - _core->report("/menu", "head menu entry " + std::string{entryId} + " is unknown"); - return false; - } - if (!found.visible || !found.enabled) { - _core->report(found.model->path, - "head menu entry " + found.model->id + (found.visible ? " is disabled" : " is hidden")); - return false; - } - if (found.model->item.onSelect) { - found.model->item.onSelect(); - } - return true; - } + bool chooseMenuEntry(std::string_view entryId); /// @brief The head's tools that are visible now, in order, each with its value and whether it is enabled. A /// tracked read. /// @return They; empty when the document declares no `tools`. - [[nodiscard]] std::vector tools() const { - std::vector shown; - for (detail::HeadToolModel const& tool : _headTools) { - if (!tool.visible.evaluate()) { - continue; - } - bool const search = tool.kind == HeadToolKind::Search; - shown.push_back(HeadTool{.id = tool.id, - .kind = tool.kind, - .label = tool.label.evaluate(), - .value = search ? tool.value.evaluate() : std::string{}, - .placeholder = search ? tool.placeholder.evaluate() : std::string{}, - .options = search ? std::vector{} : tool.options.evaluate(), - .selected = search ? std::nullopt : tool.selected.evaluate(), - .width = tool.width, - .enabled = tool.enabled.evaluate()}); - } - return shown; - } + [[nodiscard]] std::vector tools() const; /// @brief Reports a user's edit of a head tool: runs a search's `onChange` with `event` the text, or a select's /// `onChoose` with `event` the chosen key, as a user event in the screen scope, in one batch. @@ -3536,44 +2496,18 @@ class Screen { /// @param value A search's text, or a select's key. /// @return Whether it ran: `false`, with a diagnostic, for an id the head does not hold, or holds hidden or /// disabled, and for a search given anything but a string. - bool editTool(std::string_view toolId, Value const& value) { - detail::HeadToolModel const* const tool = usableTool(toolId); - if (tool == nullptr) { - return false; - } - if (tool->kind == HeadToolKind::Search && value.asString() == nullptr) { - _core->report(tool->path, "head tool " + tool->id + " is a search, edited with text"); - return false; - } - tool->edit(value); - return true; - } + bool editTool(std::string_view toolId, Value const& value); /// @brief Reports a user's submit of a head search: runs its `onSubmit` with `event` its text, as a user event in /// the screen scope, in one batch. /// @param toolId The tool's id. /// @return Whether it ran: `false`, with a diagnostic, for an id the head does not hold, or holds hidden or /// disabled, and for a select. - bool submitTool(std::string_view toolId) { - detail::HeadToolModel const* const tool = usableTool(toolId); - if (tool == nullptr) { - return false; - } - if (tool->kind != HeadToolKind::Search) { - _core->report(tool->path, "head tool " + tool->id + " is a select, which is not submitted"); - return false; - } - tool->submit(Value{runtime().untracked([&] { return tool->value.evaluate(); })}); - return true; - } + bool submitTool(std::string_view toolId); /// @brief Evaluates the document's `dirty`. /// @return Whether it is `true`. - [[nodiscard]] bool dirty() const { - Value const value = detail::evalIn(*_scope, nullptr, _core->doc().dirty); - bool const* const flag = value.asBool(); - return flag != nullptr && *flag; - } + [[nodiscard]] bool dirty() const; /// @brief Whether the screen has work a close waits for: an open dialog or drawer, a mutation run, or an upload or /// download in flight, in any of its scopes (spec 6 §3). A tracked read, so an Effect that reads it runs @@ -3587,23 +2521,14 @@ class Screen { /// @brief Runs `onClose`, as the host does before it closes the screen. /// @return False when `onClose` ran `cancelClose`: the screen stays open. - bool requestClose() { - std::shared_ptr const cancelled = beginClose(); - return cancelled == nullptr || !*cancelled; - } + bool requestClose(); /// @brief Runs `onClose`, and hands back the flag its `cancelClose` sets. /// /// The flag is shared with every command list `onClose` starts, such as the `onResult` of a confirm dialog it /// opens, so it can still be set after this returns; a host reads it once the screen is no longer `pending()`. /// @return The flag, or `nullptr` when the document declares no `onClose`. - [[nodiscard]] std::shared_ptr beginClose() { - Commands const* const commands = lifecycleList("onClose"); - if (commands == nullptr) { - return nullptr; - } - return runCommandsFlag(*commands); - } + [[nodiscard]] std::shared_ptr beginClose(); /// @brief Whether the document declares a lifecycle command list. /// @param key The key: `onClose`, `onSave`, … @@ -3612,11 +2537,7 @@ class Screen { /// @brief Runs a lifecycle command list: `onSave`, `onBackendChange`, or any other the document declares. /// @param key The key. - void runLifecycle(std::string_view key) { - if (Commands const* const commands = lifecycleList(key)) { - runCommands(*commands); - } - } + void runLifecycle(std::string_view key); /// @brief The diagnostics reported so far, each path and reason once. /// @return They. @@ -3627,16 +2548,7 @@ class Screen { /// @param point The point. /// @param value The choice. /// @return Whether it fits and was taken. - bool setPreference(std::string const& point, Value value) { - auto const found = _core->doc().customize.find(point); - if (found == _core->doc().customize.end() || !fits(found->second, value)) { - return false; - } - ValueRecord prefs = _core->prefs.peek(); - prefs.insert_or_assign(point, std::move(value)); - _core->prefs.set(std::move(prefs)); - return true; - } + bool setPreference(std::string const& point, Value value); /// @brief The screen's document, whose `customize` block names the points a preferences store loads. /// @return It. @@ -3662,66 +2574,22 @@ class Screen { [[nodiscard]] DocNode const* shownRoot() const; /// The states of the screen's own scope that have a value, by name: what a screen that replaces it keeps. - [[nodiscard]] std::map> ownState() const { - std::map> states; - for (auto const& slot : _scope->states) { - if (slot->value) { - states.insert_or_assign( - slot->decl->name, - detail::ScreenCore::KeptState{.type = slot->decl->type.name(), .value = slot->value->peek()}); - } - } - return states; - } + [[nodiscard]] std::map> ownState() const; - [[nodiscard]] Commands const* lifecycleList(std::string_view key) const { - auto const found = _core->doc().lifecycle.find(key); - return found == _core->doc().lifecycle.end() ? nullptr : &found->second; - } + [[nodiscard]] Commands const* lifecycleList(std::string_view key) const; /// Runs a command list as the screen's own (not a user's); returns whether it ran `cancelClose`. bool runCommands(Commands const& commands) { return *runCommandsFlag(commands); } /// Runs a command list as the screen's own; returns the `cancelClose` flag it and what it starts share. - std::shared_ptr runCommandsFlag(Commands const& commands) { - detail::CommandCtx const ctx{.scope = _scope, - .bindings = std::make_shared(), - .cancelClose = std::make_shared(false), - .boundary = nullptr}; - _core->runtime().batch([&] { _core->runList(commands, ctx, {}); }); - return ctx.cancelClose; - } + std::shared_ptr runCommandsFlag(Commands const& commands); - [[nodiscard]] static bool fits(CustomizePoint const& point, Value const& value) { - if (point.kind == "choice") { - std::string const* const text = value.asString(); - return text != nullptr && listed(std::span{point.options}, *text); - } - if (point.kind == "value") { - return point.type.admits(value); - } - return true; - } + [[nodiscard]] static bool fits(CustomizePoint const& point, Value const& value); - [[nodiscard]] static bool listed(std::span options, std::string const& text) { - return std::ranges::find(options, text) != options.end(); - } + [[nodiscard]] static bool listed(std::span options, std::string const& text); // A head tool by id that is visible and enabled; null, with a diagnostic, for any other. - [[nodiscard]] detail::HeadToolModel const* usableTool(std::string_view toolId) const { - auto const found = std::ranges::find(_headTools, toolId, &detail::HeadToolModel::id); - if (found == _headTools.end()) { - _core->report("/tools", "head tool " + std::string{toolId} + " is unknown"); - return nullptr; - } - auto const [visible, enabled] = - runtime().untracked([&] { return std::pair{found->visible.evaluate(), found->enabled.evaluate()}; }); - if (!visible || !enabled) { - _core->report(found->path, "head tool " + found->id + (visible ? " is disabled" : " is hidden")); - return nullptr; - } - return &*found; - } + [[nodiscard]] detail::HeadToolModel const* usableTool(std::string_view toolId) const; // A head menu entry by id, with whether it and every submenu it is in are visible and enabled. struct FoundEntry { @@ -3732,52 +2600,12 @@ class Screen { // NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. [[nodiscard]] static FoundEntry findHeadEntry(std::vector const& level, - std::string_view entryId, FoundEntry const& outer) { - for (detail::HeadMenuModel const& model : level) { - FoundEntry const here{.model = &model, - .visible = outer.visible && model.item.visible.evaluate(), - .enabled = outer.enabled && model.item.enabled.evaluate()}; - if (!model.id.empty() && model.id == entryId) { - return here; - } - if (FoundEntry const inner = findHeadEntry(model.items, entryId, here); inner.model != nullptr) { - return inner; - } - } - return FoundEntry{}; - } + std::string_view entryId, FoundEntry const& outer); // One level of the head menu as it shows now: hidden entries left out, and a separator they leave first, last or // next to another with them. // NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. - [[nodiscard]] static std::vector shownHeadMenu(std::vector const& level) { - std::vector shown; - for (detail::HeadMenuModel const& model : level) { - MenuItem const& item = model.item; - if (item.separator) { - if (!shown.empty() && !shown.back().separator) { - shown.push_back(HeadMenuEntry{.separator = true}); - } - continue; - } - if (!item.visible.evaluate()) { - continue; - } - shown.push_back(HeadMenuEntry{.id = model.id, - .label = item.label.evaluate(), - .icon = item.icon, - .keys = item.keys, - .checked = item.checked.evaluate(), - .enabled = item.enabled.evaluate(), - .items = shownHeadMenu(model.items), - .separator = false, - .description = item.description.evaluate()}); - } - if (!shown.empty() && shown.back().separator) { - shown.pop_back(); - } - return shown; - } + [[nodiscard]] static std::vector shownHeadMenu(std::vector const& level); std::unique_ptr _core; std::shared_ptr _scope; @@ -3803,43 +2631,21 @@ class AppRoot { AppRoot& operator=(AppRoot&&) = delete; /// @brief Runs `onUnmount`, takes the scope off the session, and releases everything. - ~AppRoot() { - try { - if (auto const found = _core->doc().lifecycle.find("onUnmount"); found != _core->doc().lifecycle.end()) { - runCommands(found->second); - } - } catch (...) { // NOLINT(bugprone-empty-catch): a destructor has no one to report to. - } - // The counts read the scope, so they go before it. - _navigationBadges.reset(); - _navigation.clear(); - _core->session.setAppScope(nullptr); - _scope.reset(); - } + ~AppRoot(); /// @brief The app document's `navigation` badges that are visible now, in order, each with the screen whose /// navigator entry it goes on, and following the app state they read. /// @return They, valid as long as the root; empty when the document declares no `navigation`. - [[nodiscard]] reactive::Computed> const& navigationBadges() const { - return *_navigationBadges; - } + [[nodiscard]] reactive::Computed> const& navigationBadges() const; /// @brief Where a shell shows who is signed in: the document's `principalPlacement`. /// @return The place; `Sidebar` when the document declares none. - [[nodiscard]] PrincipalPlacement principalPlacement() const noexcept { - return _core->doc().principalPlacement == "head" ? PrincipalPlacement::Head : PrincipalPlacement::Sidebar; - } + [[nodiscard]] PrincipalPlacement principalPlacement() const noexcept; /// @brief Evaluates an expression in the app document's scope. /// @param expression The expression's JSON. /// @return Its value; `null` for an expression that does not parse. - [[nodiscard]] Value read(Json const& expression) const { - auto parsed = parseExpression(expression); - if (!parsed) { - return Value{}; - } - return detail::evalIn(*_scope, nullptr, *parsed); - } + [[nodiscard]] Value read(Json const& expression) const; /// @brief What a query of the app document holds now. struct QueryRead { @@ -3858,59 +2664,20 @@ class AppRoot { /// @brief Reads a query of the app document. A tracked read: an effect that calls it follows the query. /// @param name The query. /// @return Its state; `declared` is false for a name the document does not declare as a query. - [[nodiscard]] QueryRead query(std::string_view name) const { - detail::NameRef const* const found = _scope->find(name); - if (found == nullptr || found->category != detail::NameCategory::Query) { - return QueryRead{}; - } - detail::QueryRuntime const& runtime = *found->query; - Value const error = runtime.error(); - Value const kind = runtime.errorKind(); - std::string const* const kindText = kind.asString(); - return QueryRead{.value = runtime.value(), - .pending = runtime.pending(), - .failed = !error.isNull(), - .declared = true, - .denied = kindText != nullptr && *kindText == "denied"}; - } + [[nodiscard]] QueryRead query(std::string_view name) const; /// @brief Writes a state of the app document, as a `set` of `app.name` does. /// @param name The state. /// @param value The value. /// @return Whether the document declares the state. - bool setState(std::string_view name, Value value) { - detail::NameRef const* const found = _scope->find(name); - if (found == nullptr || found->category != detail::NameCategory::State) { - return false; - } - detail::StateSlot& slot = *found->state; - slot.scope->core.initState(*slot.scope, slot); - _core->session.noteWrite(); - slot.value->set(std::move(value)); - return true; - } + bool setState(std::string_view name, Value value); /// @brief Runs a mutation of the app document, as a `run` command does. /// @param name The mutation. /// @param body The body it is run with. /// @param done Called once the run settles, with whether it succeeded; empty for none. /// @return Whether the document declares the mutation. - bool runMutation(std::string_view name, Value body, std::function done = {}) { - detail::NameRef const* const found = _scope->find(name); - if (found == nullptr || found->category != detail::NameCategory::Mutation) { - return false; - } - detail::MutationRuntime& mutation = *found->mutation; - _core->runtime().batch([&] { - mutation.run(std::move(body), std::make_shared(), - [done = std::move(done)](bool succeeded, Value const& /*reply*/) { - if (done) { - done(succeeded); - } - }); - }); - return true; - } + bool runMutation(std::string_view name, Value body, std::function done = {}); /// @brief The diagnostics reported so far. /// @return They. @@ -3921,13 +2688,7 @@ class AppRoot { AppRoot() = default; - void runCommands(Commands const& commands) { - detail::CommandCtx const ctx{.scope = _scope, - .bindings = std::make_shared(), - .cancelClose = std::make_shared(false), - .boundary = nullptr}; - _core->runtime().batch([&] { _core->runList(commands, ctx, {}); }); - } + void runCommands(Commands const& commands); // A navigation badge, lowered in the app scope, with the screen of its entry. struct PlacedBadge { @@ -3942,7 +2703,7 @@ class AppRoot { }; /// @brief Mounts UI documents (spec 5): one per client process or window, over a session and a dispatcher. -class Interpreter { +class MORPH_API Interpreter { public: /// @brief An interpreter. /// @param session The session the screens share. Borrowed. @@ -3980,7098 +2741,102 @@ class Interpreter { InterpreterOptions _options; }; -// --------------------------------------------------------------------------------------------------------------- -// Implementation -// --------------------------------------------------------------------------------------------------------------- - -inline void Session::backendChanged(std::string const& backend) { - _runtime->batch([this, &backend] { - std::vector const screens = _screens; - for (detail::ScreenCore* const screen : screens) { - if (std::ranges::find(_screens, screen) != _screens.end()) { - screen->runLifecycleOf("onBackendChange"); - } - } - ValueRecord env = _env.peek(); - env.insert_or_assign("backend", Value{backend}); - _env.set(std::move(env)); - for (auto const& [key, entry] : _entries) { - static_cast(key); - markStale(*entry); - } - std::vector const mounted = _mounted; - for (detail::QueryRuntime* const query : mounted) { - query->refetchCurrent(); - } - }); -} - -inline void Session::refetchMounted(detail::CacheEntry const& entry) { - std::vector const mounted = _mounted; - for (detail::QueryRuntime* const query : mounted) { - if (_runtime->untracked([query] { return query->entry(); }).get() == &entry) { - query->refetchCurrent(); - } - } -} - -// NOLINTNEXTLINE(bugprone-easily-swappable-parameters): a model type and an action id, as every caller names them. -inline void Session::applyReplyEffects(std::string const& typeId, std::string const& actionId, Value const& reply, - ReplyUse use, std::string const& instanceToken) { - if (!_options.catalog.action) { - return; - } - std::optional const info = _options.catalog.action(actionId); - if (!info || !info->effects) { - return; - } - detail::Marks marks; - for (ActionEffect const& effect : *info->effects) { - if (effect.kind == "changesInstance") { - for (auto const& [key, entry] : _entries) { - static_cast(key); - if (!entry->evaluate && entry->typeId == typeId && entry->instanceToken == instanceToken) { - marks.add(*entry); - } - } - } else if (effect.record && (effect.kind == "updates" || effect.kind == "changes")) { - applyRecordEffect(effect, *effect.record, *info, reply, use, marks); - } - } - markAndRefetch(marks); -} - -inline void Session::applyRecordEffect(ActionEffect const& effect, std::string const& record, ActionInfo const& info, - Value const& reply, ReplyUse use, detail::Marks& marks) { - // The reply's rows of the record, by key; none when the reply does not hold it keyed, or must only mark. - auto const own = std::ranges::find(info.records, record, &ActionRecordInfo::record); - std::optional const ownKey = - effect.kind == "updates" && use == ReplyUse::Applied && own != info.records.end() ? own->keyField - : std::nullopt; - detail::RowsByKey rows; - if (ownKey) { - for (Value const* const row : detail::keyedRowsOf(reply, own->paths, *ownKey)) { - rows.insert_or_assign(detail::canonicalJson(*row->field(*ownKey)), row); - } - } - for (auto const& [key, entry] : _entries) { - static_cast(key); - ActionRecordInfo const* const held = entry->holding(record); - if (held == nullptr) { - continue; - } - if (!ownKey || !held->keyField) { - marks.add(*entry); - continue; - } - if (auto patched = detail::patchHeldRows(entry->confirmed, held->paths, *held->keyField, rows)) { - confirm(*entry, *patched); - } - // A fetch in flight may have read before the write, and would settle over the patch. - if (entry->pending.peek()) { - markStale(*entry); - } - } -} - -inline void Session::markAndRefetch(detail::Marks const& marks) { - for (detail::CacheEntry* const entry : marks.entries) { - markStale(*entry); - } - for (detail::CacheEntry const* const entry : marks.entries) { - refetchMounted(*entry); - } -} - -inline void Session::countTopics(detail::CacheEntry const& entry, int delta) { - if (entry.evaluate) { - return; - } - // One topic: its count, and the queues a change of the count from or to zero goes to. - auto const count = [delta](auto& refs, auto const& topic, auto& watches, auto& unwatches) { - int& refsOf = refs[topic]; - refsOf += delta; - if (delta > 0 && refsOf == 1 && unwatches.erase(topic) == 0) { - watches.insert(topic); - } else if (refsOf <= 0) { - refs.erase(topic); - if (watches.erase(topic) == 0) { - unwatches.insert(topic); - } - } - }; - if (!entry.records.empty()) { - for (ActionRecordInfo const& record : entry.records) { - count(_recordRefs, record.record, _watchRecords, _unwatchRecords); - } - return; - } - constexpr std::string_view kShared = "shared:"; - if (entry.instanceToken.starts_with(kShared)) { - count(_instanceRefs, std::pair{entry.typeId, entry.instanceToken.substr(kShared.size())}, _watchInstances, - _unwatchInstances); - } -} - -inline void Session::sendWatch(std::string_view kind, wire::WatchBody const& body) const { - auto completion = _options.watcher(std::string{kind}, glz::write_json(body).value_or(std::string{})); - completion.then([](std::string const&) {}).onError([](std::exception_ptr const&) {}); -} - -inline void Session::flushWatches() { - if (!_options.watcher) { - _watchRecords.clear(); - _unwatchRecords.clear(); - _watchInstances.clear(); - _unwatchInstances.clear(); - return; - } - auto const take = [](auto& records, auto& instances) { - wire::WatchBody body; - body.records.assign(records.begin(), records.end()); - for (auto const& [modelType, primary] : instances) { - body.instances.push_back(wire::InstanceTopic{.modelType = modelType, .primary = primary, .instance = 0}); - } - records.clear(); - instances.clear(); - return body; - }; - if (!_watchRecords.empty() || !_watchInstances.empty()) { - sendWatch(wire::kWatchKind, take(_watchRecords, _watchInstances)); - } - if (!_unwatchRecords.empty() || !_unwatchInstances.empty()) { - sendWatch(wire::kUnwatchKind, take(_unwatchRecords, _unwatchInstances)); - } -} - -inline wire::WatchBody Session::watchSet() const { - wire::WatchBody body; - for (auto const& [record, refs] : _recordRefs) { - static_cast(refs); - body.records.push_back(record); - } - for (auto const& [topic, refs] : _instanceRefs) { - static_cast(refs); - body.instances.push_back( - wire::InstanceTopic{.modelType = topic.first, .primary = topic.second, .instance = 0}); - } - return body; -} - -inline void Session::markAllStale() { - _runtime->batch([this] { - detail::Marks marks; - for (auto const& [key, entry] : _entries) { - static_cast(key); - if (!entry->evaluate) { - marks.add(*entry); - } - } - markAndRefetch(marks); - }); -} - -inline void Session::reconnected() { - // The whole set replaces what the server holds, so the queued changes are superseded. - _watchRecords.clear(); - _unwatchRecords.clear(); - _watchInstances.clear(); - _unwatchInstances.clear(); - if (_options.watcher) { - wire::WatchBody body = watchSet(); - body.replace = true; - sendWatch(wire::kWatchKind, body); - } - markAllStale(); -} - -inline void Session::deliverEvent(wire::EventBody const& event) { - if (event.topic == wire::kResyncTopic) { - reconnected(); - return; - } - if (event.topic != wire::kChangesTopic) { - return; - } - if (auto changes = wire::readChangesBody(event.payload.str)) { - applyChanges(*changes); - } -} - -inline void Session::applyChanges(wire::ChangesBody const& changes) { - _runtime->batch([&] { - detail::Marks marks; - for (effects::RecordChange const& change : changes.records) { - markRecordChange(change, marks); - } - for (wire::InstanceTopic const& instance : changes.instances) { - markInstanceChange(instance, marks); - } - markAndRefetch(marks); - }); -} - -inline void Session::markRecordChange(effects::RecordChange const& change, detail::Marks& marks) { - // The keys' canonical text, so a key the server wrote is compared with the rows' own. - std::set> keys; - for (glz::raw_json const& key : change.keys.value_or(std::vector{})) { - auto json = parseJson(key.str); - auto value = json ? valueFromJson(*json) : std::unexpected(json.error()); - if (value) { - keys.insert(detail::canonicalJson(*value)); - } - } - for (auto const& [name, entry] : _entries) { - static_cast(name); - ActionRecordInfo const* const held = entry->holding(change.record); - if (held == nullptr) { - continue; - } - // An entry still waiting for its first value may come to hold a key; keyless rows cannot be told apart. - if (!change.keys || !held->keyField || !entry->hasValue.peek()) { - marks.add(*entry); - continue; - } - std::string const& keyField = *held->keyField; - bool const holdsKey = std::ranges::any_of( - detail::keyedRowsOf(entry->confirmed, held->paths, keyField), - [&](Value const* row) { return keys.contains(detail::canonicalJson(*row->field(keyField))); }); - if (holdsKey) { - marks.add(*entry); - } - } -} - -inline void Session::markInstanceChange(wire::InstanceTopic const& instance, detail::Marks& marks) { - std::string const shared = "shared:" + instance.primary; - for (auto const& [name, entry] : _entries) { - static_cast(name); - if (entry->evaluate || entry->typeId != instance.modelType) { - continue; - } - // Without a primary key, the instance is one of the connection's own private ones. - bool const same = - instance.primary.empty() ? !entry->instanceToken.starts_with("shared") : entry->instanceToken == shared; - if (same) { - marks.add(*entry); - } - } -} - -inline void Session::actionSucceeded(std::string const& typeId, std::string const& actionId, Value const& reply, - ReplyUse use, std::string const& instanceToken) { - _runtime->batch([&] { applyReplyEffects(typeId, actionId, reply, use, instanceToken); }); -} - -inline void Session::detachQuery(detail::QueryRuntime& query) { query.detach(); } - namespace detail { /// @brief The text of an instance key, as the bridge's string-keyed attach takes it. /// @param key The key's value. /// @return The text; empty for `null`. -[[nodiscard]] inline std::string instanceKeyText(Value const& key) { - if (key.isNull()) { - return {}; - } - if (std::int64_t const* const number = key.asInt()) { - return std::to_string(*number); - } - if (std::string const* const text = key.asString()) { - return *text; - } - return canonicalJson(key); -} - -/// @brief The channel an alias is bound to for its current token, binding it when the token changed. -/// @param alias The alias. -/// @param core The screen. -/// @return The channel, or `nullptr` while the alias is unbound. -[[nodiscard]] inline std::shared_ptr channelOf(ModelAlias& alias, ScreenCore& core) { - std::string const token = core.runtime().untracked([&] { return alias.token->get(); }); - if (token.empty()) { - return nullptr; - } - if (alias.channel && alias.boundToken == token) { - return alias.channel; - } - std::string const& type = alias.decl->type; - switch (alias.mode) { - case InstanceMode::Borrowed: { - auto const found = core.borrowed.find(alias.decl->name); - alias.channel = found == core.borrowed.end() ? nullptr : found->second.channel; - break; - } - case InstanceMode::Shared: - // `shared` is for a stateless model, whose instances are interchangeable: its calls go to an instance of - // the alias's own, and what it shares with other screens is the query cache, through the token. - alias.channel = core.dispatcher.bind(type, bridge::BindSharing::Private, {}); - break; - case InstanceMode::Keyed: - alias.channel = core.dispatcher.bind(type, bridge::BindSharing::Shared, token.substr(7)); - break; - case InstanceMode::Private: - case InstanceMode::Default: - default: - alias.channel = core.dispatcher.bind(type, bridge::BindSharing::Private, {}); - break; - } - alias.boundToken = token; - return alias.channel; -} - -inline RtScope::RtScope(ScreenCore& screen, std::shared_ptr enclosing, reactive::Signal const* current, - std::size_t depth) - : core{screen}, parent{std::move(enclosing)}, row{current}, nodes{screen.runtime(), depth} { - if (core.recording) { - core.scopes.push_back(this); - } -} - -inline RtScope::~RtScope() { - if (core.recording) { - std::erase(core.scopes, this); - } - if (owner != nullptr) { - core.addPending(-1); - if (owner->inner.peek() == this) { - owner->inner.set(nullptr); - } - } -} - -// NOLINTNEXTLINE(misc-no-recursion): an element's value can read a nested scope's readiness, one level per nesting. -inline bool RtScope::ready() const { - for (auto const& element : elements) { - Value const shown = core.elementValue(*element, "visible"); - bool const* const visible = shown.asBool(); - ValueList const* const errors = element->errors->get().asList(); - if ((visible == nullptr || *visible) && errors != nullptr && !errors->empty()) { - return false; - } - } - for (auto const& check : checks) { - if (check->decl->blocking && check->failing->get()) { - return false; - } - } - return true; -} - -// NOLINTNEXTLINE(misc-no-recursion): an `app.` name is read in the root scope with its head consumed, once per segment. -inline Value ScopeEnv::ref(std::string_view head, std::span path) const { - if (head == "app") { - RtScope const* const app = _scope->core.session.appScope(); - if (app == nullptr || path.empty()) { - return Value{}; - } - return ScopeEnv{*app, nullptr}.ref(path.front(), path.subspan(1)); - } - if (_bindings != nullptr) { - for (Binding const& bound : std::views::reverse(*_bindings)) { - if (bound.name == head) { - return walk(bound.read(), path); - } - } - } - NameRef const* const name = _scope->find(head); - if (name == nullptr) { - return Value{}; - } - switch (name->category) { - case NameCategory::Param: - return walk(name->param, path); - case NameCategory::State: - _scope->core.initState(*name->state->scope, *name->state); - // State inits are acyclic (`loadDocument` checks it), so the value is made by now. - return walk(name->state->value->get(), path); - case NameCategory::Let: - return walk(name->let->get(), path); - case NameCategory::Query: - return walk(name->query->value(), path); - case NameCategory::Element: - if (path.empty()) { - return Value{}; - } - return walk(_scope->core.elementValue(*name->element, path.front()), path.subspan(1)); - case NameCategory::Transfer: { - if (path.empty()) { - return Value{}; - } - TransferState const& transfer = *name->transfer; - Value value; - if (path.front() == "progress") { - value = transfer.progress.get(); - } else if (path.front() == "pending") { - value = Value{transfer.pending.get()}; - } else if (path.front() == "error") { - value = transfer.error.get(); - } - return walk(value, path.subspan(1)); - } - case NameCategory::Model: - case NameCategory::Mutation: - default: - return Value{}; - } -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per control form and kind of name. -inline Value ScopeEnv::control(ExprKind form, std::string_view name) const { - Session const& session = _scope->core.session; - NameRef const* const found = _scope->find(name); - if (form == ExprKind::Can) { - if (found != nullptr && found->category == NameCategory::Query) { - return session.can(found->query->decl().action); - } - if (found != nullptr && found->category == NameCategory::Mutation) { - return session.can(found->mutation->decl().action); - } - return session.can(name); - } - if (found != nullptr && found->category == NameCategory::Query) { - QueryRuntime const& query = *found->query; - if (form == ExprKind::Query) { - return query.value(); - } - if (form == ExprKind::Pending) { - return query.pending(); - } - if (form == ExprKind::Error) { - return query.error(); - } - if (form == ExprKind::Refusal) { - return query.refusal(); - } - return form == ExprKind::ErrorKind ? query.errorKind() : Value{}; - } - if (found != nullptr && found->category == NameCategory::Mutation) { - MutationRuntime const& mutation = *found->mutation; - if (form == ExprKind::Result) { - return mutation.result(); - } - if (form == ExprKind::Pending) { - return mutation.pending(); - } - if (form == ExprKind::Error) { - return mutation.error(); - } - if (form == ExprKind::Refusal) { - return mutation.refusal(); - } - return form == ExprKind::ErrorKind ? mutation.errorKind() : Value{}; - } - return Value{}; -} - -inline Value ScopeEnv::pref(std::string_view point, std::span path) const { - ValueRecord const& prefs = _scope->core.prefs.get(); - auto const found = prefs.find(point); - return found == prefs.end() ? Value{} : walk(found->second, path); -} - -inline Value ScopeEnv::client(ExprKind form, std::string_view name) const { - return _scope->core.session.client(form, name); -} - -inline FormatContext const& RtScope::formatting() const { - for (RtScope const* scope = this; scope != nullptr; - scope = scope->parent != nullptr ? scope->parent.get() : scope->formatSource.get()) { - if (scope->localeFormat != nullptr) { - return *scope->localeFormat->get(); - } - } - return core.session.formatting(); -} - -inline FormatContext const& ScopeEnv::formatting() const { return _scope->formatting(); } - -inline FormatContext const& ScopeEnv::entryFormatting() const { return _scope->core.session.formatting(); } - -inline void ScopeEnv::report(std::string_view path, std::string_view reason) const { - _scope->core.report(path, reason); -} - -// --- Queries --------------------------------------------------------------------------------------------------- - -inline QueryRuntime::QueryRuntime(QueryDecl const& decl, RtScope& scope, ModelAlias* alias) - : _decl{&decl}, - _typeId{alias->decl->type}, - _scope{&scope}, - _alias{alias}, - _entry{scope.core.runtime()}, - _carried{scope.core.runtime()}, - _waiting{scope.core.runtime(), false} { - scope.core.session.attachQuery(*this); -} - -inline QueryRuntime::~QueryRuntime() { - _debounce.cancel(); - _refresh.cancel(); - _scope->core.session.forgetQuery(*this); - if (auto const& current = _entry.peek()) { - _scope->core.session.release(current); - } -} - -inline std::shared_ptr QueryRuntime::channel() const { return channelOf(*_alias, _scope->core); } - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): the query's key, its fetch and its refresh triggers. -inline void QueryRuntime::start() { - RtScope& scope = *_scope; - auto& key = scope.nodes.computed([this]() -> Target { - Target target; - if (_decl->when) { - Value const when = evalIn(*_scope, nullptr, _decl->when); - bool const* const flag = when.asBool(); - if (flag == nullptr || !*flag) { - return target; - } - } - std::string token = _alias->token->get(); - if (token.empty()) { - return target; - } - Value body = _decl->body ? evalIn(*_scope, nullptr, _decl->body) : Value{ValueRecord{}}; - if (body.isNull()) { - return target; - } - target.idle = false; - target.token = std::move(token); - target.bodyText = canonicalJson(body); - target.body = std::move(body); - return target; - }); - _key = &key; - reactive::Scheduler* const scheduler = scope.core.session.options().scheduler; - std::weak_ptr const alive = _alive; - scope.nodes.effect([this, &key, scheduler, alive, first = true]() mutable { - Target target = key.get(); - _scope->core.runtime().untracked([&] { - if (first || target.idle || _decl->debounce <= 0 || scheduler == nullptr) { - first = false; - _debounce.cancel(); - _waiting.set(false); - switchTo(target); - return; - } - _pendingTarget = std::move(target); - _waiting.set(true); - _debounce = scheduler->after(std::chrono::milliseconds{_decl->debounce}, [this, alive] { - if (alive.expired()) { - return; - } - _scope->core.runtime().batch([this] { - _waiting.set(false); - switchTo(_pendingTarget); - }); - }); - }); - }); - if (_decl->refreshEvery > 0 && scheduler != nullptr) { - _refresh = scheduler->every(std::chrono::milliseconds{_decl->refreshEvery}, [this, alive] { - if (alive.expired()) { - return; - } - auto const current = _entry.peek(); - if (!current || _waiting.peek() || current->pending.peek()) { - return; - } - _scope->core.runtime().batch([&] { _scope->core.session.fetch(current, channel()); }); - }); - } -} - -inline void QueryRuntime::switchTo(Target const& target) { - Session& session = _scope->core.session; - std::shared_ptr const old = _entry.peek(); - if (old && target == _target) { - return; - } - Value shown = old && old->hasValue.peek() ? old->value.peek() : _carried.peek(); - _target = target; - if (target.idle) { - _carried.set(Value{}); - _entry.set(nullptr); - if (old) { - session.release(old); - } - return; - } - auto fresh = session.acquire(target.token, _typeId, _decl->action, _decl->evaluate, target.body); - _carried.set(std::move(shown)); - _entry.set(fresh); - if (old) { - session.release(old); - } - bool const young = fresh->fetchedAt.has_value() && - session.now() - *fresh->fetchedAt < std::chrono::milliseconds{_decl->staleTime}; - if (!fresh->pending.peek() && (!fresh->hasValue.peek() || fresh->stale || !young)) { - session.fetch(fresh, channel()); - } -} - -inline void QueryRuntime::refetch() { - _scope->core.runtime().batch([this] { - bool switched = false; - if (_waiting.peek()) { - _debounce.cancel(); - _waiting.set(false); - switchTo(_pendingTarget); - switched = true; - } - auto const current = _entry.peek(); - if (current && !(switched && current->pending.peek())) { - _scope->core.session.fetch(current, channel()); - } - }); -} +[[nodiscard]] MORPH_API std::string instanceKeyText(Value const& key); -inline void QueryRuntime::refetchCurrent() { - if (_key == nullptr) { - refetch(); - return; - } - _scope->core.runtime().batch([this] { - _debounce.cancel(); - _waiting.set(false); - Target const target = _key->peek(); - if (!(_entry.peek() && target == _target)) { - switchTo(target); - return; - } - if (auto const current = _entry.peek(); current && !current->pending.peek()) { - _scope->core.session.fetch(current, channel()); - } - }); -} - -inline Value QueryRuntime::value() const { - auto const& current = _entry.get(); - if (current) { - if (current->hasValue.get()) { - return current->value.get(); - } - if (!current->error.get().empty()) { - return Value{}; - } - } - return _carried.get(); -} +/// @brief A JSON text as a document value; `null` when it is not JSON or holds what a value cannot (a fraction). +/// @param text The JSON text. +/// @return The value. +[[nodiscard]] MORPH_API Value jsonTextValue(std::string_view text); -inline bool QueryRuntime::pending() const { - if (_waiting.get()) { - return true; - } - auto const& current = _entry.get(); - return current && current->pending.get(); -} - -inline Value QueryRuntime::error() const { - auto const& current = _entry.get(); - if (!current || current->error.get().empty()) { - return Value{}; - } - return Value{current->error.get()}; -} +/// @brief Base64 text as bytes (RFC 4648, with or without padding). +/// @param text The text. +/// @return The bytes, or `std::nullopt` for text that is not base64. +[[nodiscard]] MORPH_API std::optional base64Decode(std::string_view text); -inline Value QueryRuntime::errorKind() const { - auto const& current = _entry.get(); - if (!current || current->errorKind.get().empty()) { - return Value{}; - } - return Value{current->errorKind.get()}; -} - -inline Value QueryRuntime::refusal() const { - auto const& current = _entry.get(); - return current ? current->refusal.get() : Value{}; -} - -inline bool QueryRuntime::settled() const { - auto const& current = _entry.get(); - return !current || current->hasValue.get() || !current->error.get().empty(); -} - -// --- Mutations ------------------------------------------------------------------------------------------------- - -inline MutationRuntime::MutationRuntime(MutationDecl const& decl, RtScope& scope, ModelAlias* alias) - : _decl{&decl}, - _scope{&scope}, - _alias{alias}, - _typeId{alias->decl->type}, - _core{&scope.core}, - _inFlight{scope.core.runtime(), 0}, - _result{scope.core.runtime()}, - _error{scope.core.runtime()}, - _errorKind{scope.core.runtime()}, - _refusal{scope.core.runtime()} {} - -inline MutationRuntime::~MutationRuntime() { - *_alive = false; - // A run whose reply will now never be read is no longer pending. - if (int const running = _inFlight.peek(); running > 0) { - _core->addPending(-running); - } -} - -// NOLINTBEGIN(misc-no-recursion): a mutation's commands can run another mutation, and a serial queue sends its next -// run as the last one settles. -inline void MutationRuntime::run(Value body, std::shared_ptr bindings, RunDone done) { - auto run = std::make_shared(); - run->body = std::move(body); - run->bindings = std::move(bindings); - run->done = std::move(done); - if (_decl->concurrency == Concurrency::Exclusive && _inFlight.peek() > 0) { - run->done(false, Value{}); - return; - } - _inFlight.set(_inFlight.peek() + 1); - _core->addPending(1); - if (_decl->concurrency == Concurrency::Serial) { - // The key reads the run's body, so a run keys the same whichever command started it. - Bindings withBody = *run->bindings; - withBody.push_back(Binding{.name = "body", .read = [body = run->body] { return body; }}); - Value const key = evalIn(*_scope, &withBody, _decl->serialKey); - run->serialKey = key.isNull() ? std::string{} : canonicalJson(key); - if (_busy.contains(run->serialKey)) { - _queues[run->serialKey].push_back(run); - return; - } - _busy.insert(run->serialKey); - } - send(run); -} - -inline void MutationRuntime::send(std::shared_ptr const& run) { - run->id = ++_runs; - _latest = run->id; - applyOptimistic(*run); - std::shared_ptr const channel = channelOf(*_alias, _scope->core); - if (channel == nullptr) { - settle(run, std::nullopt, std::make_exception_ptr(std::runtime_error{"the model alias has no instance"})); - return; - } - std::weak_ptr const alive = _alive; - try { - auto completion = channel->execute(_decl->action, canonicalJson(run->body), - CallOptions{.queueOffline = _decl->offlineQueue}); - completion - .then([this, alive, run](std::string const& reply) { - if (alive.expired()) { - return; - } - auto json = parseJson(reply); - auto value = json ? valueFromJson(*json) : std::unexpected(json.error()); - if (!value) { - settle(run, std::nullopt, - std::make_exception_ptr( - std::runtime_error{"the reply is not a document value: " + value.error()})); - return; - } - settle(run, std::move(*value), nullptr); - }) - .onError([this, alive, run](std::exception_ptr const& error) { - if (!alive.expired()) { - settle(run, std::nullopt, error); - } - }); - } catch (...) { - settle(run, std::nullopt, std::current_exception()); - } -} +/// @brief How many bytes base64 text decodes to, read from its length alone. +/// @param text The text. +/// @return The byte count. +[[nodiscard]] MORPH_API std::size_t base64Size(std::string_view text); -inline void MutationRuntime::applyOptimistic(Run& run) { - if (!_decl->optimistic) { - return; - } - NameRef const* const target = _scope->find(_decl->optimistic->query); - if (target == nullptr || target->category != NameCategory::Query) { - return; - } - auto entry = _scope->core.runtime().untracked([&] { return target->query->entry(); }); - if (!entry) { - return; - } - Bindings bindings = *run.bindings; - bindings.push_back(Binding{.name = "body", .read = [body = run.body] { return body; }}); - Value key = _scope->core.runtime().untracked([&] { return evalIn(*_scope, &bindings, _decl->optimistic->key); }); - Value with = _scope->core.runtime().untracked([&] { return evalIn(*_scope, &bindings, _decl->optimistic->with); }); - // Before a value has arrived there is no list to miss. - if (entry->hasValue.peek() && - patchRows(entry->confirmed, _decl->optimistic->at, key, with).error_or(PatchMiss::NoRow) == - PatchMiss::NoList) { - _scope->core.report(pointerAppend(_decl->path, "optimistic"), - patchMissReason(_decl->optimistic->query, _decl->optimistic->at)); - } - entry->layers.push_back( - OptimisticLayer{.run = run.id, .at = _decl->optimistic->at, .key = std::move(key), .with = std::move(with)}); - _scope->core.session.showLayers(*entry); - run.layered.push_back(std::move(entry)); -} - -inline void MutationRuntime::dropLayers(Run& run) { - for (auto const& entry : run.layered) { - std::erase_if(entry->layers, [&](OptimisticLayer const& layer) { return layer.run == run.id; }); - _scope->core.session.showLayers(*entry); - } - run.layered.clear(); -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one branch per outcome a reply can have. -inline void MutationRuntime::settle(std::shared_ptr const& run, std::optional reply, - std::exception_ptr const& error) { - ScreenCore& core = _scope->core; - Session& session = core.session; - bool const applied = _decl->concurrency != Concurrency::Latest || run->id == _latest; - std::shared_ptr const scope = _scope->shared_from_this(); - auto commandCtx = [&](Bindings extra) { - return CommandCtx{.scope = scope, - .bindings = std::make_shared(std::move(extra)), - .cancelClose = std::make_shared(false), - .boundary = nullptr}; - }; - Value delivered; - bool succeeded = false; - // NOLINTNEXTLINE(readability-function-cognitive-complexity): one branch per outcome a reply can have. - core.runtime().batch([&] { - _inFlight.set(_inFlight.peek() - 1); - _core->addPending(-1); - if (reply) { - succeeded = true; - // The run's optimistic writes are confirmed by the reply: they become part of the confirmed rows. - for (auto const& entry : run->layered) { - Value confirmed = entry->confirmed; - for (OptimisticLayer const& layer : entry->layers) { - if (layer.run == run->id) { - if (auto patched = patchRows(confirmed, layer.at, layer.key, layer.with)) { - confirmed = std::move(*patched); - } - } - } - std::erase_if(entry->layers, [&](OptimisticLayer const& layer) { return layer.run == run->id; }); - session.confirm(*entry, confirmed); - } - run->layered.clear(); - std::vector secret; - if (session.options().catalog.action) { - if (auto const info = session.options().catalog.action(_decl->action)) { - secret = info->secretFields; - } - } - delivered = withoutFields(*reply, secret); - std::string const token = - _alias == nullptr ? std::string{} : core.runtime().untracked([&] { return _alias->token->get(); }); - if (!applied) { - session.actionSucceeded(_typeId, _decl->action, *reply, ReplyUse::Discarded, token); - return; - } - _result.set(*reply); - _error.set(Value{}); - _errorKind.set(Value{}); - _refusal.set(Value{}); - session.actionSucceeded(_typeId, _decl->action, *reply, ReplyUse::Applied, token); - core.runList(_decl->onSuccess, commandCtx(*run->bindings), {}); - if (!secret.empty()) { - _result.set(delivered); - } - return; - } - dropLayers(*run); - std::string const kind = session.classify(error); - if (applied) { - _error.set(Value{failureText(error)}); - _errorKind.set(Value{kind}); - _refusal.set(detail::refusalValue(error)); - core.runList(_decl->onError, commandCtx(*run->bindings), {}); - } - if (kind == "denied" && core.host != nullptr) { - core.host->permissionsStale(); - } - }); - if (_decl->concurrency == Concurrency::Serial) { - next(run->serialKey); - } - run->done(succeeded, delivered); -} - -inline void MutationRuntime::next(std::string const& serialKey) { - auto const found = _queues.find(serialKey); - if (found == _queues.end() || found->second.empty()) { - _queues.erase(serialKey); - _busy.erase(serialKey); - return; - } - std::shared_ptr const queued = found->second.front(); - found->second.pop_front(); - _scope->core.runtime().batch([&] { send(queued); }); -} -// NOLINTEND(misc-no-recursion) +/// @brief A byte count as a person reads it: `512 bytes`, `2.4 KiB`, `1 MiB`. +/// @param bytes The count. +/// @return The text. +[[nodiscard]] MORPH_API std::string sizeText(std::size_t bytes); -} // namespace detail +/// @brief A document's inline file content as bytes: base64 text, or a list of integers 0 to 255. +/// @param value The value. +/// @return The bytes, or why the value is neither. +[[nodiscard]] MORPH_API std::expected inlineBytes(Value const& value); -namespace detail { +/// @brief A value as a custom component's text prop (spec 5 §10): an `int` or `exact` as plain decimal text, so no +/// id or amount loses precision; `json` as its JSON text; `string` as the formatted text. +/// @param value The value. +/// @param type The prop type the component declares. +/// @param format The formatting facts, for `string`. +/// @return The text. +[[nodiscard]] MORPH_API std::string componentText(Value const& value, std::string_view type, + FormatContext const& format); -// --- Declaring scopes ------------------------------------------------------------------------------------------ - -/// @brief The element a node of a scope keeps its state in. -/// @param scope The scope that declares it. -/// @param node The node. -/// @return The element, or `nullptr` for a node that keeps none. -[[nodiscard]] inline ElementState* elementFor(RtScope const& scope, DocNode const& node) { - // A scope that declares nothing (a locale scope and the scope of its mounted content) leaves its children's - // elements to the enclosing scope, where `collect` registered them, so the lookup continues there. - for (RtScope const* at = &scope; at != nullptr; at = at->transparent ? at->parent.get() : nullptr) { - for (auto const& element : at->elements) { - if (element->node == &node) { - return element.get(); - } - } - } - return nullptr; -} - -/// @brief The transfers of the `upload` commands in a list, nested lists included. -/// @param commands The list. -/// @param out Where the transfer ids go. -// NOLINTNEXTLINE(misc-no-recursion): one level per nested command list -inline void transfersOf(Commands const& commands, std::vector& out) { - for (Command const& command : commands) { - if (command.kind == CommandKind::Upload && !command.transfer.empty()) { - out.push_back(command.transfer); - } - transfersOf(command.commands, out); - transfersOf(command.alternative, out); - } -} - -// NOLINTBEGIN(misc-no-recursion): a document is a tree of nodes and parts, and collecting descends it. -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of node and part. -inline void ScreenCore::collect(DocNode const& node, RtScope& scope, std::vector& commands) { - KindSpec const* const spec = findKind(node.kind, false); - if (!node.id.empty() || statefulKind(node.kind)) { - auto element = std::make_unique(runtime()); - element->node = &node; - element->scope = &scope; - if (!node.id.empty()) { - NameRef name; - name.category = NameCategory::Element; - name.element = element.get(); - scope.names.insert_or_assign(node.id, name); - } - wireErrors(*element); - scope.elements.push_back(std::move(element)); - } - bool const createsScope = spec != nullptr && (spec->flags & kScope) != 0; - for (auto const& [key, list] : node.events) { - KeySpec const* const keyed = spec == nullptr ? nullptr : keySpec(*spec, key); - if (!createsScope || keyed == nullptr || (keyed->flags & kInner) == 0) { - commands.push_back(&list); - } - } - for (auto const& [chord, list] : node.keys) { - static_cast(chord); - commands.push_back(&list); - } - for (auto const& [key, nodes] : node.children) { - KeySpec const* const keyed = spec == nullptr ? nullptr : keySpec(*spec, key); - if (createsScope && keyed != nullptr && (keyed->flags & kInner) != 0) { - continue; - } - for (DocNodePtr const& child : nodes) { - collect(*child, scope, commands); - } - } - for (auto const& [key, parts] : node.parts) { - static_cast(key); - for (DocNodePtr const& part : parts) { - KindSpec const* const partSpec = findKind(part->kind, true); - if (partSpec != nullptr && (partSpec->flags & kScope) != 0) { - continue; - } - for (auto const& [event, list] : part->events) { - static_cast(event); - commands.push_back(&list); - } - for (auto const& [childKey, nodes] : part->children) { - KeySpec const* const keyed = partSpec == nullptr ? nullptr : keySpec(*partSpec, childKey); - if (keyed != nullptr && (keyed->flags & kInner) != 0) { - continue; - } - for (DocNodePtr const& child : nodes) { - collect(*child, scope, commands); - } - } - } - } -} -// NOLINTEND(misc-no-recursion) - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one section per kind of declaration. -inline void ScreenCore::declare(RtScope& scope, ScopeDecl const* decl, std::vector const& content, - std::vector const& commands) { - std::vector lists = commands; - for (DocNode const* const node : content) { - collect(*node, scope, lists); - } - std::vector transferIds; - for (Commands const* const list : lists) { - transfersOf(*list, transferIds); - } - for (std::string const& transferId : transferIds) { - if (scope.names.contains(transferId)) { - continue; - } - scope.transfers.push_back(std::make_unique(runtime())); - NameRef name; - name.category = NameCategory::Transfer; - name.transfer = scope.transfers.back().get(); - scope.names.insert_or_assign(transferId, name); - } - if (decl != nullptr) { - for (ModelDecl const& model : decl->models) { - auto alias = std::make_unique(); - alias->decl = &model; - alias->mode = model.instance; - if (alias->mode == InstanceMode::Default) { - std::optional const info = - session.options().catalog.model ? session.options().catalog.model(model.type) : std::nullopt; - alias->mode = info && info->stateless ? InstanceMode::Shared : InstanceMode::Private; - } - ModelAlias* const raw = alias.get(); - switch (raw->mode) { - case InstanceMode::Keyed: - raw->token = &scope.nodes.computed([&scope, raw]() -> std::string { - std::string const key = instanceKeyText(evalIn(scope, nullptr, raw->decl->key)); - return key.empty() ? std::string{} : "shared:" + key; - }); - break; - case InstanceMode::Shared: - raw->token = &scope.nodes.computed([] { return std::string{"shared"}; }); - break; - case InstanceMode::Borrowed: { - auto const found = borrowed.find(model.name); - std::string token = found == borrowed.end() ? std::string{} : found->second.token; - raw->token = &scope.nodes.computed([token = std::move(token)] { return token; }); - break; - } - case InstanceMode::Private: - case InstanceMode::Default: - default: { - std::string token = session.privateToken(); - raw->token = &scope.nodes.computed([token = std::move(token)] { return token; }); - break; - } - } - NameRef name; - name.category = NameCategory::Model; - name.model = raw; - scope.names.insert_or_assign(model.name, name); - scope.models.push_back(std::move(alias)); - } - for (LetDecl const& let : decl->lets) { - NameRef name; - name.category = NameCategory::Let; - name.letExpr = let.value; - name.let = &scope.nodes.computed([&scope, expr = let.value] { return evalIn(scope, nullptr, expr); }); - scope.names.insert_or_assign(let.name, name); - } - for (StateDecl const& state : decl->state) { - auto slot = std::make_unique(); - slot->decl = &state; - slot->scope = &scope; - NameRef name; - name.category = NameCategory::State; - name.state = slot.get(); - scope.names.insert_or_assign(state.name, name); - scope.states.push_back(std::move(slot)); - } - auto aliasOf = [&scope](std::string const& model) -> ModelAlias* { - NameRef const* const found = scope.find(model); - return found != nullptr && found->category == NameCategory::Model ? found->model : nullptr; - }; - for (QueryDecl const& query : decl->queries) { - scope.queries.push_back(std::make_unique(query, scope, aliasOf(query.model))); - NameRef name; - name.category = NameCategory::Query; - name.query = scope.queries.back().get(); - scope.names.insert_or_assign(query.name, name); - } - for (MutationDecl const& mutation : decl->mutations) { - scope.mutations.push_back(std::make_unique(mutation, scope, aliasOf(mutation.model))); - NameRef name; - name.category = NameCategory::Mutation; - name.mutation = scope.mutations.back().get(); - scope.names.insert_or_assign(mutation.name, name); - } - } - for (auto const& slot : scope.states) { - initState(scope, *slot); - } - for (auto const& element : scope.elements) { - wireElement(*element); - } - if (decl == nullptr) { - return; - } - for (CheckDecl const& check : decl->checks) { - auto made = std::make_unique(); - made->decl = ✓ - made->failing = &scope.nodes.computed([&scope, expr = check.assertion] { - Value const asserted = evalIn(scope, nullptr, expr); - bool const* const flag = asserted.asBool(); - return flag != nullptr && !*flag; - }); - made->message = &scope.nodes.computed( - [&scope, expr = check.message] { return textOf(evalIn(scope, nullptr, expr), scope.formatting()); }); - for (std::string const& target : check.targets) { - NameRef const* const found = scope.find(target); - if (found != nullptr && found->category == NameCategory::Element) { - found->element->checks.push_back(made.get()); - made->targets.push_back(found->element); - found->element->checksVersion.set(found->element->checksVersion.peek() + 1); - } - } - scope.checks.push_back(std::move(made)); - } - for (auto const& query : scope.queries) { - query->start(); - } - for (WatchDecl const& watch : decl->watches) { - auto& source = scope.nodes.computed([&scope, expr = watch.on] { return evalIn(scope, nullptr, expr); }); - scope.nodes.effect([this, &scope, &source, watched = &watch, first = true]() mutable { - static_cast(source.get()); - if (first) { - first = false; - return; - } - bool const user = session.lastWriteByUser(); - if (watched->source == WatchSource::User && !user) { - return; - } - runtime().untracked([&] { - CommandCtx const ctx{.scope = scope.shared_from_this(), - .bindings = std::make_shared(), - .cancelClose = std::make_shared(false), - .boundary = nullptr}; - if (user) { - session.asUser([&] { runList(watched->body, ctx, {}); }); - } else { - runList(watched->body, ctx, {}); - } - }); - }); - } -} - -/// @brief What a date input reads from a value: the instant it shows, and whether the value names one at all. -struct DateReading { - /// @brief The instant shown; empty for an empty field. - std::optional instant; - /// @brief Whether the value names a date, an instant or nothing; `false` for text that names no date. - bool readable = true; -}; +/// @brief A value as a custom component's `number` prop: the one kind that crosses as a double. +/// @param value The value. +/// @return It; zero for anything that is not a number. +[[nodiscard]] MORPH_API double componentNumber(Value const& value); -/// @brief Reads what a date input shows for @p value, in a display zone @p offsetMinutes from UTC. -/// -/// The value is read as the date functions read it (`readDateValue`): a timestamp is its instant; a `yyyy-MM-dd` -/// string is midnight of that date in the display zone; a string `DateTime::fromIso8601` reads is its instant; `null` -/// and `""` are empty. Any other value is empty and unreadable. -/// @param value The value. -/// @param offsetMinutes The display zone's offset from UTC, in minutes. -/// @return The instant, or nothing, and whether the value was readable. -[[nodiscard]] inline DateReading dateInstantOf(Value const& value, std::int32_t offsetMinutes) { - DateValue const reading = readDateValue(value); - switch (reading.form) { - case DateForm::Absent: - return {}; - case DateForm::Date: - return {.instant = - time::DateTime{std::chrono::sys_days{reading.date} - std::chrono::minutes{offsetMinutes}}}; - case DateForm::Timestamp: - case DateForm::InstantText: - return {.instant = reading.instant}; - case DateForm::Unreadable: - default: - return {.instant = std::nullopt, .readable = false}; - } -} - -/// @brief A date input's date text for @p instant in a display zone @p offsetMinutes from UTC. -/// @param instant The instant. -/// @param offsetMinutes The display zone's offset from UTC, in minutes. -/// @return `yyyy-MM-dd`. -[[nodiscard]] inline std::string dateTextOf(time::DateTime const& instant, std::int32_t offsetMinutes) { - auto const local = instant.value + std::chrono::minutes{offsetMinutes}; - std::chrono::year_month_day const date{std::chrono::floor(local)}; - return std::format("{:04}-{:02}-{:02}", static_cast(date.year()), static_cast(date.month()), - static_cast(date.day())); -} - -/// @brief A value as the places a number is entered with. -/// @param value The value. -/// @param format The formatting facts. -/// @return The places, 0 to the most a decimal holds; -1 for a value that is not a non-negative integer. -[[nodiscard]] inline int placesOf(Value const& value, FormatContext const& format) { - static_cast(format); // Only to fit `bindProp`'s converter signature. - std::int64_t const* const whole = value.asInt(); - if (whole == nullptr || *whole < 0) { - return -1; - } - return static_cast(std::min(*whole, math::kMaxDecimalPlaces)); -} +/// @brief A custom component's event payload as a value: `i:` an `int`, `s:` a `string`, anything else +/// JSON text read as the event's declared type, and text that is none of those a `string`. +/// @param payload The payload, as the backend reports it. +/// @param type The payload type the component declares; null for an undeclared event. +/// @return The value. +[[nodiscard]] MORPH_API Value componentPayload(std::string const& payload, Type const* type); -/// @brief The fraction digits of a number as typed in the active locale. -/// @param text The typed text. -/// @param format The formatting facts. -/// @return The digits after the decimal separator; 0 for a text that is not a number, which no places rule judges. -[[nodiscard]] inline std::size_t fractionDigits(std::string_view text, FormatContext const& format) { - std::optional const canonical = render::normalizeLocaleNumber(text, withoutGrouping(format.numeric)); - if (!canonical.has_value()) { - return 0; - } - auto const dot = canonical->find('.'); - return dot == std::string::npos ? 0 : canonical->size() - dot - 1; -} - -/// @brief Whether two values show the same in an input: by text for a text input, by instant for a date input, by -/// value otherwise. -/// @param kind The input's kind. -/// @param lhs One value. -/// @param rhs The other. -/// @param format The formatting facts. +/// @brief A value as an integer: an `int`, or a decimal truncated toward zero. +/// @param value The value. +/// @param fallback What anything else gives. /// @return It. -[[nodiscard]] inline bool sameShown(std::string_view kind, Value const& lhs, Value const& rhs, - FormatContext const& format) { - if (kind == "textInput" || kind == "filePicker") { - return textOf(lhs, format) == textOf(rhs, format); - } - if (kind == "dateTimeInput") { - return dateInstantOf(lhs, format.utcOffsetMinutes).instant == - dateInstantOf(rhs, format.utcOffsetMinutes).instant; - } - return lhs == rhs; -} - -/// @brief The key of a select option: a record's `key`, `id` or `value` field, or the option itself. -/// @param option The option. -/// @return The key. -[[nodiscard]] inline Value optionKey(Value const& option) { - if (option.asRecord() == nullptr) { - return option; - } - for (std::string_view const field : {"key", "id", "value"}) { - if (Value const* const found = option.field(field)) { - return *found; - } - } - return Value{}; -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one rule per source of an error. -inline void ScreenCore::wireErrors(ElementState& element) { - RtScope& scope = *element.scope; - element.errors = &scope.nodes.computed([this, &element]() -> Value { - static_cast(element.checksVersion.get()); - DocNode const& field = *element.node; - RtScope const& owner = *element.scope; - std::vector errors; - // A group's `required` is its legend's mark only: a group has no value, so no `Required` is derived from it. - if (ExprPtr const required = field.kind != "group" ? field.prop("required") : nullptr) { - Value const requiredNow = evalIn(owner, nullptr, required); - bool const* const flag = requiredNow.asBool(); - if (flag != nullptr && *flag && !engaged(inputValue(element))) { - errors.emplace_back("Required"); - } - } - for (std::string& text : stringsOf(evalIn(owner, nullptr, field.prop("errors")))) { - errors.push_back(std::move(text)); - } - if (ExprPtr const places = field.kind == "textInput" ? field.prop("decimals") : nullptr) { - int const allowed = placesOf(evalIn(owner, nullptr, places), session.formatting()); - if (allowed >= 0 && fractionDigits(textOf(inputValue(element), session.formatting()), - session.formatting()) > static_cast(allowed)) { - // The key and fallback of a form field's `too-precise`, so both read alike in any language. - errors.emplace_back(render::resolveText(session.formatting().translations, session.formatting().locale, - std::nullopt, "morph.forms.error.too-precise", - "Too many decimal places")); - } - } - if (!field.id.empty()) { - std::vector const path{"errors", field.id}; - for (auto const& query : owner.queries) { - for (std::string& text : stringsOf(walk(query->value(), path))) { - errors.push_back(std::move(text)); - } - } - for (auto const& mutation : owner.mutations) { - for (std::string& text : stringsOf(walk(mutation->result(), path))) { - errors.push_back(std::move(text)); - } - } - } - for (CheckRuntime const* const check : element.checks) { - if (check->failing->get()) { - errors.push_back(check->message->get()); - } - } - return listOfStrings(errors); - }); -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of element. -inline void ScreenCore::wireElement(ElementState& element) { - DocNode const& node = *element.node; - RtScope& scope = *element.scope; - std::string_view const kind = node.kind; - if (kind == "form") { - wireForm(element); - return; - } - if (kind == "collection" || kind == "wizard") { - wireComposite(element); - return; - } - bool const input = kind == "textInput" || kind == "checkbox" || kind == "select" || kind == "dateTimeInput" || - kind == "slider" || kind == "filePicker"; - if (input) { - std::string_view key = "value"; - if (kind == "checkbox") { - key = "checked"; - } else if (kind == "select") { - key = "selected"; - } - ExprPtr const expr = kind == "filePicker" ? nullptr : node.prop(key); - bool const controlled = expr && (expr->kind != ExprKind::Literal || !expr->literal.isNull()); - if (controlled) { - element.bound = &scope.nodes.computed([&scope, expr] { return evalIn(scope, nullptr, expr); }); - element.draft.set(runtime().untracked([&] { return element.bound->get(); })); - scope.nodes.effect([this, &element, kind] { - Value const bound = element.bound->get(); - runtime().untracked([&] { - if (!element.edited.peek()) { - element.draft.set(bound); - } else if (sameShown(kind, element.draft.peek(), bound, session.formatting())) { - element.edited.set(false); - } - }); - }); - } else if (kind == "checkbox") { - element.draft.set(false); - } - } - if (kind == "select") { - element.rows = - &scope.nodes.computed([&scope, expr = node.prop("options")] { return evalIn(scope, nullptr, expr); }); - if (element.bound == nullptr && node.name("onStale") == "clear") { - scope.nodes.effect([this, &element] { - Value const options = element.rows->get(); - runtime().untracked([&] { - Value const selected = element.draft.peek(); - if (selected.isNull()) { - return; - } - ValueList const* const items = options.asList(); - bool const kept = items != nullptr && std::ranges::any_of(*items, [&](Value const& option) { - return optionKey(option) == selected; - }); - if (!kept) { - session.noteWrite(); - element.draft.set(Value{}); - } - }); - }); - } - } - if (kind == "table" && node.prop("rows")) { - element.rows = - &scope.nodes.computed([&scope, expr = node.prop("rows")] { return evalIn(scope, nullptr, expr); }); - // A bound selection is controlled, as a select's `selected` is: any expression but a literal `null` binds it. - ExprPtr const selection = node.prop("selection"); - if (selection && (selection->kind != ExprKind::Literal || !selection->literal.isNull())) { - element.bound = &scope.nodes.computed([&scope, selection] { return evalIn(scope, nullptr, selection); }); - } - // A bound sort is controlled as the selection is. - ExprPtr const sort = node.prop("sort"); - if (sort && (sort->kind != ExprKind::Literal || !sort->literal.isNull())) { - element.sortBound = &scope.nodes.computed([&scope, sort] { return evalIn(scope, nullptr, sort); }); - } - element.view = &scope.nodes.computed([this, &element] { return tableView(element, nullptr); }); - } -} - -/// @brief A table's sort as its element value reads it: the bound `sort` when the key binds one, else the table's -/// own. -/// @param element The table's element. -/// @return The sort. Tracked. -[[nodiscard]] inline Value tableSort(ElementState const& element) { - return element.sortBound != nullptr ? element.sortBound->get() : element.sort.get(); -} - -/// @brief A table's page values: `viewCount` (the rows it orders, every page), `page`, `pageCount`, and -/// `pageFirst` and `pageLast`, the 1-based positions of the page's first and last rows, both 0 when there are -/// none. A table that does not page reads page 0 of 1, over every row. -/// @param element The table's element. -/// @param name The value's name. -/// @return The value. Tracked. -[[nodiscard]] inline Value tablePageValue(ElementState const& element, std::string_view name) { - if (element.view == nullptr) { - return name == "pageCount" ? std::int64_t{1} : std::int64_t{0}; - } - TableView const& view = element.view->get(); - if (name == "viewCount") { - return static_cast(view.rows.size()); - } - if (name == "page") { - return view.page; - } - if (name == "pageCount") { - return view.pageCount; - } - bool const none = view.first == view.last; - if (name == "pageFirst") { - return none ? std::int64_t{0} : static_cast(view.first + 1); - } - return static_cast(view.last); -} - -/// @brief The selected keys of the rows a table holds on pages other than the one shown, in their order: what an -/// `Extend` report keeps, since the backend holds the shown page alone. -/// @param view The table's rows and page. -/// @param selection The selection, a list of keys. -/// @param rowKey A row's key. -/// @return The keys. -[[nodiscard]] inline ValueList selectedOffPage(TableView const& view, Value const& selection, - std::function const& rowKey) { - std::unordered_set onPage; - std::unordered_set offPage; - for (std::size_t index = 0; index < view.rows.size(); ++index) { - (index >= view.first && index < view.last ? onPage : offPage).insert(rowKey(view.rows.at(index))); - } - ValueList kept; - if (ValueList const* const selected = selection.asList()) { - for (Value const& item : *selected) { - Key const key = keyOf(item); - if (offPage.contains(key) && !onPage.contains(key)) { - kept.push_back(item); - } - } - } - return kept; -} - -/// @brief The sortable column part of a table with the id @p columnId. -/// @param table The table. -/// @param columnId The column's id. -/// @return The part, or `nullptr` when no sortable column has that id. -[[nodiscard]] inline DocNode const* sortableColumn(DocNode const& table, std::string_view columnId) { - for (DocNodePtr const& column : table.partList("columns")) { - if (column->id == columnId && column->flag("sortable")) { - return column.get(); - } - } - return nullptr; -} - -/// @brief One key of a table's sort: the column part that orders the rows, and whether it is descending. -struct SortKey { - /// @brief The sortable column. - DocNode const* column = nullptr; - /// @brief Whether the key sorts descending. - bool descending = false; -}; +[[nodiscard]] MORPH_API std::int64_t intOf(Value const& value, std::int64_t fallback); -/// @brief A table's sort read as its keys: a list of `{"column", "direction"}` records naming sortable columns. -/// @param table The table. -/// @param sort The sort; `null` is the source order, as `[]` is. -/// @return The keys, most significant first; `nullopt` when @p sort is not such a list. -[[nodiscard]] inline std::optional> sortKeysOf(DocNode const& table, Value const& sort) { - std::vector keys; - if (sort.isNull()) { - return keys; - } - ValueList const* const items = sort.asList(); - if (items == nullptr) { - return std::nullopt; - } - for (Value const& item : *items) { - Value const* const column = item.field("column"); - Value const* const direction = item.field("direction"); - std::string const* const columnId = column == nullptr ? nullptr : column->asString(); - std::string const* const way = direction == nullptr ? nullptr : direction->asString(); - DocNode const* const part = columnId == nullptr ? nullptr : sortableColumn(table, *columnId); - if (part == nullptr || way == nullptr || (*way != "asc" && *way != "desc")) { - return std::nullopt; - } - keys.push_back(SortKey{.column = part, .descending = *way == "desc"}); - } - return keys; -} +/// @brief A tone by its exact name, the strict reading of a value's evaluation: a table row's and a key-value item's +/// tone, which unlike `toneOf` takes no alias, so a misspelt name can be reported. +/// @param value `neutral`, `info`, `ok`, `warn` or `err`; `null` is `Neutral`. +/// @return The tone; `nullopt` for anything else. +[[nodiscard]] MORPH_API std::optional toneNamed(Value const& value); -inline void ScreenCore::groupRows(ElementState const& element, Bindings const* bindings, TableView& view) { - auto const parts = element.node->partList("group"); - if (parts.empty()) { - return; - } - ExprPtr const groupBy = parts.front()->prop("by"); - RtScope const& scope = *element.scope; - ScopeEnv const tableEnv{scope, bindings}; - Evaluator runs{tableEnv}; - // A heading's key is its run's key and its ordinal among the runs with an equal key, since adjacent grouping - // can give two runs one key (samples A, B, A); the ordinal stays put across a sort, which moves no run. - std::map> ordinals; - Value key; - ValueList run; - auto const close = [&] { - std::string const json = canonicalJson(key); - Value const record = runRecord(key, std::exchange(run, {})); - ValueRecord entry = *record.asRecord(); - entry.insert_or_assign(std::string{kGroupHeadingField}, - Value{"\x1Fgroup:" + json + ":" + std::to_string(ordinals[json]++)}); - view.runs.emplace_back(std::move(entry)); - }; - for (Value const& row : view.rows) { - Value value = evaluate(*groupBy, ScopeEnv{scope, bindings, &row}); - if (!run.empty() && !runs.sameRun(key, value)) { - close(); - } - if (run.empty()) { - key = std::move(value); - } - run.push_back(row); - view.runOf.push_back(view.runs.size()); - } - if (!run.empty()) { - close(); - } -} - -inline void ScreenCore::sortedRows(ElementState const& element, Bindings const* bindings, TableView& view) { - DocNode const& node = *element.node; - RtScope const& scope = *element.scope; - Value const source = bindings == nullptr ? element.rows->get() : evalIn(scope, bindings, node.prop("rows")); - ValueList const* const items = source.asList(); - if (items == nullptr) { - return; - } - view.rows.assign(items->begin(), items->end()); - groupRows(element, bindings, view); - Value const sort = tableSort(element); - std::optional> const keys = sortKeysOf(node, sort); - std::string const sortPath = pointerAppend(node.path, "sort"); - if (!keys) { - report( - sortPath, - "sort is " + canonicalJson(sort) + - R"(; a table's sort is a list of {"column": , "direction": "asc" or "desc"})"); - return; - } - if (keys->empty()) { - return; - } - // Each row's keys are read once, then the rows are ordered by them: a change to the sort, the rows, or anything - // a `sortBy` reads sorts again. A grouped table orders by the group first, so every group keeps its place in - // the source order and its rows are sorted within it. - bool const grouped = !view.runOf.empty(); - std::vector> rowKeys; - rowKeys.reserve(view.rows.size()); - for (std::size_t index = 0; index < view.rows.size(); ++index) { - Value const& row = view.rows.at(index); - ScopeEnv const env{scope, bindings, &row}; - std::vector values; - values.reserve(keys->size() + 1); - if (grouped) { - values.emplace_back(static_cast(view.runOf.at(index))); - } - for (SortKey const& key : *keys) { - if (ExprPtr const sortBy = key.column->prop("sortBy")) { - values.push_back(evaluate(*sortBy, env)); - } else { - Value const* const field = row.field(key.column->id); - values.push_back(field == nullptr ? Value{} : *field); - } - } - rowKeys.push_back(std::move(values)); - } - std::vector descending; - descending.reserve(keys->size() + 1); - if (grouped) { - descending.push_back(false); - } - for (SortKey const& key : *keys) { - descending.push_back(key.descending); - } - ScopeEnv const env{scope, bindings}; - std::optional> const order = Evaluator{env}.sortRows(rowKeys, descending); - if (!order) { - report(sortPath, "the rows' values for the sort are not of one comparable kind; the rows keep their order"); - return; - } - std::vector sorted; - std::vector runOf; - sorted.reserve(view.rows.size()); - for (std::size_t const index : *order) { - sorted.push_back(view.rows.at(index)); - if (grouped) { - runOf.push_back(view.runOf.at(index)); - } - } - view.rows = std::move(sorted); - view.runOf = std::move(runOf); -} - -inline TableView ScreenCore::tableView(ElementState const& element, Bindings const* bindings) { - DocNode const& node = *element.node; - RtScope const& scope = *element.scope; - TableView view; - sortedRows(element, bindings, view); - view.last = view.rows.size(); - ExprPtr const sizeExpr = node.prop("pageSize"); - if (!sizeExpr) { - return view; - } - // A `pageSize` of `null` does not page; one that is no positive integer is reported and does not page either. - Value const size = evalIn(scope, bindings, sizeExpr); - std::int64_t const* const perPage = size.asInt(); - if (size.isNull() || perPage == nullptr || *perPage < 1) { - if (!size.isNull()) { - report(pointerAppend(node.path, "pageSize"), - "pageSize is " + canonicalJson(size) + "; a page holds a positive whole number of rows"); - } - return view; - } - // A `page` of `null` is the first; one that is negative or not a whole number is reported and shows the first. - // One past the last is the last: a filter that shrinks the rows under the user is normal, not an error. - std::int64_t asked = 0; - if (ExprPtr const pageExpr = node.prop("page")) { - Value const page = evalIn(scope, bindings, pageExpr); - std::int64_t const* const index = page.asInt(); - if (index != nullptr && *index >= 0) { - asked = *index; - } else if (!page.isNull()) { - report(pointerAppend(node.path, "page"), - "page is " + canonicalJson(page) + "; a page is a whole number from 0"); - } - } - auto const total = static_cast(view.rows.size()); - view.pageCount = std::max(1, (total + *perPage - 1) / *perPage); - view.page = std::min(asked, view.pageCount - 1); - view.first = static_cast(std::min(total, view.page * *perPage)); - view.last = static_cast(std::min(total, (view.page + 1) * *perPage)); - return view; -} - -/// @brief A table's selection as its element value reads it: the bound `selection` when the key binds one, else -/// the table's own. A bound value that is not a list (`null` while state starts empty) selects nothing. -/// @param element The table's element. -/// @return A list of keys. Tracked. -[[nodiscard]] inline Value tableSelection(ElementState const& element) { - if (element.bound == nullptr) { - return element.selection.get(); - } - Value const bound = element.bound->get(); - return bound.asList() != nullptr ? bound : Value{ValueList{}}; -} - -/// @brief A JSON text as a document value; `null` when it is not JSON or holds what a value cannot (a fraction). -/// @param text The JSON text. -/// @return The value. -[[nodiscard]] inline Value jsonTextValue(std::string_view text) { - auto const json = parseJson(text); - if (!json) { - return Value{}; - } - auto value = valueFromJson(*json); - return value ? *std::move(value) : Value{}; -} - -/// @brief One field of a form as a record: `value` (the encoded value, `null` while blank or invalid), `draft` (the -/// text), `valid`, `required`, `visible`, `readonly` and `errors`. Tracked. -/// @param field The field. -/// @return The record. -[[nodiscard]] inline Value formFieldValue(forms::FieldState const& field) { - ValueRecord record; - forms::Encoding const& encoding = field.encoded().get(); - Value value; - if (encoding.has_value() && encoding->has_value()) { - value = (*encoding)->value.isNull() ? jsonTextValue((*encoding)->json) : (*encoding)->value; - } - std::optional const& error = field.error().get(); - record.insert_or_assign("value", std::move(value)); - record.insert_or_assign("draft", Value{field.spec().kind == forms::FieldKind::Object || - field.spec().kind == forms::FieldKind::ObjectArray - ? std::string{} - : field.draft()}); - record.insert_or_assign("valid", Value{!error.has_value()}); - record.insert_or_assign("required", Value{field.required().get()}); - record.insert_or_assign("visible", Value{field.visible().get()}); - record.insert_or_assign("readonly", Value{field.readonly().get()}); - record.insert_or_assign("errors", - error.has_value() ? Value{ValueList{Value{error->message}}} : Value{ValueList{}}); - return Value{std::move(record)}; -} - -/// @brief A form's element values (spec 5 §6): `ready`, `body` (the record the form would submit, `null` while not -/// ready), `submitted` (whether a submission was sent), `pending`, and each field by its wire name. Tracked. -/// @param element The form's element. -/// @param name The value's name. -/// @return The value; `null` for a name the form does not have, or a form without a session. -[[nodiscard]] inline Value formValue(ElementState const& element, std::string_view name) { - forms::FormSession const* const form = element.form.get(); - if (form == nullptr) { - return Value{}; - } - if (name == "ready") { - return form->ready(); - } - if (name == "body") { - std::optional const body = form->body(); - return body.has_value() ? jsonTextValue(*body) : Value{}; - } - if (name == "submitted") { - return form->submitAttempts() > 0; - } - if (name == "pending") { - return form->pending(); - } - for (auto const& field : form->fields()) { - if (field->spec().name == name) { - return formFieldValue(*field); - } - } - return Value{}; -} - -inline Value ScreenCore::inputValue(ElementState const& element) const { - std::string_view const kind = element.node->kind; - if (kind == "checkbox") { - return elementValue(element, "checked"); - } - if (kind == "select") { - return elementValue(element, "selected"); - } - return elementValue(element, "value"); -} - -// NOLINTNEXTLINE(misc-no-recursion,readability-function-cognitive-complexity): one case per element value. -inline Value ScreenCore::elementValue(ElementState const& element, std::string_view name) const { - DocNode const& node = *element.node; - RtScope const& scope = *element.scope; - std::string_view const kind = node.kind; - auto flagOf = [&](std::string_view key, bool fallback) -> Value { - ExprPtr const expr = node.prop(key); - if (!expr) { - return fallback; - } - Value const value = evalIn(scope, nullptr, expr); - bool const* const flag = value.asBool(); - return flag != nullptr && *flag; - }; - auto errors = [&]() -> Value { return element.errors->get(); }; - auto count = [](Value const& list) -> Value { - ValueList const* const items = list.asList(); - return static_cast(items == nullptr ? 0 : items->size()); - }; - if (name == "visible" || name == "enabled") { - return flagOf(name, true); - } - if (name == "errors") { - return errors(); - } - if (name == "valid") { - Value const current = errors(); - ValueList const* const items = current.asList(); - return items == nullptr || items->empty(); - } - if (name == "shownErrors") { - RtScope const& policy = scope.policyScope(); - std::string const mode = policy.showErrors.empty() ? _doc->showErrors : policy.showErrors; - bool const submittedNow = policy.submitted != nullptr && policy.submitted->get(); - if (mode == "always" || (mode == "submit" && submittedNow) || - (mode != "submit" && (submittedNow || element.touched.get() || touchedWithin(element)))) { - return errors(); - } - return Value{ValueList{}}; - } - if (kind == "dialog" || kind == "drawer") { - if (name == "open") { - return node.prop("open") ? flagOf("open", false) : Value{element.open.get()}; - } - if (name == "ready") { - RtScope const* const inner = element.inner.get(); - return inner != nullptr && inner->ready(); - } - if (name == "submitted") { - return element.submitted.get(); - } - return Value{}; - } - if (kind == "table") { - if (name == "selection") { - return tableSelection(element); - } - if (name == "activeKey") { - return element.activeKey.get(); - } - if (name == "selectedCount") { - return count(tableSelection(element)); - } - if (name == "sort") { - return tableSort(element); - } - if (name == "viewCount" || name == "page" || name == "pageCount" || name == "pageFirst" || - name == "pageLast") { - return tablePageValue(element, name); - } - if (name == "sourceCount") { - return element.rows == nullptr ? Value{std::int64_t{0}} : count(element.rows->get()); - } - ExprPtr const rows = node.prop("rows"); - if ((name == "pending" || name == "error") && rows && rows->kind == ExprKind::Query) { - ScopeEnv const env{scope, nullptr}; - return env.control(name == "pending" ? ExprKind::Pending : ExprKind::Error, rows->name); - } - return name == "pending" ? Value{false} : Value{}; - } - if (kind == "tabs") { - // The shown tab's id: the bound one, else the user's own pick, else the first tab's. - ExprPtr const selected = node.prop("selected"); - if (name != "selected") { - return Value{}; - } - if (selected && (selected->kind != ExprKind::Literal || !selected->literal.isNull())) { - return evalIn(scope, nullptr, selected); - } - if (Value picked = element.draft.get(); !picked.isNull()) { - return picked; - } - auto const tabs = node.partList("tabs"); - return tabs.empty() || tabs.front()->id.empty() ? Value{} : Value{tabs.front()->id}; - } - if (kind == "form") { - return formValue(element, name); - } - if (name == "draft") { - return element.draft.get(); - } - if (name == "dirty") { - return element.edited.get(); - } - if (name == "focused") { - return element.focused.get(); - } - if (name == "touched") { - return element.touched.get(); - } - if (name == "checked" || name == "selected") { - return element.bound != nullptr ? element.bound->get() : element.draft.get(); - } - if (name == "selectedOption") { - Value const selected = elementValue(element, "selected"); - ValueList const* const options = element.rows == nullptr ? nullptr : element.rows->get().asList(); - if (options != nullptr && !selected.isNull()) { - for (Value const& option : *options) { - if (optionKey(option) == selected) { - return option; - } - } - } - return Value{}; - } - if (name == "value") { - if (element.bound != nullptr) { - return element.bound->get(); - } - return element.committed.get(); - } - return Value{}; -} - -inline bool ScreenCore::touchedWithin(ElementState const& element) { - if (element.node->kind != "group") { - return false; - } - std::string const inside = element.node->path + "/"; - return std::ranges::any_of(element.scope->elements, [&inside](std::unique_ptr const& other) { - return other->node->path.starts_with(inside) && other->touched.get(); - }); -} - -// --- Commands -------------------------------------------------------------------------------------------------- - -// NOLINTBEGIN(misc-no-recursion): command lists nest -inline void ScreenCore::runList(Commands const& commands, CommandCtx const& ctx, Done done) { - if (!done) { - done = [](bool) {}; - } - if (commands.empty()) { - done(true); - return; - } - struct Join { - std::size_t left = 0; - bool ok = true; - Done done; - }; - if (recording) { - logList(commands); - } - auto join = std::make_shared(Join{.left = commands.size() + 1, .ok = true, .done = std::move(done)}); - auto finish = [join](bool succeeded) { - join->ok = join->ok && succeeded; - if (--join->left == 0) { - join->done(join->ok); - } - }; - for (Command const& command : commands) { - runOne(command, ctx, finish); - } - finish(true); -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per command of ui/1. -inline void ScreenCore::runOne(Command const& command, CommandCtx const& ctx, Done done) { - if (!done) { - done = [](bool) {}; - } - RtScope const& scope = *ctx.scope; - auto eval = [&](ExprPtr const& expr) { return evalIn(scope, ctx.bindings.get(), expr); }; - auto finish = [&done](bool succeeded) { done(succeeded); }; - switch (command.kind) { - case CommandKind::Set: - runSet(command, ctx, done); - return; - case CommandKind::Reset: - runReset(command, ctx, done); - return; - case CommandKind::Run: - runMutation(command, ctx, std::move(done)); - return; - case CommandKind::Refetch: { - // A loaded document's `refetch` names a query in scope (`loadDocument` checks it), as `run` names a - // mutation and `open` a dialog. - scope.find(command.target)->query->refetch(); - finish(true); - return; - } - case CommandKind::Open: - case CommandKind::Close: { - ElementState* target = nullptr; - if (command.kind == CommandKind::Close && command.target == "self") { - // `self` is the innermost dialog or drawer whose content holds the command, found lexically. A - // component's fallback scope has no parent, so the walk stops at its boundary as its names do. - RtScope const* walk = &scope; - while (walk->owner == nullptr && walk->parent) { - walk = walk->parent.get(); - } - target = walk->owner; - if (target == nullptr && walk != rootScope.lock().get()) { - report(command.path, "`close: self` inside a component names no dialog or drawer"); - finish(false); - return; - } - if (target == nullptr) { - finish((host != nullptr && host->closeSelf(_doc->id, std::nullopt)) || - unsupported(command, "`close: self`")); - return; - } - } else { - target = scope.find(command.target)->element; - } - ElementState& element = *target; - if (element.node->prop("open")) { - report(command.path, "the dialog's `open` is bound to an expression"); - finish(false); - return; - } - bool const opening = command.kind == CommandKind::Open; - if (opening && !element.open.peek()) { - element.submitted.set(false); - } - session.noteWrite(); - element.open.set(opening); - finish(true); - return; - } - case CommandKind::Navigate: { - NavigateRequest const request{.screen = command.target, - .route = eval(command.extra), - .params = eval(command.value), - .as = command.option, - .call = false}; - if (host == nullptr) { - finish(unsupported(command, "`navigate`")); - return; - } - // A navigation without `onResult` and `onCancel` asks for no answer, so it files no call: the screen it - // opens answers nobody, and its `return` is the application's. - if (command.commands.empty() && command.alternative.empty()) { - finish(host->navigate(request, {}, {}) || unsupported(command, "`navigate`")); - return; - } - std::weak_ptr const weak = ctx.scope; - CommandCtx const kept = detached(ctx); - auto onResult = [this, weak, kept, list = &command.commands](Value const& result) { - if (auto const held = weak.lock()) { - auto bindings = std::make_shared(*kept.bindings); - bindings->push_back(Binding{.name = "event", .read = [result] { return result; }}); - CommandCtx const next{.scope = held, - .bindings = bindings, - .cancelClose = kept.cancelClose, - .boundary = kept.boundary}; - runtime().batch([&] { runList(*list, next, {}); }); - } - }; - auto onCancel = [this, weak, kept, list = &command.alternative] { - if (auto const held = weak.lock()) { - CommandCtx next = kept; - next.scope = held; - runtime().batch([&] { runList(*list, next, {}); }); - } - }; - finish(host->navigate(request, std::move(onResult), std::move(onCancel)) || - unsupported(command, "`navigate`")); - return; - } - case CommandKind::Return: - finish(host != nullptr && host->closeSelf(_doc->id, eval(command.value)) - ? true - : unsupported(command, "`return`")); - return; - case CommandKind::Focus: - if (focusTarget(command, scope, ctx.bindings.get())) { - finish(true); - return; - } - report(command.path, "`" + command.target + "` is not mounted"); - finish(false); - return; - case CommandKind::Host: - runHostCommand(command, ctx, done); - return; - case CommandKind::SwitchBackend: { - std::weak_ptr const weak = ctx.scope; - auto committed = [this, weak, target = command.target, path = command.path, - done](std::expected const& outcome) { - if (!weak.lock()) { - return; - } - if (!outcome) { - report(path, "backendSwitchFailed: " + outcome.error()); - done(false); - return; - } - session.backendChanged(target); - done(true); - }; - if (host != nullptr && host->switchBackend(command.target, std::move(committed))) { - return; - } - report(command.path, "backend `" + command.target + "` is not listed"); - finish(false); - return; - } - case CommandKind::ResetPrefs: { - ValueRecord prefsNow = prefs.peek(); - if (command.target == "all") { - prefsNow = prefDefaults; - } else if (auto const found = prefDefaults.find(command.target); found != prefDefaults.end()) { - prefsNow.insert_or_assign(command.target, found->second); - } - prefs.set(std::move(prefsNow)); - if (host != nullptr) { - host->resetPrefs(_doc->id, command.target); - } - finish(true); - return; - } - case CommandKind::SetLocale: - session.setLocale(command.target); - if (host != nullptr) { - host->setLocale(command.target); - } - finish(true); - return; - case CommandKind::SetContext: { - // The shell checks the value against the switcher's options; with no switcher it is unsupported. - Value const requested = eval(command.value); - if (session.requestContext(requested)) { - finish(true); - } else { - report(command.path, - "`setContext` was refused: " + std::string{session.can("context") - ? "the value is not one of the scope's options" - : "no scope switcher is declared"}); - finish(false); - } - return; - } - case CommandKind::Notify: { - std::string const text = textOf(eval(command.value), ctx.scope->formatting()); - finish(host != nullptr && host->notify(text, command.option) ? true : unsupported(command, "`notify`")); - return; - } - case CommandKind::Seq: { - // A step that waits for a reply keeps the rest of the sequence in that reply's handler, which the - // dispatcher may hold past the screen: the sequence holds its scope weakly and stops once it is gone. - CommandCtx const inner = detached(CommandCtx{.scope = nullptr, - .bindings = std::make_shared(*ctx.bindings), - .cancelClose = ctx.cancelClose, - .boundary = ctx.boundary}); - std::weak_ptr const weak = ctx.scope; - auto step = std::make_shared>(); - *step = [this, inner, weak, list = &command.commands, done = std::move(done), - weakStep = std::weak_ptr>{step}](std::size_t index) { - auto const held = weak.lock(); - if (index == list->size() || !held) { - done(held != nullptr); - return; - } - auto const self = weakStep.lock(); - CommandCtx current = inner; - current.scope = held; - runOne(list->at(index), current, [self, index, done](bool succeeded) { - if (!succeeded) { - done(false); - return; - } - (*self)(index + 1); - }); - }; - (*step)(0); - return; - } - case CommandKind::All: { - CommandCtx const inner{.scope = ctx.scope, - .bindings = std::make_shared(*ctx.bindings), - .cancelClose = ctx.cancelClose, - .boundary = ctx.boundary}; - runList(command.commands, inner, std::move(done)); - return; - } - case CommandKind::If: { - Value const condition = eval(command.value); - bool const* const flag = condition.asBool(); - if (flag == nullptr) { - finish(true); - return; - } - runList(*flag ? command.commands : command.alternative, ctx, std::move(done)); - return; - } - case CommandKind::CancelClose: - *ctx.cancelClose = true; - finish(true); - return; - case CommandKind::Retry: - // `retry` is valid only inside a boundary's `error`, which is lowered with its boundary. - for (QueryRuntime* const query : ctx.boundary->queries) { - if (!runtime().untracked([&] { return query->error(); }).isNull()) { - query->refetch(); - } - } - finish(true); - return; - case CommandKind::SignIn: { - NameRef const* const found = scope.find(command.target); - Value const reply = found != nullptr && found->category == NameCategory::Mutation - ? runtime().untracked([&] { return found->mutation->result(); }) - : Value{}; - session.clear(); - finish(host != nullptr && host->signIn(reply) ? true : unsupported(command, "`signIn`")); - return; - } - case CommandKind::SignOut: - session.clear(); - if (host != nullptr) { - host->signOut(); - } - finish(true); - return; - case CommandKind::Upload: - case CommandKind::Download: - default: - runTransfer(command, ctx, std::move(done)); - return; - } -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): a single run, or a run per list item. -inline void ScreenCore::runMutation(Command const& command, CommandCtx const& ctx, Done done) const { - RtScope const& scope = *ctx.scope; - MutationRuntime& mutation = *scope.find(command.target)->mutation; - RtScope const& policy = scope.policyScope(); - if (policy.submitted != nullptr) { - policy.submitted->set(true); - } - if (policy.owner != nullptr && !runtime().untracked([&] { return policy.ready(); })) { - done(false); - return; - } - RtScope const& declaring = *[&]() -> RtScope const* { - for (RtScope const* candidate = &scope; candidate != nullptr; candidate = candidate->parent.get()) { - if (candidate->names.contains(command.target)) { - return candidate; - } - } - return &scope; - }(); - auto bodyFor = [&](Bindings const& bindings) { - if (command.value) { - return evalIn(scope, &bindings, command.value); - } - if (mutation.decl().body) { - return evalIn(declaring, &bindings, mutation.decl().body); - } - return Value{ValueRecord{}}; - }; - if (!command.extra) { - Value body = bodyFor(*ctx.bindings); - mutation.run(std::move(body), std::make_shared(*ctx.bindings), - [bindings = ctx.bindings, bindAs = command.binding, done = std::move(done)](bool succeeded, - Value const& reply) { - if (succeeded && !bindAs.empty()) { - bindings->push_back(Binding{.name = bindAs, .read = [reply] { return reply; }}); - } - done(succeeded); - }); - return; - } - Value const each = evalIn(scope, ctx.bindings.get(), command.extra); - ValueList const items = each.asList() == nullptr ? ValueList{} : *each.asList(); - if (items.empty()) { - done(true); - return; - } - struct Each { - std::size_t left = 0; - bool ok = true; - Done done; - }; - auto state = std::make_shared(Each{.left = items.size(), .ok = true, .done = std::move(done)}); - std::vector bodies; - std::vector> bound; - for (Value const& item : items) { - Bindings bindings = *ctx.bindings; - if (!command.binding.empty()) { - bindings.push_back(Binding{.name = command.binding, .read = [item] { return item; }}); - } - bodies.push_back(bodyFor(bindings)); - bound.push_back(std::make_shared(std::move(bindings))); - } - if (mutation.decl().concurrency != Concurrency::Exclusive) { - for (std::size_t index = 0; index < bodies.size(); ++index) { - mutation.run(bodies.at(index), bound.at(index), [state](bool succeeded, Value const&) { - state->ok = state->ok && succeeded; - if (--state->left == 0) { - state->done(state->ok); - } - }); - } - return; - } - // An exclusive mutation refuses a run while another is in flight, so its elements go one after another. - auto step = std::make_shared>(); - *step = [&mutation, bodies, bound, state, - weakStep = std::weak_ptr>{step}](std::size_t index) { - if (index == bodies.size()) { - state->done(state->ok); - return; - } - auto const self = weakStep.lock(); - mutation.run(bodies.at(index), bound.at(index), [self, state, index](bool succeeded, Value const&) { - if (!succeeded) { - state->done(false); - return; - } - (*self)(index + 1); - }); - }; - (*step)(0); -} - -// NOLINTEND(misc-no-recursion) -inline void ScreenCore::writeSlot(StateSlot& slot, std::span within, Value value, - Command const& command, Done const& done) { - slot.scope->core.initState(*slot.scope, slot); - Type const& type = slot.decl->type; - if (within.empty() && !type.isAny() && !type.admits(value)) { - report(command.path, "`set` writes a value that is not a " + type.name()); - done(false); - return; - } - Value next = withPath(slot.value->peek(), within, std::move(value)); - session.noteWrite(); - slot.value->set(std::move(next)); - done(true); -} - -inline void ScreenCore::runSetApp(Command const& command, std::span rest, Value value, - Done const& done) { - if (RtScope const* const app = session.appScope(); app != nullptr && !rest.empty()) { - NameRef const* const named = app->find(rest.front()); - if (named != nullptr && named->category == NameCategory::State) { - writeSlot(*named->state, rest.subspan(1), std::move(value), command, done); - return; - } - report(command.path, "`app." + rest.front() + "` is not state of the app document"); - done(false); - return; - } - std::string name; - for (std::string const& segment : rest) { - name += name.empty() ? segment : "." + segment; - } - done(host != nullptr && host->setAppValue(name, value) ? true : unsupported(command, "`set` of `app`")); -} - -inline void ScreenCore::runSet(Command const& command, CommandCtx const& ctx, Done const& done) { - RtScope const& scope = *ctx.scope; - auto path = splitPath(command.target); - if (!path || path->empty()) { - done(false); - return; - } - std::string const head = path->front(); - std::span const rest = std::span{*path}.subspan(1); - Value value = evalIn(scope, ctx.bindings.get(), command.value); - if (head == "app") { - runSetApp(command, rest, std::move(value), done); - return; - } - NameRef const* const found = scope.find(head); - if (found != nullptr && found->category == NameCategory::State) { - writeSlot(*found->state, rest, std::move(value), command, done); - return; - } - if (found != nullptr && found->category == NameCategory::Element) { - ElementState& element = *found->element; - session.noteWrite(); - element.draft.set(value); - if (element.bound == nullptr) { - element.committed.set(std::move(value)); - } - done(true); - return; - } - report(command.path, "`set` names nothing writable here"); - done(false); -} - -inline void ScreenCore::runReset(Command const& command, CommandCtx const& ctx, Done const& done) { - RtScope const& scope = *ctx.scope; - NameRef const* const found = scope.find(command.target); - auto resetStates = [this](RtScope const& owner) { - for (auto const& slot : owner.states) { - if (slot->value) { - Value init = runtime().untracked([&] { return evalIn(owner, nullptr, slot->decl->init); }); - slot->value->set(std::move(init)); - } - } - for (auto const& element : owner.elements) { - element->draft.set(element->bound != nullptr ? runtime().untracked([&] { return element->bound->get(); }) - : Value{}); - element->committed.set(Value{}); - element->edited.set(false); - element->touched.set(false); - } - }; - bool known = true; - session.noteWrite(); - if (found != nullptr && found->category == NameCategory::State) { - StateSlot& slot = *found->state; - initState(*slot.scope, slot); - slot.value->set(runtime().untracked([&] { return evalIn(*slot.scope, nullptr, slot.decl->init); })); - } else if (found != nullptr && found->category == NameCategory::Element) { - ElementState& element = *found->element; - element.submitted.set(false); - if (RtScope const* const inner = element.inner.peek()) { - resetStates(*inner); - } - } else { - report(command.path, "`reset` names no state or dialog here"); - known = false; - } - done(known); -} - -inline void ScreenCore::runHostCommand(Command const& command, CommandCtx const& ctx, Done const& done) { - Value const args = evalIn(*ctx.scope, ctx.bindings.get(), command.value); - if (auto const& run = session.hostCommandRunner()) { - HostCommandResult const result = run(command.target, args); - if (result.kind == HostCommandResult::Kind::Missing) { - report(command.path, "host command `" + command.target + "` is missing"); - } else if (result.kind == HostCommandResult::Kind::Refused) { - report(command.path, result.reason); - } - done(result.kind == HostCommandResult::Kind::Ran); - return; - } - bool const known = host != nullptr && host->hostCommand(command.target, args); - if (!known) { - report(command.path, "host command `" + command.target + "` is missing"); - } - done(known); -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): a download and an upload, each settled. -/// @brief A transfer's share of its screen's pending count. -/// -/// A transfer is pending from the host accepting it to its settle: its completion carries on the command list that -/// started it, which the close protocol and save-and-close wait for. The count is taken once the host accepts, so a -/// refused transfer never counts, and a host that settles before it returns leaves nothing taken. It is given back -/// once, also when the transfer settles after its scope is gone, but not after the screen itself is gone, since the -/// count went with it. -class TransferHold { -public: - /// @brief A hold that counts nothing yet. - /// @param core The screen whose count it moves. - /// @param alive Expires with the screen. - TransferHold(ScreenCore& core, std::weak_ptr alive) : _core{&core}, _alive{std::move(alive)} {} - - /// @brief Counts the transfer, unless it has already settled. - void take() { - if (_state == State::NotTaken) { - _state = State::Taken; - _core->addPending(1); - } - } - - /// @brief Gives the count back, if one was taken and the screen is still there; the transfer counts no more. - void release() { - if (_state == State::Taken && !_alive.expired()) { - _core->addPending(-1); - } - _state = State::Released; - } - -private: - enum class State : std::uint8_t { NotTaken, Taken, Released }; - - ScreenCore* _core; - std::weak_ptr _alive; - State _state = State::NotTaken; -}; - -/// @brief Bytes as base64 (RFC 4648, with padding): how a document carries an inline file. -/// @param bytes The bytes. -/// @return The text. -[[nodiscard]] inline std::string base64Encode(std::string_view bytes) { - static constexpr std::string_view kAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"; - std::string out; - out.reserve(((bytes.size() + 2) / 3) * 4); - for (std::size_t index = 0; index < bytes.size(); index += 3) { - std::size_t const left = std::min(3, bytes.size() - index); - std::uint32_t group = 0; - for (std::size_t offset = 0; offset < 3; ++offset) { - group <<= 8U; - if (offset < left) { - group |= static_cast(bytes.at(index + offset)); - } - } - for (std::size_t digit = 0; digit < 4; ++digit) { - out.push_back(digit <= left ? kAlphabet.at((group >> (18U - (6U * digit))) & 0x3FU) : '='); - } - } - return out; -} - -/// @brief Base64 text as bytes (RFC 4648, with or without padding). -/// @param text The text. -/// @return The bytes, or `std::nullopt` for text that is not base64. -[[nodiscard]] inline std::optional base64Decode(std::string_view text) { - while (!text.empty() && text.back() == '=') { - text.remove_suffix(1); - } - if (text.size() % 4 == 1) { - return std::nullopt; - } - auto digitOf = [](char chr) -> int { - if (chr >= 'A' && chr <= 'Z') { - return chr - 'A'; - } - if (chr >= 'a' && chr <= 'z') { - return chr - 'a' + 26; - } - if (chr >= '0' && chr <= '9') { - return chr - '0' + 52; - } - if (chr == '+') { - return 62; - } - return chr == '/' ? 63 : -1; - }; - std::string out; - out.reserve((text.size() * 3) / 4); - std::uint32_t group = 0; - int bits = 0; - for (char const chr : text) { - int const digit = digitOf(chr); - if (digit < 0) { - return std::nullopt; - } - group = (group << 6U) | static_cast(digit); - bits += 6; - if (bits >= 8) { - bits -= 8; - out.push_back(static_cast((group >> static_cast(bits)) & 0xFFU)); - } - } - return out; -} - -/// @brief How many bytes base64 text decodes to, read from its length alone. -/// @param text The text. -/// @return The byte count. -[[nodiscard]] inline std::size_t base64Size(std::string_view text) { - while (!text.empty() && text.back() == '=') { - text.remove_suffix(1); - } - return (text.size() * 3) / 4; -} - -/// @brief A byte count as a person reads it: `512 bytes`, `2.4 KiB`, `1 MiB`. -/// @param bytes The count. -/// @return The text. -[[nodiscard]] inline std::string sizeText(std::size_t bytes) { - constexpr std::size_t kKiB = 1024; - if (bytes < kKiB) { - return std::to_string(bytes) + " bytes"; - } - bool const mebi = bytes >= kKiB * kKiB; - std::size_t const unit = mebi ? kKiB * kKiB : kKiB; - // One decimal place, rounded half up, and none when it is zero. - std::size_t const tenths = ((bytes * 10) + (unit / 2)) / unit; - std::string text = std::to_string(tenths / 10); - if (tenths % 10 != 0) { - text += "." + std::to_string(tenths % 10); - } - return text + (mebi ? " MiB" : " KiB"); -} +/// @brief A span list's runs: each element a record `{text, strong?, mono?, tone?}`, or a plain run of any other value +/// but a list or `null`. A run's text is shown as `textOf` shows any value, so a computed number is a run of +/// its digits, and a flag is set only by `true`. +/// @param value The list; `null` is no runs. +/// @param format How a run's value is written. +/// @param dropped Set when the value is not a list, or an element is a list, `null`, or a record without `text`; +/// such an element is left out. +/// @param badTone Set, when given, when a run's `tone` is none of the tone names; the run is kept, untoned. +/// @return The runs, in order. +[[nodiscard]] MORPH_API std::vector spansOf(Value const& value, FormatContext const& format, bool& dropped, + bool* badTone = nullptr); -/// @brief A document's inline file content as bytes: base64 text, or a list of integers 0 to 255. +/// @brief A sizing by its document form: `"content"`, `{"fixed": n}`, `{"stretch": w}` or `{"percent": n}`. /// @param value The value. -/// @return The bytes, or why the value is neither. -[[nodiscard]] inline std::expected inlineBytes(Value const& value) { - if (std::string const* const text = value.asString()) { - if (std::optional bytes = base64Decode(*text)) { - return *std::move(bytes); - } - return std::unexpected(std::string{"the text is not base64"}); - } - if (ValueList const* const list = value.asList()) { - std::string bytes; - bytes.reserve(list->size()); - for (Value const& item : *list) { - std::int64_t const* const byte = item.asInt(); - if (byte == nullptr || *byte < 0 || *byte > 255) { - return std::unexpected(std::string{"a byte list holds integers 0 to 255"}); - } - bytes.push_back(static_cast(static_cast(*byte))); - } - return bytes; - } - return std::unexpected(std::string{"inline bytes are base64 text or a list of bytes"}); -} - -inline void ScreenCore::runTransfer(Command const& command, CommandCtx const& ctx, Done done) { - Value const file = evalIn(*ctx.scope, ctx.bindings.get(), command.value); - if (command.kind == CommandKind::Download) { - runDownload(command, ctx, file, std::move(done)); - } else { - runUpload(command, ctx, file, std::move(done)); - } -} - -inline void ScreenCore::runDownload(Command const& command, CommandCtx const& ctx, Value const& file, Done done) { - Value const name = evalIn(*ctx.scope, ctx.bindings.get(), command.extra); - auto const hold = std::make_shared(*this, _alive); - auto const settled = [this, weak = std::weak_ptr{ctx.scope}, target = command.target, - preview = command.option == "preview", done, - hold](std::expected const& reply) { - auto const held = weak.lock(); - if (!held) { - hold->release(); - return; - } - runtime().batch([&] { - bool const succeeded = reply.has_value(); - NameRef const* const found = succeeded && preview ? held->find(target) : nullptr; - if (found != nullptr && found->category == NameCategory::State) { - initState(*found->state->scope, *found->state); - session.noteWrite(); - found->state->value->set(*reply); - } - done(succeeded); - hold->release(); - }); - }; - if (command.bytes) { - std::optional const inlined = inlineDownload(command, ctx, file, name); - if (!inlined) { - done(false); - return; - } - if (host == nullptr || !host->saveFile(*inlined, command.option, settled)) { - unsupported(command, "`download`"); - done(false); - return; - } - hold->take(); - return; - } - if (host == nullptr || !host->download(file, command.option, name, settled)) { - unsupported(command, "`download`"); - done(false); - return; - } - hold->take(); -} - -// Inline bytes are checked before the host is asked: content over the cap, or that does not decode, never reaches it. -inline std::optional ScreenCore::inlineDownload( - Command const& command, CommandCtx const& ctx, - // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the command's `file` and `name`, in its order. - Value const& file, Value const& name) { - std::size_t const cap = session.options().maxInlineFileBytes; - std::size_t size = 0; - if (std::string const* const text = file.asString()) { - size = base64Size(*text); - } else if (ValueList const* const list = file.asList()) { - size = list->size(); - } - std::expected bytes = size > cap ? std::unexpected(std::string{}) : inlineBytes(file); - if (size > cap || (bytes && bytes->size() > cap)) { - report(command.path, "download: " + sizeText(bytes ? bytes->size() : size) + " is over the " + sizeText(cap) + - " inline cap; serve it through the file store"); - return std::nullopt; - } - if (!bytes) { - report(command.path, "download: " + bytes.error()); - return std::nullopt; - } - return InlineFile{ - .name = textOf(name, ctx.scope->formatting()), - .mediaType = command.mediaType - ? textOf(evalIn(*ctx.scope, ctx.bindings.get(), command.mediaType), ctx.scope->formatting()) - : std::string{}, - .bytes = *std::move(bytes)}; -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one branch per outcome an upload can have. -inline void ScreenCore::runUpload(Command const& command, CommandCtx const& ctx, Value const& file, Done done) { - RtScope const& scope = *ctx.scope; - std::weak_ptr const weak = ctx.scope; - auto const hold = std::make_shared(*this, _alive); - NameRef const* const transferName = command.transfer.empty() ? nullptr : scope.find(command.transfer); - TransferState* const transfer = - transferName != nullptr && transferName->category == NameCategory::Transfer ? transferName->transfer : nullptr; - auto const progress = [weak, transfer](Value fraction) { - if (weak.lock() && transfer != nullptr) { - transfer->progress.set(std::move(fraction)); - } - }; - // Settles with the members the mutation's body gets beside its own (the reference or the inline file), or the - // failure. - auto const settled = [this, weak, kept = detached(ctx), transfer, command = &command, done, - hold](std::expected reply) { - auto const held = weak.lock(); - if (!held) { - hold->release(); - return; - } - runtime().batch([&] { - if (transfer != nullptr) { - transfer->pending.set(false); - transfer->error.set(reply ? Value{} : Value{reply.error()}); - } - if (!reply) { - done(false); - hold->release(); - return; - } - NameRef const* const found = held->find(command->target); - // The mutation's body cannot name the reference (a body is checked where the mutation is declared), - // so the reference is added to it under `as`, `file` by default. - MutationRuntime& mutation = *found->mutation; - Value const base = evalIn(*held, kept.bindings.get(), mutation.decl().body); - ValueRecord fields = base.asRecord() == nullptr ? ValueRecord{} : *base.asRecord(); - for (auto& [member, value] : *reply) { - fields.insert_or_assign(member, std::move(value)); - } - // The run takes its own count before this one is given back, so pending never reads zero in between. - mutation.run(Value{std::move(fields)}, std::make_shared(*kept.bindings), - [done](bool succeeded, Value const&) { done(succeeded); }); - hold->release(); - }); - }; - if (host == nullptr) { - unsupported(command, "`upload`"); - done(false); - return; - } - if (transfer != nullptr) { - transfer->pending.set(true); - transfer->progress.set(Value{std::int64_t{0}}); - transfer->error.set(Value{}); - } - NameRef const* const target = scope.find(command.target); - UploadRequest request{.file = file, .modelType = {}, .action = {}}; - if (target != nullptr && target->category == NameCategory::Mutation && target->mutation != nullptr) { - request.modelType = target->mutation->typeId(); - request.action = target->mutation->decl().action; - } - std::string const member = command.binding.empty() ? std::string{"file"} : command.binding; - bool started = false; - if (command.bytes) { - std::size_t const cap = session.options().maxInlineFileBytes; - started = host->readFile( - file, cap, - [this, settled, progress, cap, member, command = &command](std::expected read) { - if (!read) { - settled(std::unexpected(read.error())); - return; - } - if (read->bytes.size() > cap) { - // The host should have refused it; the cap holds whether or not it did. - std::string why = "upload: " + sizeText(read->bytes.size()) + " is over the " + sizeText(cap) + - " inline cap; send it through the file store"; - report(command->path, why); - settled(std::unexpected(std::move(why))); - return; - } - progress(Value{std::int64_t{1}}); - ValueRecord added; - added.insert_or_assign(member, Value{base64Encode(read->bytes)}); - if (!command->nameAs.empty()) { - added.insert_or_assign(command->nameAs, Value{read->name}); - } - if (!command->typeAs.empty()) { - added.insert_or_assign(command->typeAs, Value{read->mediaType}); - } - settled(std::move(added)); - }); - } else { - started = host->uploadFor(request, progress, [settled, member](std::expected reference) { - if (!reference) { - settled(std::unexpected(reference.error())); - return; - } - ValueRecord added; - added.insert_or_assign(member, *std::move(reference)); - settled(std::move(added)); - }); - } - if (!started) { - if (transfer != nullptr) { - transfer->pending.set(false); - transfer->progress.set(Value{}); - } - unsupported(command, "`upload`"); - done(false); - return; - } - hold->take(); -} - -} // namespace detail - -namespace detail { - -// --- Lowering -------------------------------------------------------------------------------------------------- - -/// @brief A value as a `bool` property: `true` only for `true`. -/// @param value The value. -/// @param format Unused. -/// @return It. -[[nodiscard]] inline bool boolOf(Value const& value, FormatContext const& format) { - static_cast(format); - bool const* const flag = value.asBool(); - return flag != nullptr && *flag; -} - -/// @brief A value as a text property. -/// @param value The value. -/// @param format The formatting facts. -/// @return Its text. -[[nodiscard]] inline std::string stringOf(Value const& value, FormatContext const& format) { - return textOf(value, format); -} - -/// @brief A value as a custom component's text prop (spec 5 §10): an `int` or `exact` as plain decimal text, so no -/// id or amount loses precision; `json` as its JSON text; `string` as the formatted text. -/// @param value The value. -/// @param type The prop type the component declares. -/// @param format The formatting facts, for `string`. -/// @return The text. -[[nodiscard]] inline std::string componentText(Value const& value, std::string_view type, - FormatContext const& format) { - if (type == "json") { - return canonicalJson(value); - } - if (type == "int" || type == "exact") { - if (std::int64_t const* const whole = value.asInt()) { - return std::to_string(*whole); - } - // A value that cannot be rounded at its own places is written as its exact JSON, never clamped. - if (Decimal const* const number = value.asDecimal()) { - return detail::decimalText(number->value, static_cast(number->value.decimalPlaces.value)) - .value_or(canonicalJson(value)); - } - if (Quantity const* const quantity = value.asQuantity()) { - auto const text = - detail::decimalText(quantity->value, static_cast(quantity->value.decimalPlaces.value)); - return text ? *text + " " + quantity->unit : canonicalJson(value); - } - } - return textOf(value, format); -} - -/// @brief An exact rational as the nearest double, unrounded. -/// -/// `Rational::toDouble` rounds to the value's own places, which is a display reading: `29 / 100` keeps its operands' -/// 0 places and would read as 0. The view tree wants the magnitude, so the lowering reads it here. -/// @param value The rational. -/// @return Its numerator divided by its denominator. -[[nodiscard]] inline double realOf(math::Rational const& value) noexcept { - return static_cast(value.numerator) / static_cast(value.denominator); -} +/// @return The sizing. +[[nodiscard]] MORPH_API Sizing sizingOf(Value const& value); -/// @brief A value as a custom component's `number` prop: the one kind that crosses as a double. +/// @brief Whether a value is a sizing of one dimension: `"content"`, `{"fixed": n}`, `{"stretch": w}` or +/// `{"percent": n}` with n from 1 to 100. /// @param value The value. -/// @return It; zero for anything that is not a number. -[[nodiscard]] inline double componentNumber(Value const& value) { - if (std::int64_t const* const whole = value.asInt()) { - return static_cast(*whole); - } - if (Decimal const* const number = value.asDecimal()) { - return realOf(number->value); - } - if (Quantity const* const quantity = value.asQuantity()) { - return realOf(quantity->value); - } - return 0.0; -} +/// @return Whether `sizingOf` reads it as written rather than as content by default. +[[nodiscard]] MORPH_API bool isSizing(Value const& value); -/// @brief A custom component's event payload as a value: `i:` an `int`, `s:` a `string`, anything else -/// JSON text read as the event's declared type, and text that is none of those a `string`. +/// @brief A component's `change` payload as the wire value of the field it draws, read as the `value` prop's +/// declared type. /// @param payload The payload, as the backend reports it. -/// @param type The payload type the component declares; null for an undeclared event. -/// @return The value. -[[nodiscard]] inline Value componentPayload(std::string const& payload, Type const* type) { - std::string_view const text{payload}; - if (text.starts_with("i:")) { - std::int64_t whole = 0; - std::string_view const digits = text.substr(2); - char const* const last = std::to_address(digits.end()); - auto const [end, error] = std::from_chars(std::to_address(digits.begin()), last, whole); - if (error == std::errc{} && end == last) { - return Value{whole}; - } - } - if (text.starts_with("s:")) { - return Value{std::string{text.substr(2)}}; - } - if (auto json = parseJson(text); json && type != nullptr) { - if (auto value = valueFromJson(*json, *type)) { - return std::move(*value); - } - } - return Value{payload}; -} - -/// @brief A value as an integer: an `int`, or a decimal truncated toward zero. -/// @param value The value. -/// @param fallback What anything else gives. -/// @return It. -[[nodiscard]] inline std::int64_t intOf(Value const& value, std::int64_t fallback) { - if (std::int64_t const* const number = value.asInt()) { - return *number; - } - if (Decimal const* const number = value.asDecimal()) { - // Integer division truncates toward zero, and reads the exact value rather than one rounded to its places. - return number->value.numerator / number->value.denominator; - } - return fallback; -} - -/// @brief A text role by name. -/// @param name `normal`, `muted`, `heading` (or `title`), `section`, `error`, `success`, `mono`, `display`, `small`, -/// `overline`, `caption`, `label`, `headline`. -/// @return The role; `nullopt` for any other name. -[[nodiscard]] inline std::optional roleNamed(std::string_view name) { - if (name == "normal") { - return TextRole::Normal; - } - if (name == "muted") { - return TextRole::Muted; - } - if (name == "heading" || name == "title") { - return TextRole::Heading; - } - if (name == "section") { - return TextRole::Section; - } - if (name == "error") { - return TextRole::Error; - } - if (name == "success") { - return TextRole::Success; - } - if (name == "mono") { - return TextRole::Mono; - } - if (name == "display") { - return TextRole::Display; - } - if (name == "small") { - return TextRole::Small; - } - if (name == "overline") { - return TextRole::Overline; - } - if (name == "caption") { - return TextRole::Caption; - } - if (name == "label") { - return TextRole::Label; - } - if (name == "headline") { - return TextRole::Headline; - } - return std::nullopt; -} - -/// @brief What a role that names none is told: the names `roleNamed` reads. -inline constexpr std::string_view kRoleNames = - "a role is normal, muted, heading, section, error, success, mono, display, small, overline, caption, label or " - "headline"; - -/// @brief A text role by name, as `roleNamed` reads it. -/// @param value The name. -/// @param format Unused. -/// @return The role; `Normal` for any other name. -[[nodiscard]] inline TextRole roleOf(Value const& value, FormatContext const& format) { - return roleNamed(textOf(value, format)).value_or(TextRole::Normal); -} - -/// @brief A tone by name. -/// @param value `neutral`, `info`, `ok` (or `success`), `warn` (or `warning`), `err` (or `error`). -/// @param format Unused. -/// @return The tone; `Neutral` for anything else. -[[nodiscard]] inline Tone toneOf(Value const& value, FormatContext const& format) { - std::string const text = textOf(value, format); - if (text == "info") { - return Tone::Info; - } - if (text == "ok" || text == "success") { - return Tone::Ok; - } - if (text == "warn" || text == "warning") { - return Tone::Warn; - } - if (text == "err" || text == "error") { - return Tone::Err; - } - return Tone::Neutral; -} - -/// @brief A tone by its exact name, the strict reading of a value's evaluation: a table row's and a key-value item's -/// tone, which unlike `toneOf` takes no alias, so a misspelt name can be reported. -/// @param value `neutral`, `info`, `ok`, `warn` or `err`; `null` is `Neutral`. -/// @return The tone; `nullopt` for anything else. -[[nodiscard]] inline std::optional toneNamed(Value const& value) { - if (value.isNull()) { - return Tone::Neutral; - } - static constexpr std::array, 5> kTones = {{ - {"neutral", Tone::Neutral}, - {"info", Tone::Info}, - {"ok", Tone::Ok}, - {"warn", Tone::Warn}, - {"err", Tone::Err}, - }}; - if (std::string const* const text = value.asString()) { - // A loop, not std::ranges::find: an array's iterator is a pointer on some standard libraries and not on - // others, so `auto` there reads differently to each. - for (auto const& [name, tone] : kTones) { - if (name == *text) { - return tone; - } - } - } - return std::nullopt; -} - -/// @brief A span list's runs: each element a record `{text, strong?, mono?, tone?}`, or a plain run of any other value -/// but a list or `null`. A run's text is shown as `textOf` shows any value, so a computed number is a run of -/// its digits, and a flag is set only by `true`. -/// @param value The list; `null` is no runs. -/// @param format How a run's value is written. -/// @param dropped Set when the value is not a list, or an element is a list, `null`, or a record without `text`; -/// such an element is left out. -/// @param badTone Set, when given, when a run's `tone` is none of the tone names; the run is kept, untoned. -/// @return The runs, in order. -[[nodiscard]] inline std::vector spansOf(Value const& value, FormatContext const& format, bool& dropped, - bool* badTone = nullptr) { - std::vector spans; - if (value.isNull()) { - return spans; - } - ValueList const* const runs = value.asList(); - if (runs == nullptr) { - dropped = true; - return spans; - } - auto const flag = [](Value const* field) { - bool const* const set = field != nullptr ? field->asBool() : nullptr; - return set != nullptr && *set; - }; - for (Value const& run : *runs) { - if (run.asRecord() == nullptr) { - if (run.isNull() || run.asList() != nullptr) { - dropped = true; - } else { - spans.push_back(TextSpan{.text = textOf(run, format)}); - } - continue; - } - Value const* const text = run.field("text"); - if (text == nullptr) { - dropped = true; - continue; - } - Tone tone = Tone::Neutral; - if (Value const* const named = run.field("tone")) { - if (std::optional const known = toneNamed(*named)) { - tone = *known; - } else if (badTone != nullptr) { - *badTone = true; - } - } - spans.push_back(TextSpan{.text = textOf(*text, format), - .strong = flag(run.field("strong")), - .mono = flag(run.field("mono")), - .tone = tone, - .action = flag(run.field("action"))}); - } - return spans; -} - -/// @brief Whether a scope declares any name, so a node in it reads names the screen's own scope lacks. -/// @param scope The scope. -/// @return True when it declares a model, state, let, query, mutation, watch or check. -[[nodiscard]] inline bool declaresNames(ScopeDecl const& scope) noexcept { - return !(scope.models.empty() && scope.state.empty() && scope.lets.empty() && scope.queries.empty() && - scope.mutations.empty() && scope.watches.empty() && scope.checks.empty()); -} - -/// @brief What a span list with a run it drops is told. -inline constexpr std::string_view kSpansReason = - "spans is a list of runs, each a value or a record with `text`; a list, a null or a record without `text` is " - "dropped"; - -/// @brief What a tone of no known name is told. -inline constexpr std::string_view kToneNames = "a tone is neutral, info, ok, warn or err, or null for none"; - -/// @brief What a span list with a run of a tone of no known name is told. -inline constexpr std::string_view kSpanToneReason = - "a run's tone is neutral, info, ok, warn or err, or null for none; a run of another tone is drawn untoned"; - -/// @brief A splitter's `sizes`: a list of numbers, each read as `intOf` reads it. -/// @param value The value. -/// @return The sizes; `nullopt` for anything but a list whose every item is an `int` or a decimal. -[[nodiscard]] inline std::optional> splitterSizesOf(Value const& value) { - ValueList const* const items = value.asList(); - if (items == nullptr) { - return std::nullopt; - } - std::vector sizes; - sizes.reserve(items->size()); - for (Value const& item : *items) { - if (item.asInt() == nullptr && item.asDecimal() == nullptr) { - return std::nullopt; - } - sizes.push_back(static_cast(intOf(item, 0))); - } - return sizes; -} - -/// @brief A sizing by its document form: `"content"`, `{"fixed": n}`, `{"stretch": w}` or `{"percent": n}`. -/// @param value The value. -/// @return The sizing. -[[nodiscard]] inline Sizing sizingOf(Value const& value) { - if (Value const* const fixed = value.field("fixed")) { - return Sizing::fixed(static_cast(intOf(*fixed, 0))); - } - if (Value const* const percent = value.field("percent")) { - return Sizing::percent(static_cast(intOf(*percent, 1))); - } - if (Value const* const stretch = value.field("stretch")) { - return Sizing::stretch(static_cast(intOf(*stretch, 1))); - } - return Sizing::content(); -} - -/// @brief Whether a value is a sizing of one dimension: `"content"`, `{"fixed": n}`, `{"stretch": w}` or -/// `{"percent": n}` with n from 1 to 100. -/// @param value The value. -/// @return Whether `sizingOf` reads it as written rather than as content by default. -[[nodiscard]] inline bool isSizing(Value const& value) { - if (std::string const* const text = value.asString()) { - return *text == "content"; - } - ValueRecord const* const record = value.asRecord(); - if (record == nullptr || record->size() != 1 || record->begin()->second.asInt() == nullptr) { - return false; - } - if (record->contains("percent")) { - std::int64_t const share = *record->begin()->second.asInt(); - return share >= 1 && share <= 100; - } - return record->contains("fixed") || record->contains("stretch"); -} - -/// @brief An alignment by name, as the loader checked it: `start`, `center`, `end`, or stretch for none. -/// @param name The name; empty for none. -/// @return The alignment. -[[nodiscard]] inline Align alignOf(std::string_view name) { - if (name == "start") { - return Align::Start; - } - if (name == "center") { - return Align::Center; - } - if (name == "end") { - return Align::End; - } - return Align::Stretch; -} - -/// @brief A table cell's place by name: across its column (`align`) or down its row (`valign`). -/// @param name `start`, `center` or `end`. -/// @return The place; `nullopt` for any other name, `stretch` included. -[[nodiscard]] inline std::optional cellPlaceNamed(std::string_view name) { - if (name == "start") { - return Align::Start; - } - if (name == "center") { - return Align::Center; - } - if (name == "end") { - return Align::End; - } - return std::nullopt; -} - -/// @brief A justification by name, as the loader checked it: `center`, `end`, `between`, or start for none. -/// @param name The name; empty for none. -/// @return The justification. -[[nodiscard]] inline Justify justifyOf(std::string_view name) { - if (name == "center") { - return Justify::Center; - } - if (name == "end") { - return Justify::End; - } - if (name == "between") { - return Justify::Between; - } - return Justify::Start; -} - -/// @brief An axis by name: `horizontal`, or vertical for anything else. -/// @param value The value. -/// @return The axis. -[[nodiscard]] inline Axis axisOf(Value const& value) { - std::string const* const text = value.asString(); - return text != nullptr && *text == "horizontal" ? Axis::Horizontal : Axis::Vertical; -} - -/// @brief A step's state by name: `active`, `done`, `failed`, or pending for anything else. -/// @param name The name. -/// @return The state. -[[nodiscard]] inline StepState stepStateOf(std::string_view name) { - if (name == "active") { - return StepState::Active; - } - if (name == "done") { - return StepState::Done; - } - return name == "failed" ? StepState::Failed : StepState::Pending; -} - -/// @brief The options of a select, from a list of scalars or of records with a key and a `label`. -/// @param options The list. -/// @param format The formatting facts. -/// @return The options. -[[nodiscard]] inline std::vector selectOptions(Value const& options, FormatContext const& format) { - std::vector out; - if (ValueList const* const items = options.asList()) { - for (Value const& option : *items) { - Value const key = optionKey(option); - Value const* const label = option.field("label"); - out.push_back(SelectOption{.key = keyOf(key), .label = textOf(label != nullptr ? *label : key, format)}); - } - } - return out; -} - -/// @brief What a percent sizes, as a refusal or a report says it. -inline constexpr std::string_view kPercentPlaces = - "`percent` sizes a width along a row or a horizontal splitter; nothing here takes a share"; -/// @brief Why a percent inside a case or an overlay's content is not a share. -inline constexpr std::string_view kPercentInHolder = "size the `switch` or the overlay itself; its content fills it"; - -/// @brief The default spacing step between the children of a document panel or collapsible, the mockups' 8 px. -inline constexpr int kPanelGap = 2; -/// @brief The default spacing step between the children of a document dialog or drawer, the mockups' 12 px. -inline constexpr int kDialogGap = 3; - -/// @brief A node's size request. -/// @param node The node; may be null. -/// @return Its layout hints, or none for a null node or a kind that has no `Common`. -[[nodiscard]] inline LayoutHints layoutHintsOf(Node const& node) { - if (!node) { - return {}; - } - return std::visit( - [](auto const& spec) -> LayoutHints { - if constexpr (requires { spec.common.layout; }) { - return spec.common.layout; - } else { - return {}; - } - }, - node->kind); -} - -/// @brief A node with its width sizing replaced; a node of a kind with no layout is returned as it is. -/// @param node The node. -/// @param width The sizing. -/// @return The node. -[[nodiscard]] inline Node withWidth(Node const& node, Sizing width) { - if (!node) { - return node; - } - auto copy = std::make_shared(*node); - std::visit( - [&width](auto& spec) { - if constexpr (requires { spec.common.layout; }) { - spec.common.layout.width = width; - } - }, - copy->kind); - return copy; -} - -/// @brief The size request of a holder of @p sizings: a stretch by the largest weight where any is a stretch, and -/// content otherwise (a share of a row is not a holder's: `listColumn` passes a lone child's on). -/// @param sizings One dimension's sizing of each child. -/// @return The holder's sizing. -[[nodiscard]] inline Sizing holderSizing(std::span sizings) { - int weight = 0; - for (Sizing const& sizing : sizings) { - if (sizing.kind == Sizing::Kind::Stretch) { - weight = std::max(weight, sizing.amount); - } - } - return weight > 0 ? Sizing::stretch(weight) : Sizing::content(); -} - -/// @brief The column that holds a node list. It stretches along an axis when one of its children does, so the -/// content means what its nodes would mean written inline in the holder's parent. -/// @param children The content. -/// @param gap The spacing step between children. -/// @return The column; bounds and `alignSelf` stay unset, because they belong to a child. -[[nodiscard]] inline Column listColumn(std::vector children, int gap = 0) { - std::vector widths; - std::vector heights; - for (Node const& child : children) { - LayoutHints const hints = layoutHintsOf(child); - widths.push_back(hints.width); - heights.push_back(hints.height); - } - // A lone child's share of its row is the holder's, and the child fills the holder, so the share is taken once. - if (children.size() == 1 && widths.front().kind == Sizing::Kind::Percent) { - Sizing const share = widths.front(); - children.front() = withWidth(children.front(), Sizing::stretch(1)); - Column column{.children = std::move(children), .gap = gap}; - column.common.layout.width = share; - column.common.layout.height = holderSizing(heights); - return column; - } - Column column{.children = std::move(children), .gap = gap}; - column.common.layout.width = holderSizing(widths); - column.common.layout.height = holderSizing(heights); - return column; -} - -/// @brief Content whose scope is made when it mounts and released when it unmounts: a one-row `forEach` whose -/// row view builds it. -/// @param build Builds the content, its scope included. -/// @param hints The size request of the content. A slot reads the sizing of its direct child alone, which is this -/// `forEach`, so the content's stretch reaches the slot only through these. -/// @return The node. -[[nodiscard]] inline Node lazy(std::function build, LayoutHints const& hints = {}) { - Common common; - common.layout = hints; - return ui::forEach([] { return std::vector{0}; }, [](int const&) { return Key{std::int64_t{0}}; }, - [build = std::move(build)](reactive::Signal const&) { return build(); }, - Axis::Vertical, 0, common); -} - -/// @brief A column of content that holds its scope for as long as it is mounted: its `visible` is a binding -/// that keeps the scope alive and reads nothing. -/// @param children The content. -/// @param scope The scope. -/// @param keys The chords of the content. -/// @param gap The spacing step between the children. -/// @return The node. -[[nodiscard]] inline Node holding(std::vector children, std::shared_ptr scope, - std::vector keys = {}, int gap = 0) { - Column column = listColumn(std::move(children), gap); - column.common.visible = Prop{[held = std::move(scope)] { return held != nullptr; }}; - column.common.keys = std::move(keys); - return ui::column(std::move(column)); -} - -/// @brief Whether an expression reads a name in @p names. -/// @param expr The expression. -/// @param names The names. -/// @return Whether any form of the expression names one. -// NOLINTBEGIN(misc-no-recursion): an expression nests its arguments and fields, and the walk follows them. -[[nodiscard]] inline bool readsAny(ExprPtr const& expr, std::set> const& names) { - if (!expr) { - return false; - } - if (!expr->name.empty() && names.contains(expr->name)) { - return true; - } - return std::ranges::any_of(expr->args, [&](ExprPtr const& arg) { return readsAny(arg, names); }) || - std::ranges::any_of(expr->fields, [&](auto const& field) { return readsAny(field.second, names); }); -} -// NOLINTEND(misc-no-recursion) - -/// @brief Collects the element ids of a document subtree. -/// @param node The root. -/// @param out Receives the ids. -// NOLINTNEXTLINE(misc-no-recursion): a node's children and parts are nodes, and the walk follows them. -inline void collectIds(DocNode const& node, std::set>& out) { - if (!node.id.empty()) { - out.insert(node.id); - } - for (auto const* group : {&node.children, &node.parts}) { - for (auto const& [key, list] : *group) { - for (DocNodePtr const& child : list) { - collectIds(*child, out); - } - } - } -} - -// NOLINTNEXTLINE(misc-no-recursion): lowering a node lowers its children, which come back through here. -inline Node ScreenCore::lowerAll(std::span nodes, LowerCtx const& ctx, int gap) { - LowerCtx listCtx = ctx; - listCtx.listGap = gap; - if (nodes.size() == 1) { - return lower(*nodes.front(), listCtx); - } - std::vector children; - children.reserve(nodes.size()); - for (DocNodePtr const& child : nodes) { - children.push_back(lower(*child, listCtx)); - } - // Several nodes share a holder, and a share of a row is not a share of a holder: each is reported and takes its - // content size. - for (auto&& [child, written] : std::views::zip(children, nodes)) { - if (layoutHintsOf(child).width.kind == Sizing::Kind::Percent) { - report(written->path, - "a percent among several nodes is a share of their holder; " + std::string{kPercentPlaces}); - child = withWidth(child, Sizing::content()); - } - } - Column holder = listColumn(std::move(children), gap); - // The column is the mount's, not the document's: a child that bleeds reaches past the padding of the container - // the document names, so the column passes that padding on instead of hiding it. - holder.holder = true; - return ui::column(std::move(holder)); -} - -inline void ScreenCore::fillHolder(std::vector& children, std::string const& path) { - for (Node& child : children) { - if (layoutHintsOf(child).width.kind == Sizing::Kind::Percent) { - report(path, std::string{kPercentInHolder}); - child = withWidth(child, Sizing::stretch(1)); - } - } -} - -inline LayoutHints ScreenCore::nodeHints(DocNode const& node, std::set> const& own, - LowerCtx const& ctx) { - LayoutHints hints; - if (ExprPtr const sizing = node.prop("sizing")) { - if (sizing->kind != ExprKind::Literal && readsAny(sizing, own)) { - report(sizing->path, - "this sizing reads a name the case declares, so the case is held at its " - "content size"); - } else { - Value const value = once(ctx, sizing); - Value const* const width = value.field("width"); - Value const* const height = value.field("height"); - if (width != nullptr || height != nullptr) { - hints.width = width != nullptr && isSizing(*width) ? sizingOf(*width) : Sizing::content(); - hints.height = height != nullptr && isSizing(*height) ? sizingOf(*height) : Sizing::content(); - } else if (isSizing(value)) { - hints.width = sizingOf(value); - } - } - } - return hints; -} - -inline LayoutHints ScreenCore::holderHints(std::span content, ScopeDecl const* decl, - LowerCtx const& ctx) { - std::set> own; - for (DocNode const* const node : content) { - collectIds(*node, own); - } - if (decl != nullptr) { - for (ModelDecl const& model : decl->models) { - own.insert(model.name); - } - for (StateDecl const& state : decl->state) { - own.insert(state.name); - } - for (LetDecl const& let : decl->lets) { - own.insert(let.name); - } - for (QueryDecl const& query : decl->queries) { - own.insert(query.name); - } - for (MutationDecl const& mutation : decl->mutations) { - own.insert(mutation.name); - } - } - std::vector widths; - std::vector heights; - for (DocNode const* const node : content) { - LayoutHints const hints = nodeHints(*node, own, ctx); - widths.push_back(hints.width); - heights.push_back(hints.height); - } - LayoutHints out; - out.width = holderSizing(widths); - out.height = holderSizing(heights); - return out; -} - -// NOLINTBEGIN(misc-no-recursion): a menu nests, and lowering descends the document. -inline Node ScreenCore::lower(DocNode const& node, LowerCtx const& ctx) { - if (recording) { - if (loweredNodes.size() >= kPruneLoweredAt && loweredNodes.size() % kPruneLoweredAt == 0) { - std::erase_if(loweredNodes, [](LoweredNode const& entry) { return entry.scope.expired(); }); - } - loweredNodes.push_back(LoweredNode{.node = &node, .scope = ctx.scope, .bindings = ctx.bindings}); - } - // Only a switch reads the gap of the list around it; every other kind's children are held by a holder that sets - // their gap, so none sees its grandparent's. - if (ctx.listGap != 0 && node.kind != "switch") { - LowerCtx plain = ctx; - plain.listGap = 0; - return lowerKind(node, plain, elementFor(*ctx.scope, node)); - } - return lowerKind(node, ctx, elementFor(*ctx.scope, node)); -} - -inline Prop ScreenCore::roleProp(LowerCtx const& ctx, ExprPtr const& expr) { - if (!expr || expr->kind == ExprKind::Literal) { - return bindProp(ctx, expr, TextRole::Normal, roleOf); - } - return slotProp([this, scope = ctx.scope, bindings = ctx.bindings, expr] { - Value const value = evalIn(*scope, bindings.get(), expr); - std::optional const role = roleNamed(textOf(value, scope->formatting())); - if (!role) { - report(expr->path, "role is " + canonicalJson(value) + "; " + std::string{kRoleNames}); - } - return role.value_or(TextRole::Normal); - }); -} - -inline Prop ScreenCore::surfaceOf(DocNode const& node, LowerCtx const& ctx) { - ExprPtr const expr = node.prop("surface"); - auto nameOf = [this, path = pointerAppend(node.path, "surface")](Value const& value) -> std::string { - if (std::string const* const name = value.asString()) { - return *name; - } - if (!value.isNull()) { - report(path, "a surface is the name of one; " + canonicalJson(value) + " is not a string"); - } - return {}; - }; - if (!expr || expr->kind == ExprKind::Literal) { - return expr ? Prop{nameOf(expr->literal)} : Prop{std::string{}}; - } - return slotProp([scope = ctx.scope, bindings = ctx.bindings, expr, nameOf = std::move(nameOf)] { - return nameOf(evalIn(*scope, bindings.get(), expr)); - }); -} - -inline KeyValueItem ScreenCore::keyValueItemOf(Value const& item, std::string const& path, RtScope const& scope) { - FormatContext const& format = scope.formatting(); - Value const* const label = item.field("label"); - Value const* const value = item.field("value"); - KeyValueItem out{.label = label == nullptr ? std::string{} : textOf(*label, format), - .value = value == nullptr ? std::string{} : textOf(*value, format)}; - if (Value const* const spans = item.field("spans")) { - bool dropped = false; - bool badTone = false; - out.spans = spansOf(*spans, format, dropped, &badTone); - if (dropped) { - report(path, kSpansReason); - } - if (badTone) { - report(path, kSpanToneReason); - } - } - if (Value const* const tone = item.field("tone")) { - std::optional const named = toneNamed(*tone); - if (!named) { - report(path, "an item's tone is " + canonicalJson(*tone) + "; " + std::string{kToneNames}); - } - out.tone = named.value_or(Tone::Neutral); - } - return out; -} - -// A group needs no widget of its own: it lowers to kinds every backend has, so the view tree and the contract do not -// change. Its description is a line read in order after its children, since `Common` carries no accessible -// description. -inline Node ScreenCore::lowerGroup(DocNode const& node, LowerCtx const& ctx, ElementState* element, - std::vector children) { - Text legend{.text = bindProp(ctx, node.prop("label"), std::string{}, stringOf), - .role = TextRole::Label}; - legend.field.required = bindProp(ctx, node.prop("required"), false, boolOf); - std::vector column; - column.reserve(children.size() + 3); - column.push_back(ui::text(std::move(legend))); - std::ranges::move(children, std::back_inserter(column)); - if (ExprPtr const description = node.prop("description")) { - Text line{.text = bindProp(ctx, description, std::string{}, stringOf), .role = TextRole::Muted}; - line.common.visible = slotProp([scope = ctx.scope, bindings = ctx.bindings, description] { - return !textOf(evalIn(*scope, bindings.get(), description), scope->formatting()).empty(); - }); - column.push_back(ui::text(std::move(line))); - } - // The shown errors, one line each: a check that targets the group shows its message here. - auto shown = [this, element, scope = ctx.scope, bindings = ctx.bindings, errors = node.prop("errors")] { - return stringsOf(element != nullptr ? elementValue(*element, "shownErrors") - : evalIn(*scope, bindings.get(), errors)); - }; - Text messages{.text = slotProp([shown] { - std::string joined; - for (std::string const& message : shown()) { - joined += (joined.empty() ? "" : "\n") + message; - } - return joined; - }), - .role = TextRole::Error}; - messages.common.visible = slotProp([shown] { return !shown().empty(); }); - column.push_back(ui::text(std::move(messages))); - Column spec{.children = std::move(column), - .gap = static_cast(intOf(node.prop("gap") ? once(ctx, node.prop("gap")) : Value{}, 0))}; - commonOf(node, ctx, element, spec.common); - if (spec.common.a11y.role.empty()) { - spec.common.a11y.role = "group"; - } - bool const named = std::ranges::any_of(node.partList("a11y"), - [](DocNodePtr const& a11y) { return a11y->prop("name") != nullptr; }); - if (!named) { - spec.common.a11y.name = bindProp(ctx, node.prop("label"), std::string{}, stringOf); - } - return ui::column(std::move(spec)); -} - -inline Prop> ScreenCore::spansProp(LowerCtx const& ctx, ExprPtr const& expr) { - return slotProp>([this, scope = ctx.scope, bindings = ctx.bindings, expr] { - bool dropped = false; - bool badTone = false; - std::vector spans = - spansOf(evalIn(*scope, bindings.get(), expr), scope->formatting(), dropped, &badTone); - if (dropped) { - report(expr->path, kSpansReason); - } - if (badTone) { - report(expr->path, kSpanToneReason); - } - return spans; - }); -} - -// The size request: `sizing` (the width, or both dimensions), `alignSelf`, and the bounds. -inline void ScreenCore::layoutOf(DocNode const& node, LowerCtx const& ctx, LayoutHints& layout) { - if (ExprPtr const sizing = node.prop("sizing")) { - // The width, or both dimensions from a `{width, height}` record, one left out being content. The loader - // refuses a literal of another form; a computed one that is none is reported and lowers to content. - Value const value = once(ctx, sizing); - Value const* const width = value.field("width"); - Value const* const height = value.field("height"); - bool const record = width != nullptr || height != nullptr; - bool const valid = record ? (width == nullptr || isSizing(*width)) && (height == nullptr || isSizing(*height)) - : isSizing(value); - if (!valid) { - report(sizing->path, "sizing is " + canonicalJson(value) + - "; a sizing is \"content\", {\"fixed\": n}, {\"stretch\": w}, {\"percent\": n} " - "with n from 1 to 100, or a record of width and height of them"); - } else if (record) { - layout.width = width != nullptr ? sizingOf(*width) : Sizing::content(); - layout.height = height != nullptr ? sizingOf(*height) : Sizing::content(); - if (layout.height.kind == Sizing::Kind::Percent) { - report(sizing->path, std::string{kPercentPlaces}); - layout.height = Sizing::content(); - } - } else { - layout.width = sizingOf(value); - } - } - if (std::string_view const placed = node.name("alignSelf"); !placed.empty()) { - layout.alignSelf = alignOf(placed); - } - layout.bleed = node.flag("bleed"); - // Literal integers, checked at load. - for (auto const& [key, bound] : - {std::pair{"minWidth", &LayoutHints::minWidth}, std::pair{"maxWidth", &LayoutHints::maxWidth}, - std::pair{"minHeight", &LayoutHints::minHeight}, std::pair{"maxHeight", &LayoutHints::maxHeight}}) { - if (ExprPtr const expr = node.prop(key); expr != nullptr && expr->literal.asInt() != nullptr) { - layout.*bound = static_cast(*expr->literal.asInt()); - } - } -} - -/// @brief Where a declaration is lowered, as a focus key reads it. -struct FocusPlace { - /// @brief The focus key of the component use it is lowered for, and `>`; empty outside a component. - std::string prefix; - /// @brief The keys of the rows that enclose it, outermost first. - std::vector rows; -}; - -/// @brief Where @p scope is: the row keys of its chain and the component use it is lowered for. -/// @param scope The scope. -/// @return It. -[[nodiscard]] inline FocusPlace focusPlace(RtScope const& scope) { - FocusPlace place; - for (RtScope const* current = &scope; current != nullptr; current = current->parent.get()) { - if (current->row != nullptr) { - place.rows.push_back(current->rowKey); - } - if (current->parent == nullptr) { - place.prefix = current->usePrefix; - } - } - std::ranges::reverse(place.rows); - return place; -} - -/// @brief A focus key: a declaration's pointer under its component use's prefix, with one key per enclosing row. -/// @param place Where the declaration is lowered. -/// @param path The declaring node's JSON Pointer. -/// @return The key, unique per declaration, row and component use. -[[nodiscard]] inline std::string focusKey(FocusPlace const& place, std::string_view path) { - std::string key = place.prefix; - key += path; - for (std::string const& row : place.rows) { - key += '@'; - key += row; - } - return key; -} - -/// @brief The focus key of the element @p path declares, lowered in @p scope. -/// @param path The declaring node's JSON Pointer. -/// @param scope The scope it is lowered in. -/// @return The key. -[[nodiscard]] inline std::string focusKeyOf(std::string_view path, RtScope const& scope) { - return focusKey(focusPlace(scope), path); -} - -inline void ScreenCore::commonOf(DocNode const& node, LowerCtx const& ctx, ElementState* element, Common& common) { - static_cast(element); - common.visible = bindProp(ctx, node.prop("visible"), true, boolOf); - common.enabled = bindProp(ctx, node.prop("enabled"), true, boolOf); - common.tooltip = bindProp(ctx, node.prop("tooltip"), std::string{}, stringOf); - layoutOf(node, ctx, common.layout); - common.testId = std::string{node.name("testId")}; - if (!node.id.empty()) { - common.focusId = focusKeyOf(node.path, *ctx.scope); - } - common.surface = surfaceOf(node, ctx); - if (ExprPtr const autofocus = node.prop("autofocus")) { - common.autofocus = boolOf(once(ctx, autofocus), ctx.scope->formatting()); - } - for (DocNodePtr const& a11y : node.partList("a11y")) { - common.a11y.name = bindProp(ctx, a11y->prop("name"), std::string{}, stringOf); - common.a11y.role = std::string{a11y->name("role")}; - } - for (DocNodePtr const& drag : node.partList("drag")) { - ExprPtr const payload = drag->prop("payload"); - common.dragKey = slotProp>( - [scope = ctx.scope, bindings = ctx.bindings, payload]() -> std::optional { - Value const value = evalIn(*scope, bindings.get(), payload); - return value.isNull() ? std::nullopt : std::optional{keyOf(value)}; - }); - } - for (DocNodePtr const& drop : node.partList("drop")) { - ExprPtr const accepts = drop->prop("accepts"); - common.accepts = [this, scope = ctx.scope, bindings = ctx.bindings, accepts](Key const& key) { - if (!accepts) { - return true; - } - Value const accepted = runtime().untracked([&] { return evalIn(*scope, bindings.get(), accepts); }); - if (ValueList const* const items = accepted.asList()) { - return std::ranges::any_of(*items, [&](Value const& item) { return keyOf(item) == key; }); - } - return accepted.isNull() || keyOf(accepted) == key; - }; - common.onDrop = [this, ctx, commands = drop->event("onDrop")](Key const& key) { - runEvent(commands, ctx, valueOfKey(key)); - }; - } - for (auto const& [chord, commands] : node.keys) { - common.keys.push_back( - KeyBinding{.chord = chord, .onPress = [this, ctx, list = &commands] { runEvent(list, ctx, Value{}); }}); - } -} - -inline void ScreenCore::fieldOf(DocNode const& node, LowerCtx const& ctx, ElementState* element, FieldState& field) { - field.readonly = bindProp(ctx, node.prop("readonly"), false, boolOf); - field.required = bindProp(ctx, node.prop("required"), false, boolOf); - field.stale = bindProp(ctx, node.prop("stale"), false, boolOf); - if (element != nullptr) { - field.errors = slotProp>( - [this, scope = ctx.scope, element] { return stringsOf(elementValue(*element, "shownErrors")); }); - } else if (ExprPtr const errors = node.prop("errors")) { - field.errors = slotProp>([scope = ctx.scope, bindings = ctx.bindings, errors] { - return stringsOf(evalIn(*scope, bindings.get(), errors)); - }); - } - // A tone evaluates the value and is not an error: it changes the field's look and nothing of `valid`. - if (node.prop("description")) { - field.description = bindProp(ctx, node.prop("description"), std::string{}, stringOf); - } - if (node.prop("labelHint")) { - field.labelHint = bindProp(ctx, node.prop("labelHint"), std::string{}, stringOf); - } - if (ExprPtr const tone = node.prop("tone")) { - field.tone = slotProp([this, scope = ctx.scope, bindings = ctx.bindings, tone] { - Value const value = evalIn(*scope, bindings.get(), tone); - std::optional const named = toneNamed(value); - if (!named) { - report(tone->path, "tone is " + canonicalJson(value) + "; " + std::string{kToneNames}); - } - return named.value_or(Tone::Neutral); - }); - } -} - -inline MenuItem ScreenCore::menuItemOf(DocNode const& part, LowerCtx const& ctx) { - MenuItem item; - if (part.flag("separator")) { - item.separator = true; - return item; - } - item.label = bindProp(ctx, part.prop("label"), std::string{}, stringOf); - item.description = bindProp(ctx, part.prop("description"), std::string{}, stringOf); - item.visible = bindProp(ctx, part.prop("visible"), true, boolOf); - if (Commands const* const commands = part.event("onClick")) { - item.onSelect = [this, ctx, commands] { runEvent(commands, ctx, Value{}); }; - } - if (ExprPtr const icon = part.prop("icon")) { - item.icon = textOf(once(ctx, icon), ctx.scope->formatting()); - } - item.keys = std::string{part.name("keys")}; - if (ExprPtr const checked = part.prop("checked")) { - item.checked = slotProp>( - [scope = ctx.scope, bindings = ctx.bindings, checked]() -> std::optional { - Value const value = evalIn(*scope, bindings.get(), checked); - bool const* const flag = value.asBool(); - return flag == nullptr ? std::nullopt : std::optional{*flag}; - }); - } - item.enabled = bindProp(ctx, part.prop("enabled"), true, boolOf); - return item; -} - -// NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. -inline std::vector ScreenCore::menuItems(std::span parts, LowerCtx const& ctx) { - std::vector items; - for (DocNodePtr const& part : parts) { - MenuItem item = menuItemOf(*part, ctx); - if (!item.separator) { - item.items = menuItems(part->partList("items"), ctx); - } - items.push_back(std::move(item)); - } - return items; -} - -// NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. -inline std::vector ScreenCore::lowerHeadMenu(std::span parts, LowerCtx const& ctx) { - std::vector models; - models.reserve(parts.size()); - for (DocNodePtr const& part : parts) { - models.push_back(HeadMenuModel{.id = part->id, - .path = part->path, - .item = menuItemOf(*part, ctx), - .items = lowerHeadMenu(part->partList("items"), ctx)}); - } - return models; -} - -inline std::vector ScreenCore::lowerHeadTools(std::span parts, LowerCtx const& ctx) { - static constexpr int kSearchWidth = 30; - std::vector models; - models.reserve(parts.size()); - for (DocNodePtr const& part : parts) { - bool const search = part->name("kind") == "search"; - HeadToolModel model{ - .id = part->id, - .path = part->path, - .kind = search ? HeadToolKind::Search : HeadToolKind::Select, - .label = bindProp(ctx, part->prop("label"), std::string{}, stringOf), - .value = bindProp(ctx, part->prop("value"), std::string{}, stringOf), - .placeholder = bindProp(ctx, part->prop("placeholder"), std::string{}, stringOf), - .options = {}, - .selected = {}, - .width = search ? kSearchWidth : 0, - .enabled = bindProp(ctx, part->prop("enabled"), true, boolOf), - .visible = bindProp(ctx, part->prop("visible"), true, boolOf), - .edit = {}, - .submit = {}}; - if (ExprPtr const width = part->prop("width")) { - if (std::int64_t const* const units = width->literal.asInt()) { - model.width = static_cast(*units); - } - } - if (!search) { - model.options = slotProp>( - [scope = ctx.scope, bindings = ctx.bindings, options = part->prop("options")] { - return selectOptions(evalIn(*scope, bindings.get(), options), scope->formatting()); - }); - model.selected = slotProp>([scope = ctx.scope, bindings = ctx.bindings, - selected = part->prop("selected")]() -> std::optional { - Value const value = selected ? evalIn(*scope, bindings.get(), selected) : Value{}; - return value.isNull() ? std::nullopt : std::optional{keyOf(value)}; - }); - } - Commands const* const edited = part->event(search ? "onChange" : "onChoose"); - model.edit = [this, ctx, edited](Value event) { runEvent(edited, ctx, std::move(event)); }; - if (search) { - model.submit = [this, ctx, onSubmit = part->event("onSubmit")](Value event) { - runEvent(onSubmit, ctx, std::move(event)); - }; - } - models.push_back(std::move(model)); - } - return models; -} - -inline ActionModels ScreenCore::lowerActionParts(std::span parts, LowerCtx const& ctx) { - ActionModels models; - models.reserve(parts.size()); - for (DocNodePtr const& part : parts) { - ActionModel model{.id = part->id, - .path = part->path, - .label = bindProp(ctx, part->prop("label"), std::string{}, stringOf), - .icon = bindProp(ctx, part->prop("icon"), std::string{}, stringOf), - .iconOnly = bindProp(ctx, part->prop("iconOnly"), false, boolOf), - .emphasis = ButtonEmphasis::Normal, - .enabled = bindProp(ctx, part->prop("enabled"), true, boolOf), - .visible = bindProp(ctx, part->prop("visible"), true, boolOf), - .run = {}}; - model.emphasis = emphasisNamed(part->name("emphasis")).value_or(ButtonEmphasis::Normal); - if (Commands const* const commands = part->event("onClick")) { - model.run = [this, ctx, commands] { runEvent(commands, ctx, Value{}); }; - } - models.push_back(std::move(model)); - } - return models; -} - -inline Node ScreenCore::actionBarOf(ActionModels actions) { - ActionBar bar; - for (ActionModel& action : actions) { - Button button{.label = action.label, - .emphasis = action.emphasis, - .onClick = std::move(action.run), - .common = {}, - .icon = action.icon.evaluate()}; - if (action.iconOnly.isBound() || action.iconOnly.constant()) { - // The label is the button's name and tooltip; the caption is empty while the icon stands alone. - button.label = Prop{[label = action.label, iconOnly = action.iconOnly] { - return iconOnly.evaluate() ? std::string{} : label.evaluate(); - }}; - button.common.a11y.name = action.label; - button.common.tooltip = action.label; - } - button.common.visible = std::move(action.visible); - button.common.enabled = std::move(action.enabled); - button.common.testId = "action_" + action.id; - bar.children.push_back(ui::button(std::move(button))); - } - return ui::actionBar(std::move(bar)); -} - -inline std::vector ScreenCore::lowerBadgeParts(std::span parts, LowerCtx const& ctx) { - std::vector badges; - badges.reserve(parts.size()); - for (DocNodePtr const& part : parts) { - badges.push_back(BadgeModel{.text = bindProp(ctx, part->prop("text"), std::string{}, stringOf), - .tone = bindProp(ctx, part->prop("tone"), Tone::Neutral, toneOf), - .icon = bindProp(ctx, part->prop("icon"), std::string{}, stringOf), - .visible = bindProp(ctx, part->prop("visible"), true, boolOf)}); - } - return badges; -} - -// The readers every kind's lowering shares, each bound to the node being lowered. -class ScreenCore::KindKit { -public: - KindKit(ScreenCore& core, DocNode const& node, LowerCtx const& ctx, ElementState* element) - : _core{core}, _node{node}, _ctx{ctx}, _element{element}, _format{ctx.scope->formatting()} {} - - // The children under @p key, each lowered with @p gap as the gap of the list around it. - [[nodiscard]] std::vector children(std::string_view key, int gap = 0) const { - LowerCtx listCtx = _ctx; - listCtx.listGap = gap; - std::vector out; - for (DocNodePtr const& child : _node.nodes(key)) { - out.push_back(_core.lower(*child, listCtx)); - } - return out; - } - - // The children under @p key as one node: none is empty, several share a holder that sets @p gap. - [[nodiscard]] Node child(std::string_view key, int gap = 0) const { - auto const nodes = _node.nodes(key); - return nodes.empty() ? Node{} : _core.lowerAll(nodes, _ctx, gap); - } - - [[nodiscard]] std::int64_t onceInt(std::string_view key, std::int64_t fallback) const { - ExprPtr const expr = _node.prop(key); - return expr ? intOf(_core.once(_ctx, expr), fallback) : fallback; - } - - [[nodiscard]] bool onceBool(std::string_view key, bool fallback) const { - ExprPtr const expr = _node.prop(key); - return expr ? boolOf(_core.once(_ctx, expr), _format) : fallback; - } - - // A stack's padding: one step, or the loader-checked constant list of the vertical and the horizontal step. A - // computed padding that yields a list is not a step: it is reported once and taken as 0. - [[nodiscard]] Padding stackPadding() const { - ExprPtr const expr = _node.prop("padding"); - if (!expr) { - return {}; - } - Value const value = _core.once(_ctx, expr); - if (ValueList const* const steps = value.asList()) { - if (expr->kind == ExprKind::Literal && steps->size() == 2) { - return Padding{static_cast(intOf(steps->at(0), 0)), static_cast(intOf(steps->at(1), 0))}; - } - _core.report(_node.path + "/padding", "a computed `padding` is one spacing step, not a list; taken as 0"); - return {}; - } - return Padding{static_cast(intOf(value, 0))}; - } - - [[nodiscard]] std::string onceText(std::string_view key) const { - ExprPtr const expr = _node.prop(key); - return expr ? textOf(_core.once(_ctx, expr), _format) : std::string{}; - } - - [[nodiscard]] Prop textProp(std::string_view key) const { - return _core.bindProp(_ctx, _node.prop(key), std::string{}, stringOf); - } - - // A field shows no caption of its own, so its label is what names it to assistive technology. An `a11y` part - // that gives a name was written for that purpose and wins; one that gives only a role leaves the label. - void nameByLabel(Common& common) const { - bool const named = std::ranges::any_of(_node.partList("a11y"), - [](DocNodePtr const& a11y) { return a11y->prop("name") != nullptr; }); - if (_node.prop("label") && !named) { - common.a11y.name = textProp("label"); - } - } - - // A standalone input draws its label as a caption only when the document asks for it (`showLabel`). - template - void captionOf(Spec& spec) const { - if (_node.prop("label")) { - spec.label = textProp("label"); - } - spec.showLabel = _node.flag("showLabel"); - } - - [[nodiscard]] Action action(std::string_view key) const { - Commands const* const commands = _node.event(key); - if (commands == nullptr) { - return {}; - } - return [core = &_core, ctx = _ctx, commands] { core->runEvent(commands, ctx, Value{}); }; - } - - [[nodiscard]] ActionButton actionPart() const { - ActionButton button; - for (DocNodePtr const& part : _node.partList("action")) { - button.label = _core.bindProp(_ctx, part->prop("label"), std::string{}, stringOf); - if (Commands const* const commands = part->event("onClick")) { - button.onClick = [core = &_core, ctx = _ctx, commands] { core->runEvent(commands, ctx, Value{}); }; - } - } - return button; - } - - // A reader of the element's value under @p name. - [[nodiscard]] auto read(std::string_view name) const { - return [element = _element, core = &_core, name = std::string{name}] { - return core->elementValue(*element, name); - }; - } - -private: - // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members): the kit lives inside one lowering call, in - // which all four outlive it. - ScreenCore& _core; - DocNode const& _node; - LowerCtx const& _ctx; - ElementState* _element; - FormatContext const& _format; - // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members) -}; - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of ui/1. -inline std::optional ScreenCore::lowerWidget(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - std::string_view const kind = node.kind; - FormatContext const& format = ctx.scope->formatting(); - KindKit const kit{*this, node, ctx, element}; - if (kind == "text") { - Text spec{.role = roleProp(ctx, node.prop("role"))}; - // A text with spans shows them, so its `text`, an older client's fallback, is not lowered. - if (ExprPtr const spans = node.prop("spans")) { - spec.spans = spansProp(ctx, spans); - } else { - spec.text = kit.textProp("text"); - } - if (!node.name("align").empty()) { - spec.align = textAlignNamed(node.name("align")); - } - fieldOf(node, ctx, element, spec.field); - commonOf(node, ctx, element, spec.common); - return ui::text(std::move(spec)); - } - if (kind == "button") { - Button spec{.label = kit.textProp("label")}; - spec.icon = kit.onceText("icon"); - spec.emphasis = emphasisNamed(node.name("emphasis")).value_or(ButtonEmphasis::Normal); - if (node.name("style") == "item") { - spec.style = ButtonStyle::Item; - } - spec.shape = shapeNamed(node.name("shape")).value_or(ControlShape::Default); - spec.size = sizeNamed(node.name("size")).value_or(ButtonSize::Normal); - spec.mono = node.flag("mono"); - spec.weight = weightNamed(node.name("weight")).value_or(0); - if (node.prop("selected")) { - spec.selected = bindProp(ctx, node.prop("selected"), false, boolOf); - // An entry's content, drawn in place of its label: one node as it is, several in a column. - if (std::vector content = kit.children("children"); content.size() == 1) { - spec.child = std::move(content.front()); - } else if (!content.empty()) { - spec.child = ui::column(Column{.children = std::move(content)}); - } - } - Commands const* const onClick = node.event("onClick"); - Commands const* const onActivate = node.event("onActivate"); - if (onClick != nullptr || onActivate != nullptr) { - spec.onClick = [this, ctx, onClick, onActivate] { - runEvent(onClick, ctx, Value{}); - runEvent(onActivate, ctx, Value{}); - }; - } - commonOf(node, ctx, element, spec.common); - return ui::button(std::move(spec)); - } - if (kind == "textInput") { - std::string const commitOn = node.name("commitOn").empty() ? "change" : std::string{node.name("commitOn")}; - auto commit = [this, ctx, element, commitOn, onChange = node.event("onChange")](std::string const& when, - std::string const& text) { - if (commitOn != when) { - return; - } - if (element->bound == nullptr) { - session.noteWrite(); - element->committed.set(Value{text}); - } - runEvent(onChange, ctx, Value{text}); - }; - TextInput spec; - spec.value = - slotProp([this, element] { return textOf(element->draft.get(), session.formatting()); }); - spec.onChange = [this, element, commit](std::string text) { - session.asUser([&] { - session.noteWrite(); - element->draft.set(Value{text}); - element->edited.set(true); - }); - commit("change", text); - }; - spec.onCommit = [this, ctx, element, commit, onCommit = node.event("onCommit")](std::string const& text) { - element->touched.set(true); - commit("blur", text); - runEvent(onCommit, ctx, Value{text}); - }; - // Only a field that does something on Enter submits: one without `onSubmit` that does not commit on Enter - // lets Enter go on to its ancestors' chords, a dialog's `default` among them. - if (Commands const* const onSubmit = node.event("onSubmit"); onSubmit != nullptr || commitOn == "enter") { - spec.onSubmit = [this, ctx, commit, onSubmit](std::string const& text) { - commit("enter", text); - runEvent(onSubmit, ctx, Value{text}); - }; - } - spec.placeholder = kit.textProp("placeholder"); - std::string const mode = kit.onceText("mode"); - spec.mode = TextInputMode::SingleLine; - if (mode == "multiline") { - spec.mode = TextInputMode::Multiline; - } else if (mode == "password") { - spec.mode = TextInputMode::Password; - } - // A multiline input shows no unit and no icon; a computed mode that turns out multiline is reported and - // its unit and icon left out, so the mount never meets them there. The loader refuses a literal one. - for (std::string_view const key : {std::string_view{"unit"}, std::string_view{"icon"}, - std::string_view{"prefix"}, std::string_view{"decimals"}}) { - if (ExprPtr const given = node.prop(key); given != nullptr && spec.mode == TextInputMode::Multiline) { - report(given->path, "a multiline input shows no " + std::string{key}); - } - } - spec.mono = node.flag("mono"); - if (spec.mode != TextInputMode::Multiline) { - spec.emphasis = node.name("emphasis") == "prominent" ? InputEmphasis::Prominent : InputEmphasis::Normal; - spec.icon = kit.onceText("icon"); - spec.align = alignOf(node.name("align")); - if (spec.align == Align::Stretch) { - spec.align = Align::Start; - } - if (node.prop("unit")) { - spec.unit = kit.textProp("unit"); - } - if (node.prop("prefix")) { - spec.prefix = kit.textProp("prefix"); - } - if (ExprPtr const places = node.prop("decimals")) { - spec.decimals = bindProp(ctx, places, -1, placesOf); - } - } - fieldOf(node, ctx, element, spec.field); - commonOf(node, ctx, element, spec.common); - kit.nameByLabel(spec.common); - kit.captionOf(spec); - return ui::textInput(std::move(spec)); - } - if (kind == "checkbox") { - Checkbox spec{.label = kit.textProp("label"), .checked = slotProp([read = kit.read("checked")] { - Value const value = read(); - bool const* const flag = value.asBool(); - return flag != nullptr && *flag; - })}; - spec.onToggle = [this, ctx, element, onToggle = node.event("onToggle"), - onChange = node.event("onChange")](bool checked) { - // A toggle is a check box's commit, so it touches the box. - session.asUser([&] { - if (element->bound == nullptr) { - session.noteWrite(); - element->draft.set(checked); - } - element->touched.set(true); - }); - runEvent(onToggle, ctx, Value{checked}); - runEvent(onChange, ctx, Value{checked}); - }; - fieldOf(node, ctx, element, spec.field); - commonOf(node, ctx, element, spec.common); - return ui::checkbox(std::move(spec)); - } - if (kind == "select") { - Select spec; - spec.options = slotProp>( - [scope = ctx.scope, element] { return selectOptions(element->rows->get(), scope->formatting()); }); - spec.selected = slotProp>([read = kit.read("selected")]() -> std::optional { - Value const selected = read(); - return selected.isNull() ? std::nullopt : std::optional{keyOf(selected)}; - }); - spec.onSelect = [this, ctx, element, onChoose = node.event("onChoose"), - onChange = node.event("onChange")](Key const& key) { - Value const chosen = valueOfKey(key); - // A choice is a select's commit, so it touches the select. - session.asUser([&] { - if (element->bound == nullptr) { - session.noteWrite(); - element->draft.set(chosen); - } - element->touched.set(true); - }); - runEvent(onChoose, ctx, chosen); - runEvent(onChange, ctx, chosen); - }; - // A computed style of no known name is reported once and drawn as a dropdown; the loader refuses a constant - // one. - if (ExprPtr const style = node.prop("style")) { - std::string const name = textOf(once(ctx, style), ctx.scope->formatting()); - if (name == "radio") { - spec.style = SelectStyle::Radio; - } else if (name == "segmented") { - spec.style = SelectStyle::Segmented; - } else if (name != "dropdown") { - report(style->path, "style is `" + name + "`; a select's style is dropdown, radio or segmented"); - } - } - fieldOf(node, ctx, element, spec.field); - commonOf(node, ctx, element, spec.common); - kit.nameByLabel(spec.common); - kit.captionOf(spec); - return ui::select(std::move(spec)); - } - if (kind == "slider") { - Slider spec; - spec.value = slotProp([read = kit.read("value"), element] { - return intOf(element->bound != nullptr ? read() : element->draft.get(), 0); - }); - spec.minimum = kit.onceInt("min", 0); - spec.maximum = kit.onceInt("max", 100); - spec.step = kit.onceInt("step", 1); - spec.onChange = [this, ctx, element, onChange = node.event("onChange")](std::int64_t value) { - session.asUser([&] { - session.noteWrite(); - element->draft.set(value); - element->edited.set(true); - if (element->bound == nullptr) { - element->committed.set(value); - } - }); - runEvent(onChange, ctx, Value{value}); - }; - spec.onCommit = [this, ctx, element, onCommit = node.event("onCommit")](std::int64_t value) { - element->touched.set(true); - runEvent(onCommit, ctx, Value{value}); - }; - fieldOf(node, ctx, element, spec.field); - commonOf(node, ctx, element, spec.common); - kit.nameByLabel(spec.common); - return ui::slider(std::move(spec)); - } - if (kind == "dateTimeInput") { - DateTimeInput spec; - DateMode const mode = kit.onceText("mode") == "date" ? DateMode::Date : DateMode::DateTime; - std::optional heldAtLoad; - if (auto const found = _doc->dateValueKinds.find(&node); found != _doc->dateValueKinds.end()) { - heldAtLoad = found->second; - } - std::string const valuePath = pointerAppend(node.path, "value"); - std::int32_t const offsetMinutes = format.utcOffsetMinutes; - spec.value = slotProp>([this, element, offsetMinutes, - valuePath]() -> std::optional { - DateReading const reading = dateInstantOf(element->draft.get(), offsetMinutes); - if (!reading.readable) { - report(valuePath, "`dateTimeInput` shows a timestamp or an ISO-8601 date or date-time string"); - } - return reading.instant ? std::optional{time::Timestamp{*reading.instant}} : std::nullopt; - }); - spec.onChange = [this, ctx, element, heldAtLoad, mode, offsetMinutes, onChange = node.event("onChange"), - onCommit = node.event("onCommit")](std::optional value) { - bool asString = element->bound != nullptr && element->bound->get().asString() != nullptr; - if (heldAtLoad) { - asString = *heldAtLoad == TypeKind::String; - } - std::optional const instant = value ? value->value : std::nullopt; - Value entered; - if (!asString) { - if (instant) { - entered = Value{*instant}; - } - } else if (!instant) { - entered = Value{std::string{}}; - } else if (mode == DateMode::Date) { - entered = Value{dateTextOf(*instant, offsetMinutes)}; - } else { - entered = Value{instant->toIso8601()}; - } - element->touched.set(true); - session.asUser([&] { - session.noteWrite(); - element->draft.set(entered); - element->edited.set(true); - if (element->bound == nullptr) { - element->committed.set(entered); - } - }); - runEvent(onChange, ctx, entered); - runEvent(onCommit, ctx, entered); - }; - spec.mode = mode; - spec.offsetMinutes = offsetMinutes; - // Tracked: a locale switch changes the pattern the screen's dates are written in, and the input follows. - spec.pattern = slotProp([this, mode] { - FormatContext const& now = session.formatting(); - return mode == DateMode::Date ? now.datePattern : now.dateTimePattern; - }); - fieldOf(node, ctx, element, spec.field); - commonOf(node, ctx, element, spec.common); - kit.nameByLabel(spec.common); - kit.captionOf(spec); - return ui::dateTimeInput(std::move(spec)); - } - if (kind == "filePicker") { - FilePicker spec; - spec.path = - slotProp([this, element] { return textOf(element->draft.get(), session.formatting()); }); - spec.onPicked = [this, ctx, element, onPick = node.event("onPick")](std::string path) { - session.asUser([&] { - session.noteWrite(); - element->draft.set(Value{path}); - element->committed.set(Value{path}); - }); - runEvent(onPick, ctx, Value{path}); - }; - spec.mode = kit.onceText("mode") == "save" ? FilePickerMode::Save : FilePickerMode::Open; - fieldOf(node, ctx, element, spec.field); - commonOf(node, ctx, element, spec.common); - kit.nameByLabel(spec.common); - return ui::filePicker(std::move(spec)); - } - if (kind == "menu") { - Menu spec{.items = menuItems(node.partList("items"), ctx)}; - if (node.name("style") == "button") { - spec.style = MenuStyle::Button; - spec.label = kit.textProp("label"); - spec.icon = kit.onceText("icon"); - if (node.name("emphasis") == "primary") { - spec.emphasis = ButtonEmphasis::Primary; - } else if (node.name("emphasis") == "danger") { - spec.emphasis = ButtonEmphasis::Danger; - } else if (node.name("emphasis") == "ghost") { - spec.emphasis = ButtonEmphasis::Ghost; - } - } - commonOf(node, ctx, element, spec.common); - return ui::menu(std::move(spec)); - } - return std::nullopt; -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of ui/1. -inline std::optional ScreenCore::lowerDisplay(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - std::string_view const kind = node.kind; - KindKit const kit{*this, node, ctx, element}; - if (kind == "banner") { - Banner spec{.tone = bindProp(ctx, node.prop("tone"), Tone::Info, toneOf)}; - if (ExprPtr const spans = node.prop("spans")) { - spec.spans = spansProp(ctx, spans); - } else { - spec.text = kit.textProp("text"); - } - spec.action = kit.actionPart(); - spec.dismissible = kit.onceBool("dismissible", false); - spec.onDismiss = kit.action("onDismiss"); - spec.actionStyle = bannerActionStyleNamed(node.name("actionStyle")).value_or(BannerActionStyle::Ghost); - spec.actionStretch = node.flag("actionStretch"); - commonOf(node, ctx, element, spec.common); - return ui::banner(std::move(spec)); - } - if (kind == "badge") { - Badge spec{.tone = bindProp(ctx, node.prop("tone"), Tone::Neutral, toneOf), - .text = kit.textProp("text")}; - spec.icon = kit.onceText("icon"); - std::string_view const style = node.name("style"); - spec.style = BadgeStyle::Filled; - if (style == "outline") { - spec.style = BadgeStyle::Outline; - } else if (style == "quiet") { - spec.style = BadgeStyle::Quiet; - } - spec.shape = shapeNamed(node.name("shape")).value_or(ControlShape::Default); - spec.mono = node.flag("mono"); - if (Commands const* const onRemove = node.event("onRemove")) { - spec.onRemove = [this, ctx, onRemove] { runEvent(onRemove, ctx, Value{}); }; - spec.removeLabel = kit.textProp("removeLabel"); - } - commonOf(node, ctx, element, spec.common); - return ui::badge(std::move(spec)); - } - if (kind == "progress") { - Progress spec; - spec.value = slotProp>( - [scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("value")]() -> std::optional { - Value const value = evalIn(*scope, bindings.get(), expr); - if (std::int64_t const* const number = value.asInt()) { - return static_cast(*number); - } - if (Decimal const* const number = value.asDecimal()) { - return realOf(number->value); - } - return std::nullopt; - }); - spec.label = kit.textProp("label"); - commonOf(node, ctx, element, spec.common); - return ui::progress(std::move(spec)); - } - if (kind == "steps") { - Steps spec; - spec.items = - slotProp>([scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("items")] { - std::vector steps; - Value const items = evalIn(*scope, bindings.get(), expr); - if (ValueList const* const list = items.asList()) { - for (Value const& item : *list) { - Value const* const label = item.field("label"); - Value const* const state = item.field("state"); - Value const* const detail = item.field("detail"); - std::string const name = state == nullptr ? std::string{} : textOf(*state, {}); - steps.push_back( - Step{.label = label == nullptr ? std::string{} : textOf(*label, scope->formatting()), - .state = stepStateOf(name), - .detail = detail == nullptr ? std::string{} : textOf(*detail, scope->formatting())}); - } - } - return steps; - }); - spec.current = slotProp>( - [scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("current")]() -> std::optional { - std::int64_t const index = intOf(evalIn(*scope, bindings.get(), expr), -1); - return index < 0 ? std::nullopt : std::optional{static_cast(index)}; - }); - spec.labelled = bindProp(ctx, node.prop("labelled"), true, boolOf); - commonOf(node, ctx, element, spec.common); - return ui::steps(std::move(spec)); - } - if (kind == "chart") { - return lowerChart(node, ctx, element); - } - if (kind == "keyValue") { - KeyValue spec; - spec.captions = node.name("fieldLayout") == "stacked" ? CaptionPlacement::Above : CaptionPlacement::Beside; - // The loader has checked `captionWidth` is a literal integer. - if (ExprPtr const width = node.prop("captionWidth")) { - spec.captionWidth = static_cast(*width->literal.asInt()); - } - spec.items = slotProp>( - [this, scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("items")] { - std::vector out; - Value const items = evalIn(*scope, bindings.get(), expr); - if (ValueList const* const list = items.asList()) { - for (Value const& item : *list) { - out.push_back(keyValueItemOf(item, expr->path, *scope)); - } - } - return out; - }); - commonOf(node, ctx, element, spec.common); - return ui::keyValue(std::move(spec)); - } - if (kind == "emptyState") { - EmptyState spec{.title = kit.textProp("title"), .text = kit.textProp("text")}; - spec.icon = kit.onceText("icon"); - spec.action = kit.actionPart(); - commonOf(node, ctx, element, spec.common); - return ui::emptyState(std::move(spec)); - } - return std::nullopt; -} - -inline Node ScreenCore::lowerStack(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - std::string_view const kind = node.kind; - KindKit const kit{*this, node, ctx, element}; - int const gap = static_cast(kit.onceInt("gap", 0)); - if (std::string const arrangement = arrangedBy(node.id); !arrangement.empty()) { - return lowerArranged(node, ctx, element, arrangement, kind == "column" ? Axis::Vertical : Axis::Horizontal, - gap); - } - if (kind == "column") { - Column spec{.children = kit.children("children", gap), - .gap = gap, - .align = alignOf(node.name("align")), - .justify = justifyOf(node.name("justify")), - .divided = node.flag("divided"), - .padding = kit.stackPadding()}; - if (node.prop("selected")) { - spec.selected = bindProp(ctx, node.prop("selected"), false, boolOf); - } - commonOf(node, ctx, element, spec.common); - return ui::column(std::move(spec)); - } - Row spec{.children = kit.children("children"), - .gap = gap, - .align = alignOf(node.name("align")), - .justify = justifyOf(node.name("justify")), - .wrap = node.flag("wrap"), - .divided = node.flag("divided"), - .padding = kit.stackPadding()}; - if (node.prop("selected")) { - spec.selected = bindProp(ctx, node.prop("selected"), false, boolOf); - } - commonOf(node, ctx, element, spec.common); - return ui::row(std::move(spec)); -} - -inline Node ScreenCore::lowerGrid(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - KindKit const kit{*this, node, ctx, element}; - Grid spec{.columns = static_cast(kit.onceInt("columns", 1)), - .gap = static_cast(kit.onceInt("gap", 0)), - .align = alignOf(node.name("align")), - .minColumnWidth = static_cast(kit.onceInt("minColumnWidth", 0))}; - for (DocNodePtr const& track : node.partList("tracks")) { - ExprPtr const width = track->prop("width"); - spec.tracks.push_back(GridTrack{.width = width ? sizingOf(once(ctx, width)) : Sizing::stretch(), - .align = cellPlaceNamed(track->name("align")).value_or(Align::Start)}); - } - for (DocNodePtr const& cell : node.nodes("children")) { - ExprPtr const span = cell->prop("span"); - spec.cells.push_back( - GridCell{.node = lower(*cell, ctx), .span = static_cast(span ? intOf(once(ctx, span), 1) : 1)}); - } - commonOf(node, ctx, element, spec.common); - return ui::grid(std::move(spec)); -} - -inline Node ScreenCore::lowerPanel(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - KindKit const kit{*this, node, ctx, element}; - Panel spec{.title = kit.textProp("title"), .padding = static_cast(kit.onceInt("padding", 0))}; - spec.header = kit.child("header"); - spec.child = kit.child("children", static_cast(kit.onceInt("gap", kPanelGap))); - spec.collapsible = kit.onceBool("collapsible", false); - spec.collapsed = bindProp(ctx, node.prop("collapsed"), false, boolOf); - if (Commands const* const commands = node.event("onToggle")) { - spec.onToggle = [this, ctx, commands](bool collapsed) { runEvent(commands, ctx, Value{collapsed}); }; - } - commonOf(node, ctx, element, spec.common); - return ui::panel(std::move(spec)); -} - -inline Node ScreenCore::lowerSplitter(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - KindKit const kit{*this, node, ctx, element}; - ExprPtr const orientation = node.prop("orientation"); - Splitter spec{.children = kit.children("children"), - .orientation = orientation && axisOf(once(ctx, orientation)) == Axis::Vertical ? Axis::Vertical - : Axis::Horizontal}; - // No `onResize`: a user's drag stays the splitter's own, and the document's sizes are where it starts. - if (ExprPtr const sizes = node.prop("sizes")) { - spec.sizes = bindProp>( - ctx, sizes, {}, [this, path = sizes->path](Value const& value, FormatContext const& /*format*/) { - std::optional> parsed = splitterSizesOf(value); - if (!parsed) { - report(path, "sizes is " + canonicalJson(value) + "; sizes is a list of numbers, one per pane"); - } - return std::move(parsed).value_or(std::vector{}); - }); - } - commonOf(node, ctx, element, spec.common); - // A literal `sizes` that matches the panes places them, so a pane's own width is not used. - if (ExprPtr const sizes = node.prop("sizes"); sizes && sizes->kind == ExprKind::Literal) { - std::optional> const given = splitterSizesOf(sizes->literal); - if (given && given->size() == spec.children.size()) { - for (std::size_t at = 0; at < spec.children.size(); ++at) { - // A stretch pane asks only to fill, which `sizes` leaves it to do; a fixed or percent pane names a - // size. - Sizing::Kind const kind = layoutHintsOf(spec.children.at(at)).width.kind; - if (spec.orientation == Axis::Horizontal && - (kind == Sizing::Kind::Fixed || kind == Sizing::Kind::Percent)) { - report(sizes->path, "this splitter's `sizes` places its panes; pane " + std::to_string(at) + - "'s sizing is not used"); - } - } - } - } - return ui::splitter(std::move(spec)); -} - -inline void ScreenCore::reportActionBarGaps(DocNode const& bar, LowerCtx const& ctx) { - for (DocNodePtr const& child : bar.nodes("children")) { - if (child->kind != "forEach" || child->prop("gap") == nullptr) { - continue; - } - ExprPtr const axis = child->prop("axis"); - if (axis != nullptr && axis->kind != ExprKind::Literal && axisOf(once(ctx, axis)) == Axis::Horizontal) { - report(child->path + "/gap", kActionBarGapRefusal); - } - } -} - -inline Node ScreenCore::lowerCollapsible(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - KindKit const kit{*this, node, ctx, element}; - Collapsible spec{.title = kit.textProp("title"), .open = bindProp(ctx, node.prop("open"), true, boolOf)}; - if (Commands const* const commands = node.event("onToggle")) { - spec.onToggle = [this, ctx, commands](bool open) { runEvent(commands, ctx, Value{open}); }; - } - spec.header = kit.child("header"); - spec.child = kit.child("children", static_cast(kit.onceInt("gap", kPanelGap))); - commonOf(node, ctx, element, spec.common); - return ui::collapsible(std::move(spec)); -} - -inline Node ScreenCore::lowerDropZone(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - KindKit const kit{*this, node, ctx, element}; - DropZone spec; - spec.accept = stringsOf(node.prop("accept") ? once(ctx, node.prop("accept")) : Value{}); - spec.multiple = kit.onceBool("multiple", false); - if (Commands const* const commands = node.event("onDrop")) { - spec.onDrop = [this, ctx, commands](std::vector const& paths) { - runEvent(commands, ctx, listOfStrings(paths)); - }; - } - spec.child = kit.child("children"); - commonOf(node, ctx, element, spec.common); - return ui::dropZone(std::move(spec)); -} - -inline Node ScreenCore::lowerPage(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - KindKit const kit{*this, node, ctx, element}; - Page spec; - spec.geometry = pageGeometryOf(node); - std::optional const outer = std::exchange(pageBeingLowered, spec.geometry); - spec.children = kit.children("children"); - pageBeingLowered = outer; - commonOf(node, ctx, element, spec.common); - return ui::page(std::move(spec)); -} - -inline Node ScreenCore::lowerPageRegion(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - if (!pageBeingLowered) { - report(node.path, "a page region belongs in a page"); - return ui::text(Text{.text = std::string{}, .role = TextRole::Muted}); - } - KindKit const kit{*this, node, ctx, element}; - PageRegion spec; - spec.geometry = regionGeometryOf(node, *pageBeingLowered); - std::optional const outer = std::exchange(pageBeingLowered, std::nullopt); - spec.children = kit.children("children"); - pageBeingLowered = outer; - commonOf(node, ctx, element, spec.common); - return ui::pageRegion(std::move(spec)); -} - -inline Node ScreenCore::lowerLocaleScope(DocNode const& node, LowerCtx const& ctx) { - auto holder = std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); - holder->transparent = true; - ExprPtr const locale = node.prop("locale"); - holder->localeFormat = &holder->nodes.computed([this, scope = ctx.scope, bindings = ctx.bindings, - locale]() -> std::shared_ptr { - Value const value = evalIn(*scope, bindings.get(), locale); - std::string const* const tag = value.asString(); - if (tag == nullptr && !value.isNull()) { - report(locale->path, "the locale is " + canonicalJson(value) + "; a locale is a BCP 47 tag, a string"); - } - if (tag == nullptr || tag->empty()) { - return session.sharedFormatting(); - } - if (session.firstUnlistedLocale(*tag)) { - report(locale->path, "no formatting facts for locale `" + *tag + "`; numbers, money and dates use en's"); - } - return session.scopedFormatting(*tag); - }); - // The children are mounted again whenever the tag changes: a value a node reads once, as it is lowered (a - // table's column labels, a `once` property, a literal), is written in the facts at that moment, and only a new - // lowering writes it in the new ones. The key is the tag as the scope resolves it; a tag that is not known yet - // is the key `""`, apart from every tag. - std::vector content; - for (DocNodePtr const& child : node.nodes("children")) { - content.push_back(child.get()); - } - LayoutHints const hints = holderHints(content, nullptr, ctx); - Switch spec; - spec.selector = slotProp([scope = ctx.scope, bindings = ctx.bindings, locale] { - Value const value = evalIn(*scope, bindings.get(), locale); - std::string const* const tag = value.asString(); - return Key{tag == nullptr ? std::string{} : *tag}; - }); - spec.fallback = lazy( - [this, ctx, holder, content, path = node.path]() -> Node { - auto inner = std::make_shared(*this, holder, nullptr, holder->nodes.depth() + 2); - inner->transparent = true; - LowerCtx const innerCtx{.scope = inner, .bindings = ctx.bindings, .boundary = ctx.boundary, .listGap = 0}; - std::vector children; - children.reserve(content.size()); - for (DocNode const* const child : content) { - children.push_back(lower(*child, innerCtx)); - } - fillHolder(children, path); - return holding(std::move(children), inner, {}, 0); - }, - hints); - commonOf(node, ctx, nullptr, spec.common); - return ui::switchOf(std::move(spec)); -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of ui/1. -inline Node ScreenCore::lowerKind(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - std::string_view const kind = node.kind; - KindKit const kit{*this, node, ctx, element}; - if (std::optional widget = lowerWidget(node, ctx, element)) { - return std::move(*widget); - } - if (kind == "group") { - return lowerGroup(node, ctx, element, kit.children("children")); - } - if (kind == "column" || kind == "row") { - return lowerStack(node, ctx, element); - } - if (kind == "grid") { - return lowerGrid(node, ctx, element); - } - if (kind == "spacer") { - Spacer spec; - commonOf(node, ctx, element, spec.common); - return ui::spacer(std::move(spec)); - } - if (kind == "panel") { - return lowerPanel(node, ctx, element); - } - if (kind == "scroll") { - ExprPtr const axis = node.prop("axis"); - Scroll spec{.child = kit.child("children"), .axis = axis ? axisOf(once(ctx, axis)) : Axis::Vertical}; - commonOf(node, ctx, element, spec.common); - return ui::scroll(std::move(spec)); - } - if (kind == "switch") { - return lowerSwitch(node, ctx); - } - if (kind == "tabs") { - return lowerTabs(node, ctx, element); - } - if (kind == "dialog" || kind == "drawer") { - return lowerDialog(node, ctx, element); - } - if (kind == "busy") { - Busy spec{.active = bindProp(ctx, node.prop("active"), false, boolOf), .label = kit.textProp("label")}; - commonOf(node, ctx, element, spec.common); - return ui::busy(std::move(spec)); - } - if (kind == "forEach" || kind == "table") { - return lowerRows(node, ctx, element); - } - if (std::optional display = lowerDisplay(node, ctx, element)) { - return std::move(*display); - } - if (kind == "splitter") { - return lowerSplitter(node, ctx, element); - } - if (kind == "collapsible") { - return lowerCollapsible(node, ctx, element); - } - if (kind == "dropZone") { - return lowerDropZone(node, ctx, element); - } - if (kind == "actionBar") { - KindKit const bar{*this, node, ctx, element}; - ActionBar spec{.children = bar.children("children"), - .align = alignOf(node.name("align")), - .justify = justifyOf(node.name("justify")), - .wrap = node.flag("wrap")}; - reportActionBarGaps(node, ctx); - commonOf(node, ctx, element, spec.common); - return ui::actionBar(std::move(spec)); - } - if (kind == "page") { - return lowerPage(node, ctx, element); - } - if (kind == "pageRegion") { - return lowerPageRegion(node, ctx, element); - } - if (kind == "localeScope") { - return lowerLocaleScope(node, ctx); - } - if (kind == "boundary") { - return lowerBoundary(node, ctx); - } - if (kind == "custom") { - return lowerCustom(node, ctx); - } - if (kind == "customize") { - return lowerCustomize(node, ctx); - } - if (kind == "form") { - return lowerForm(node, ctx, element); - } - if (kind == "collection" || kind == "wizard") { - return lowerComposite(node, ctx, element); - } - report(node.path, "`" + node.kind + "` is a node kind this interpreter does not lower"); - return ui::text(Text{.text = std::string{node.kind}, .role = TextRole::Muted}); -} - -/// @brief A document field overlay's expressions, evaluated once, as the engine's overlay. -/// @param scope The scope the form is declared in. -/// @param part The `fields` entry. -/// @param format How values read as text and numbers. -/// @return The overlay. -[[nodiscard]] inline forms::FieldOverlay overlayOf(RtScope const& scope, DocNode const& part, - FormatContext const& format) { - auto const read = [&](std::string_view key) -> std::optional { - ExprPtr const expr = part.prop(key); - if (!expr) { - return std::nullopt; - } - return scope.core.runtime().untracked([&] { return evalIn(scope, nullptr, expr); }); - }; - auto const text = [&](std::string_view key) -> std::optional { - auto const value = read(key); - return value.has_value() && !value->isNull() ? std::optional{textOf(*value, format)} - : std::nullopt; - }; - auto const flag = [&](std::string_view key) { - auto const value = read(key); - bool const* const set = value.has_value() ? value->asBool() : nullptr; - return set != nullptr && *set; - }; - forms::FieldOverlay overlay{.omit = flag("omit"), .hidden = flag("hidden")}; - overlay.label = text("label"); - overlay.unit = text("unit"); - overlay.widget = text("widget"); - if (auto const decimals = read("decimals"); - decimals.has_value() && decimals->asInt() != nullptr && *decimals->asInt() >= 0) { - overlay.decimals = static_cast(std::min(*decimals->asInt(), 18)); - } - if (auto const blankAs = text("blankAs")) { - overlay.blankAs = *blankAs == "empty" ? forms::BlankAs::Empty : forms::BlankAs::Omit; - } - return overlay; -} - -/// @brief A lowering context whose scope is held weakly: what an Effect the scope itself owns may keep, so the scope -/// does not keep itself alive. -struct DetachedLower { - /// @brief The scope, weakly. - std::weak_ptr scope; - /// @brief The names bound there. - std::shared_ptr bindings; - /// @brief The innermost boundary. - std::shared_ptr boundary; -}; - -/// @brief Detaches a lowering context's scope. -/// @param ctx The context. -/// @return The context, its scope held weakly. -[[nodiscard]] inline DetachedLower detachedLower(LowerCtx const& ctx) { - return DetachedLower{.scope = ctx.scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; -} - -/// @brief Puts a detached context's scope back. -/// @param held The detached context. -/// @return The context; its scope is null once the scope is gone. -[[nodiscard]] inline LowerCtx attached(DetachedLower const& held) { - return LowerCtx{.scope = held.scope.lock(), .bindings = held.bindings, .boundary = held.boundary}; -} - -// Builds the form's session when its element is declared, so its values can be read before the form is drawn. -inline void ScreenCore::wireForm(ElementState& element) { - DocNode const& node = *element.node; - RtScope& scope = *element.scope; - std::string const action{node.name("action")}; - Catalog const& catalog = session.options().catalog; - std::optional const schema = catalog.schema ? catalog.schema(action) : std::nullopt; - if (!schema.has_value()) { - report(node.path, "no schema for `" + action + "`: the catalog has none for a `form` to build from"); - return; - } - NameRef const* const alias = scope.find(node.name("model")); - if (alias == nullptr || alias->model == nullptr) { - report(node.path, "`" + std::string{node.name("model")} + "` is not a model alias"); - return; - } - forms::FieldOverlays overlays; - // `fields` is one record part holding a `field` part per overlaid member. - for (DocNodePtr const& record : node.partList("fields")) { - for (DocNodePtr const& part : record->partList("fields")) { - forms::FieldOverlay overlay = overlayOf(scope, *part, session.formatting()); - // A computed `decimals` is carried by the effect below alone: baking the value read now would make it - // the fallback when the expression later gives no places, where the schema's places belong. - if (ExprPtr const places = part->prop("decimals"); places && places->kind != ExprKind::Literal) { - overlay.decimals.reset(); - } - overlays.insert_or_assign(part->id, std::move(overlay)); - } - } - auto model = forms::FormModel::fromSchema(action, *schema, overlays); - if (!model) { - report(node.path, - "the form of `" + action + "` does not build: " + model.error().path + ": " + model.error().message); - return; - } - if (node.name("submit") == "explicit") { - model = model->withSubmitMode(forms::SubmitMode::Explicit); - } else if (node.name("submit") == "auto") { - model = model->withSubmitMode(forms::SubmitMode::Automatic); - } - element.form = std::make_unique(runtime(), *std::move(model), aliasSubmits(alias->model), - aliasCalls(alias->model), engineOptions()); - // An overlay's `decimals` follows its expression: the field keeps the draft as typed and checks it again against - // the places the expression gives now. - for (DocNodePtr const& record : node.partList("fields")) { - for (DocNodePtr const& part : record->partList("fields")) { - ExprPtr const places = part->prop("decimals"); - if (!places) { - continue; - } - forms::FieldState* state = nullptr; - try { - state = &element.form->field(part->id); - } catch (std::out_of_range const&) { - continue; // The overlay names a field the form does not have (an omitted one). - } - scope.nodes.effect([this, &scope, places, state] { - int const now = placesOf(evalIn(scope, nullptr, places), session.formatting()); - runtime().untracked([&] { - state->places().set(now >= 0 ? std::optional{static_cast(now)} - : std::nullopt); - }); - }); - } - } - if (ExprPtr const prefill = node.prop("prefill")) { - // A prefill follows its expression. A value of the record being edited (the first value, or one under the - // same `key`) keeps the fields the user changed; another record, a new `key`, or any later value of a form - // without one, loads every field. - forms::FormSession* const form = element.form.get(); - struct Followed { - bool loaded = false; - Value key; - }; - auto const followed = std::make_shared(); - scope.nodes.effect([this, &scope, prefill, key = node.prop("key"), form, followed] { - Value const value = evalIn(scope, nullptr, prefill); - if (value.isNull()) { - return; - } - runtime().untracked([&] { - Value const current = key ? evalIn(scope, nullptr, key) : Value{}; - bool const same = !followed->loaded || (key && current == followed->key); - followed->loaded = true; - followed->key = current; - std::string const json = glz::write_json(valueToJson(value)).value_or(std::string{}); - if (same) { - form->refill(json); - } else { - form->prefill(json); - } - }); - }); - } -} - -inline Node ScreenCore::lowerForm(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - forms::FormSession* const form = element == nullptr ? nullptr : element->form.get(); - if (form == nullptr) { - return ui::text(Text{.text = std::string{node.name("action")}, .role = TextRole::Muted}); - } - // The form's events, each run once per change of the count it watches. - auto const watch = [this, &ctx](Commands const* commands, auto count, auto payload) { - if (commands == nullptr || commands->empty()) { - return; - } - auto const seen = std::make_shared(runtime().untracked(count)); - ctx.scope->nodes.effect([this, held = detachedLower(ctx), commands, count, payload, seen] { - std::uint64_t const now = count(); - if (now == *seen) { - return; - } - *seen = now; - runtime().untracked([&] { runEvent(commands, attached(held), payload()); }); - }); - }; - watch( - node.event("onSubmit"), [form] { return form->submitAttempts(); }, - [form] { - std::optional const body = form->body(); - return body.has_value() ? jsonTextValue(*body) : Value{}; - }); - watch( - node.event("onSuccess"), [form] { return form->successCount(); }, - [form] { - std::optional const& reply = form->lastReply(); - return reply.has_value() ? jsonTextValue(*reply) : Value{}; - }); - if (Commands const* const onError = node.event("onError"); onError != nullptr && !onError->empty()) { - // Each failure is a new exception: run once per failure, with its text. - auto const seen = - std::make_shared(runtime().untracked([form] { return form->lastError(); })); - ctx.scope->nodes.effect([this, held = detachedLower(ctx), onError, form, seen] { - std::exception_ptr const error = form->lastError(); - if (error == nullptr || error == *seen) { - return; - } - *seen = error; - runtime().untracked([&] { runEvent(onError, attached(held), Value{failureText(error)}); }); - }); - } - forms::FormViewOptions options{.showTitle = false}; - presentForm(node, ctx, options); - options.title = bindProp(ctx, node.prop("title"), std::string{}, stringOf); - // A field whose overlay names a component is drawn by it; only top-level fields take one, as every overlay. - for (DocNodePtr const& record : node.partList("fields")) { - for (DocNodePtr const& overlay : record->partList("fields")) { - if (!overlay->name("component").empty()) { - options.overrides.byField(overlay->id, - [this, ctx, field = overlay.get()](forms::FieldView const& view) { - return fieldComponent(view, *field, ctx); - }); - } - } - } - Column column{.children = {forms::formView(*form, std::move(options))}}; - commonOf(node, ctx, element, column.common); - return ui::column(std::move(column)); -} - -/// @brief A component's `change` payload as the wire value of the field it draws, read as the `value` prop's -/// declared type. -/// @param payload The payload, as the backend reports it. -/// @param type The `value` prop's type. -/// @return The wire value, or why the payload is not one. -[[nodiscard]] inline std::expected changeWire(std::string const& payload, - std::string_view type) { - std::string_view text{payload}; - if (type == "string") { - if (text.starts_with("s:")) { - text.remove_prefix(2); - } - // Parentheses: braces would pick the initializer-list constructor and make a one-element array. - return forms::detail::engine::Json(std::string{text}); - } - if (text.starts_with("i:")) { - text.remove_prefix(2); - } - std::optional json = forms::detail::engine::parseJson(text); - if (!json) { - return std::unexpected(std::string{"it is not JSON"}); - } - bool const fits = type == "json" || json->is_null() || (type == "bool" && json->is_boolean()) || - ((type == "int" || type == "number") && json->is_number()) || - (type == "exact" && (json->is_number() || json->is_string())); - if (!fits) { - bool const vowel = type == "int" || type == "exact"; - return std::unexpected("it is not " + std::string{vowel ? "an " : "a "} + std::string{type}); - } - return *std::move(json); -} - -/// @brief What a form fills of a field component's props: the field's value, errors, read-only and required state, -/// and label, each a tracked read of the field. -/// @param prop The prop's name. -/// @param state The field. -/// @return The read, or empty for a prop the form does not fill. -[[nodiscard]] inline std::function formFilled(std::string const& prop, forms::FieldState* state) { - if (prop == "value") { - return [state] { - forms::Encoding const& encoding = state->encoded().get(); - if (!encoding.has_value() || !encoding->has_value()) { - return Value{}; - } - return (*encoding)->value.isNull() ? jsonTextValue((*encoding)->json) : (*encoding)->value; - }; - } - if (prop == "errors") { - return [state] { - std::optional const& error = state->error().get(); - return error.has_value() ? Value{ValueList{Value{error->message}}} : Value{ValueList{}}; - }; - } - if (prop == "readonly") { - return [state] { return Value{state->readonly().get()}; }; - } - if (prop == "required") { - return [state] { return Value{state->required().get()}; }; - } - if (prop == "label") { - return [state] { return Value{state->label()}; }; - } - return {}; -} - -// NOLINTNEXTLINE(bugprone-easily-swappable-parameters): a prop's name, then its declared type. -inline CustomProp ScreenCore::componentProp(std::string const& prop, std::string const& type, - std::function read) { - if (type == "bool") { - return CustomProp{.name = prop, .value = slotProp([this, read = std::move(read)] { - return boolOf(read(), session.formatting()); - })}; - } - if (type == "number") { - return CustomProp{.name = prop, - .value = slotProp([read = std::move(read)] { return componentNumber(read()); })}; - } - return CustomProp{.name = prop, .value = slotProp([this, read = std::move(read), type] { - return componentText(read(), type, session.formatting()); - })}; -} - -inline void ScreenCore::changeField(forms::FieldState& state, forms::FieldSpec const& spec, std::string const& path, - std::string_view valueType, std::string const& payload) { - auto wire = changeWire(payload, valueType); - // A base64 member holds a file's bytes, which a document moves inline only under the session's cap. - if (std::size_t const cap = session.options().maxInlineFileBytes; - wire && spec.bytes && wire->is_string() && base64Size(wire->get_string()) > cap) { - report(path, "field " + spec.name + ": " + std::to_string(base64Size(wire->get_string())) + - " bytes is over the " + std::to_string(cap) + " inline cap"); - return; - } - if (wire) { - if (auto edited = state.edit(*wire); !edited) { - wire = std::unexpected(edited.error()); - } - } - if (!wire) { - report(path, "field " + spec.name + ": the component's change does not decode: " + wire.error()); - } -} - -inline Node ScreenCore::fieldComponent(forms::FieldView const& view, DocNode const& overlay, LowerCtx const& ctx) { - std::string const name{overlay.name("component")}; - // A loaded document's field component is declared, with a `value` prop and a `change` event. - Component const& component = _doc->components.at(name); - forms::FieldState* const state = &view.state(); - Custom spec{.name = name, - .fallback = view.defaultControl(), - .props = {}, - .minVersion = - static_cast(std::clamp(component.version, 0, std::numeric_limits::max())), - .onEvent = {}}; - for (auto const& [prop, type] : component.props) { - if (prop == "value" && type == "json") { - // The wire JSON itself, so an object's or a collection's every digit reaches the component. - spec.props.push_back(CustomProp{.name = prop, .value = slotProp([state] { - forms::Encoding const& encoding = state->encoded().get(); - return encoding.has_value() && encoding->has_value() - ? (*encoding)->json - : std::string{"null"}; - })}); - continue; - } - std::function read = formFilled(prop, state); - if (!read) { - ExprPtr given; - for (DocNodePtr const& record : overlay.partList("props")) { - if (ExprPtr const expr = record->prop(prop)) { - given = expr; - } - } - read = [scope = ctx.scope, bindings = ctx.bindings, given] { - return given ? evalIn(*scope, bindings.get(), given) : Value{}; - }; - } - spec.props.push_back(componentProp(prop, type, std::move(read))); - } - spec.onEvent = [this, state, path = overlay.path, fieldSpec = &view.spec(), - valueType = component.props.at("value")](std::string const& event, std::string const& payload) { - if (event == "change") { - changeField(*state, *fieldSpec, path, valueType, payload); - } - }; - return ui::custom(std::move(spec)); -} - -// Every call goes through the alias's channel, bound for its current instance when the call is made. -inline forms::Submitter ScreenCore::aliasCalls(ModelAlias* alias) { - return [this, alias](std::string_view actionId, std::string const& body) -> async::Completion { - std::shared_ptr const channel = channelOf(*alias, *this); - if (channel == nullptr) { - auto [failed, promise] = async::Completion::makeSettleable(&runtime().owner()); - promise.reject(std::make_exception_ptr(std::runtime_error{"the node's model alias is not bound"})); - return std::move(failed); - } - return channel->execute(std::string{actionId}, body, CallOptions{}); - }; -} - -// The calls of a form, collection or wizard: a success other than of @p read, the collection's own query, tells the -// session, which applies the action's effects, as a mutation's success does. -inline forms::Submitter ScreenCore::aliasSubmits(ModelAlias* alias, std::string read) { - return [this, alias, call = aliasCalls(alias), read = std::move(read)]( - std::string_view actionId, std::string body) -> async::Completion { - async::Completion completion = call(actionId, std::move(body)); - if (actionId != read) { - completion.then([this, alive = std::weak_ptr{_alive}, alias, typeId = alias->decl->type, - action = std::string{actionId}](std::string const& reply) { - if (alive.expired()) { - return; - } - auto json = parseJson(reply); - auto value = json ? valueFromJson(*json) : std::unexpected(json.error()); - std::string const token = runtime().untracked([&] { return alias->token->get(); }); - session.actionSucceeded(typeId, action, value ? *value : Value{}, ReplyUse::Applied, token); - }); - } - return completion; - }; -} - -// The session's locale, translations, display zone and date patterns, as every form the engine builds here reads them. -inline forms::FormSessionOptions ScreenCore::engineOptions() const { - FormatContext const& format = session.formatting(); - forms::FormSessionOptions options{}; - options.locale = withoutGrouping(format.numeric); - options.bcp47 = format.locale; - options.translations = format.translations; - options.displayOffsetMinutes = format.utcOffsetMinutes; - options.datePattern = format.datePattern; - options.dateTimePattern = format.dateTimePattern; - return options; -} - -// Builds a collection's or wizard's session when its element is declared. The node's `action` is the collection's -// query or the wizard's first step; the catalog answers the document for it, and every call (the query, the actions, -// every step's submission) goes through the node's model alias. -inline void ScreenCore::wireComposite(ElementState& element) { - DocNode const& node = *element.node; - RtScope const& scope = *element.scope; - bool const collection = node.kind == "collection"; - std::string const action{node.name("action")}; - Catalog const& catalog = session.options().catalog; - auto const& lookup = collection ? catalog.view : catalog.wizard; - std::optional const document = lookup ? lookup(action) : std::nullopt; - if (!document.has_value()) { - report(node.path, std::string{"no "} + (collection ? "view" : "wizard") + " document for `" + action + - "`: the catalog has none for a `" + node.kind + "` to build from"); - return; - } - NameRef const* const alias = scope.find(node.name("model")); - if (alias == nullptr || alias->model == nullptr) { - report(node.path, "`" + std::string{node.name("model")} + "` is not a model alias"); - return; - } - forms::SchemaLookup const schemas = catalog.schema ? forms::SchemaLookup{catalog.schema} : forms::SchemaLookup{}; - forms::Submitter const call = aliasCalls(alias->model); - if (collection) { - auto model = forms::CollectionModel::fromSchema(*document); - if (!model) { - report(node.path, "the collection of `" + action + "` does not build: " + model.error().path + ": " + - model.error().message); - return; - } - if (model->query() != action) { - report(node.path, "the view document of `" + action + "` lists `" + std::string{model->query()} + "`"); - return; - } - std::string query{model->query()}; - element.collection = std::make_unique(runtime(), *std::move(model), schemas, - aliasSubmits(alias->model, std::move(query)), - call, engineOptions()); - return; - } - // The wizard's id, the stem of its translation keys, is the action it starts with. - auto model = forms::WizardModel::fromSchema(action, *document); - if (!model) { - report(node.path, - "the wizard of `" + action + "` does not build: " + model.error().path + ": " + model.error().message); - return; - } - if (model->steps().front().action != action) { - report(node.path, - "the wizard document of `" + action + "` starts with `" + model->steps().front().action + "`"); - return; - } - try { - element.wizard = std::make_unique(runtime(), *std::move(model), schemas, - aliasSubmits(alias->model), call, engineOptions()); - } catch (std::invalid_argument const& error) { - report(node.path, error.what()); - } -} - -// The presentation keys a form, a collection and a wizard share, but the title: the label of the explicit-mode button -// and the status line naming it, bound in the node's scope; whether the status line shows, the grid's columns and the -// field layout and the inline caption column's width, as read at load. -inline void ScreenCore::presentForm(DocNode const& node, LowerCtx const& ctx, forms::FormViewOptions& options) { - if (ExprPtr const label = node.prop("submitLabel")) { - options.submitLabel = bindProp(ctx, label, std::string{}, stringOf); - } - if (auto const shown = node.flags.find("showStatus"); shown != node.flags.end()) { - options.showStatus = shown->second; - } - if (ExprPtr const columns = node.prop("columns"); columns != nullptr && columns->literal.asInt() != nullptr) { - options.gridColumns = static_cast(*columns->literal.asInt()); - options.flatGridColumns = options.gridColumns; - } - if (node.name("fieldLayout") == "inline") { - options.fieldLayout = forms::FieldLayout::Inline; - } - // The loader has checked `captionWidth` is a literal integer. - if (ExprPtr const width = node.prop("captionWidth")) { - options.inlineLabelWidth = static_cast(*width->literal.asInt()); - } -} - -inline Node ScreenCore::lowerComposite(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - // The editor's and the steps' titles are the dialog's and the header's; the forms do not repeat them. A `title` - // replaces the view's own heading. - forms::FormViewOptions form{}; - form.showTitle = false; - presentForm(node, ctx, form); - Prop title = bindProp(ctx, node.prop("title"), std::string{}, stringOf); - Node view; - if (element != nullptr && element->collection != nullptr) { - forms::CollectionViewOptions options{}; - options.form = std::move(form); - options.title = std::move(title); - view = forms::collectionView(*element->collection, std::move(options)); - } else if (element != nullptr && element->wizard != nullptr) { - forms::WizardViewOptions options{}; - options.form = std::move(form); - options.title = std::move(title); - view = forms::wizardView(*element->wizard, options); - } else { - return ui::text(Text{.text = std::string{node.name("action")}, .role = TextRole::Muted}); - } - Column column{.children = {std::move(view)}}; - commonOf(node, ctx, element, column.common); - return ui::column(std::move(column)); -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): an overlay's scope, content, actions and keys are one lowering. -// NOLINTNEXTLINE(readability-function-cognitive-complexity): an overlay's scope, content, actions and keys are one lowering. -inline Node ScreenCore::lowerDialog(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - Prop open = node.prop("open") ? bindProp(ctx, node.prop("open"), false, boolOf) - : slotProp([element] { return element->open.get(); }); - std::vector bodyContent; - for (DocNodePtr const& child : node.nodes("children")) { - bodyContent.push_back(child.get()); - } - int const bodyGap = - node.prop("gap") ? static_cast(intOf(once(ctx, node.prop("gap")), kDialogGap)) : kDialogGap; - LayoutHints const bodyHints = holderHints(bodyContent, node.scope ? &*node.scope : nullptr, ctx); - Node body = lazy( - [this, ctx, &node, element, bodyGap]() -> Node { - auto inner = std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); - inner->owner = element; - addPending(1); - inner->submitted = &element->submitted; - inner->showErrors = std::string{node.name("showErrors")}; - std::vector content; - for (DocNodePtr const& child : node.nodes("children")) { - content.push_back(child.get()); - } - std::vector lists; - for (std::string_view const key : {"default", "cancel"}) { - if (Commands const* const commands = node.event(key)) { - lists.push_back(commands); - } - } - for (DocNodePtr const& action : node.partList("actions")) { - if (Commands const* const commands = action->event("onClick")) { - lists.push_back(commands); - } - } - declare(*inner, node.scope ? &*node.scope : nullptr, content, lists); - element->inner.set(inner.get()); - LowerCtx const innerCtx{ - .scope = inner, .bindings = ctx.bindings, .boundary = ctx.boundary, .listGap = bodyGap}; - std::vector children; - children.reserve(content.size()); - for (DocNode const* const child : content) { - children.push_back(lower(*child, innerCtx)); - } - // The overlay's actions end its scoped content, so they bind in its scope; the mount puts them in its - // footer. - if (ActionModels actions = lowerActionParts(node.partList("actions"), innerCtx); !actions.empty()) { - children.push_back(actionBarOf(std::move(actions))); - } - std::vector keys; - if (Commands const* const commands = node.event("default")) { - keys.push_back(KeyBinding{.chord = "Enter", .onPress = [this, innerCtx, commands] { - runEvent(commands, innerCtx, Value{}); - }}); - } - if (Commands const* const commands = node.event("cancel")) { - keys.push_back(KeyBinding{ - .chord = "Esc", .onPress = [this, innerCtx, commands] { runEvent(commands, innerCtx, Value{}); }}); - } - fillHolder(children, node.path); - return holding(std::move(children), inner, std::move(keys), bodyGap); - }, - bodyHints); - Action onDismiss = [this, ctx, element, commands = node.event("onDismiss")] { - session.asUser([&] { - session.noteWrite(); - element->open.set(false); - }); - runEvent(commands, ctx, Value{}); - }; - if (node.kind == "drawer") { - ExprPtr const side = node.prop("side"); - Drawer spec{ - .open = std::move(open), - .title = bindProp(ctx, node.prop("title"), std::string{}, stringOf), - .description = bindProp(ctx, node.prop("description"), std::string{}, stringOf), - .child = std::move(body), - .onDismiss = std::move(onDismiss), - .side = side && textOf(once(ctx, side), ctx.scope->formatting()) == "start" ? Side::Start : Side::End}; - if (ExprPtr const spans = node.prop("descriptionSpans")) { - spec.descriptionSpans = spansProp(ctx, spans); - } - commonOf(node, ctx, element, spec.common); - return ui::drawer(std::move(spec)); - } - Dialog spec{.open = std::move(open), - .title = bindProp(ctx, node.prop("title"), std::string{}, stringOf), - .description = bindProp(ctx, node.prop("description"), std::string{}, stringOf), - .child = std::move(body), - .onDismiss = std::move(onDismiss), - .common = {}, - .sheet = bindProp(ctx, node.prop("sheet"), false, boolOf), - .dismissLabel = bindProp(ctx, node.prop("dismissLabel"), std::string{"Close"}, stringOf)}; - if (ExprPtr const spans = node.prop("descriptionSpans")) { - spec.descriptionSpans = spansProp(ctx, spans); - } - commonOf(node, ctx, element, spec.common); - return ui::dialog(std::move(spec)); -} - -inline Node ScreenCore::lowerSwitch(DocNode const& node, LowerCtx const& ctx) { - std::vector whens; - Switch spec; - std::int64_t index = 0; - for (DocNodePtr const& part : node.partList("cases")) { - whens.push_back(part->prop("when")); - DocNode const* const casePart = part.get(); - std::vector caseContent; - for (DocNodePtr const& child : casePart->nodes("children")) { - caseContent.push_back(child.get()); - } - LayoutHints const caseHints = holderHints(caseContent, casePart->scope ? &*casePart->scope : nullptr, ctx); - spec.cases.push_back(SwitchCase{ - .key = Key{index++}, - .node = lazy( - [this, ctx, casePart, caseGap = ctx.listGap]() -> Node { - auto inner = std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); - std::vector content; - for (DocNodePtr const& child : casePart->nodes("children")) { - content.push_back(child.get()); - } - declare(*inner, casePart->scope ? &*casePart->scope : nullptr, content, {}); - LowerCtx const innerCtx{ - .scope = inner, .bindings = ctx.bindings, .boundary = ctx.boundary, .listGap = caseGap}; - std::vector children; - children.reserve(content.size()); - for (DocNode const* const child : content) { - children.push_back(lower(*child, innerCtx)); - } - fillHolder(children, casePart->path); - return holding(std::move(children), inner, {}, caseGap); - }, - caseHints)}); - } - spec.selector = slotProp( - [scope = ctx.scope, bindings = ctx.bindings, selected = node.prop("on"), whens = std::move(whens)] { - Value const value = evalIn(*scope, bindings.get(), selected); - for (std::size_t at = 0; at < whens.size(); ++at) { - if (evalIn(*scope, bindings.get(), whens.at(at)) == value) { - return Key{static_cast(at)}; - } - } - return Key{std::int64_t{-1}}; - }); - auto const fallback = node.nodes("default"); - spec.fallback = fallback.empty() ? Node{} : lowerAll(fallback, ctx, ctx.listGap); - commonOf(node, ctx, nullptr, spec.common); - return ui::switchOf(std::move(spec)); -} - -// The tab a bound `selected` names. A value that names no tab shows the first, and is reported once. -inline Prop ScreenCore::controlledTabSelection(DocNode const& node, LowerCtx const& ctx, - ExprPtr const& selected, - std::shared_ptr> const& ids) { - auto const unknownReported = std::make_shared(false); - return Prop{[this, scope = ctx.scope, bindings = ctx.bindings, selected, ids, unknownReported, - path = pointerAppend(node.path, "selected")]() -> std::size_t { - Value const value = evalIn(*scope, bindings.get(), selected); - std::string const* const named = value.asString(); - auto const found = named == nullptr ? ids->end() : std::ranges::find(*ids, *named); - if (found != ids->end()) { - return static_cast(std::distance(ids->begin(), found)); - } - if (!*unknownReported) { - *unknownReported = true; - report(path, canonicalJson(value) + " names no tab; the first is shown"); - } - return 0; - }}; -} - -// A document names tabs by id; the view tree by index, so the ids map to indices once. A bound `selected` is the -// controlled index: a pick runs `onChoose` and the page follows `selected` alone. Without it the node keeps the -// user's pick itself, as a bound index too, whose page follows the pick: a constant would move only the highlight. -inline Node ScreenCore::lowerTabs(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - Tabs spec; - auto ids = std::make_shared>(); - for (DocNodePtr const& tab : node.partList("tabs")) { - auto const nodes = tab->nodes("children"); - ids->push_back(tab->id); - spec.tabs.push_back(Tab{.label = bindProp(ctx, tab->prop("label"), std::string{}, stringOf), - .node = nodes.empty() ? Node{} : lowerAll(nodes, ctx)}); - } - spec.moreLabel = bindProp(ctx, node.prop("moreLabel"), std::string{"More"}, stringOf); - if (ExprPtr const inset = node.prop("inset")) { - spec.inset = static_cast(intOf(once(ctx, inset), 0)); - } - if (ExprPtr const pageInset = node.prop("pageInset")) { - spec.pageInset = static_cast(intOf(once(ctx, pageInset), 0)); - } - spec.stripSurface = std::string{node.name("stripSurface")}; - ExprPtr const selected = node.prop("selected"); - Commands const* const onChoose = node.event("onChoose"); - bool const controlled = selected && (selected->kind != ExprKind::Literal || !selected->literal.isNull()); - auto const picked = std::make_shared>(runtime(), std::size_t{0}); - spec.selected = controlled ? controlledTabSelection(node, ctx, selected, ids) - : Prop{[picked] { return picked->get(); }}; - spec.onSelect = [this, ctx, onChoose, ids, picked, controlled, element](std::size_t index) { - if (!controlled) { - picked->set(index); - if (element != nullptr && index < ids->size()) { - element->draft.set(Value{ids->at(index)}); - } - } - if (onChoose != nullptr && index < ids->size()) { - runEvent(onChoose, ctx, Value{ids->at(index)}); - } - }; - commonOf(node, ctx, element, spec.common); - return ui::tabs(std::move(spec)); -} - -// Focuses the declaration the command's target resolved to: of several candidates (cases of one switch), the one -// that is mounted. Each candidate is keyed by the command's own enclosing row keys, as many as enclose the -// candidate; with `row`, the innermost of them is the row's key instead. -inline bool ScreenCore::focusTarget(Command const& command, RtScope const& scope, Bindings const* bindings) { - if (!focusElement) { - return false; - } - auto const found = _doc->focusTargets.find(command.path); - if (found == _doc->focusTargets.end()) { - return focusElement(command.target); - } - FocusPlace const place = focusPlace(scope); - std::optional row; - if (found->second.row) { - Value const value = evalIn(scope, bindings, command.extra); - if (value.isNull()) { - return false; - } - row = canonicalJson(valueOfKey(keyOf(value))); - } - for (FocusCandidate const& candidate : found->second.candidates) { - std::size_t const kept = row ? candidate.rows - 1 : candidate.rows; - if (candidate.rows == 0 && row) { - continue; - } - if (kept > place.rows.size()) { - continue; - } - FocusPlace candidatePlace{ - .prefix = place.prefix, - .rows = {place.rows.begin(), std::next(place.rows.begin(), static_cast(kept))}}; - if (row) { - candidatePlace.rows.push_back(*row); - } - if (focusElement(focusKey(candidatePlace, candidate.path))) { - return true; - } - } - return false; -} - -inline std::shared_ptr ScreenCore::rowScope(DocNode const& node, LowerCtx const& ctx, - reactive::Signal const& row, - std::vector const& content, std::string key) { - auto scope = std::make_shared(*this, ctx.scope, &row, ctx.scope->nodes.depth() + 2); - scope->rowKey = std::move(key); - declare(*scope, node.scope ? &*node.scope : nullptr, content, {}); - return scope; -} - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): a list of rows and a table. -inline Node ScreenCore::lowerRows(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - ExprPtr const rowsExpr = node.prop("rows"); - if (!rowsExpr) { - report(node.path, "a model-backed `table` needs the table engine, which this interpreter does not lower yet"); - return ui::text(Text{.text = std::string{"table"}, .role = TextRole::Muted}); - } - std::function()> rows = [scope = ctx.scope, bindings = ctx.bindings, rowsExpr] { - Value const value = evalIn(*scope, bindings.get(), rowsExpr); - ValueList const* const items = value.asList(); - return items == nullptr ? std::vector{} : std::vector{items->begin(), items->end()}; - }; - auto keyFn = [scope = ctx.scope, bindings = ctx.bindings, keyExpr = node.prop("key")](Value const& row) -> Key { - if (Value const* const heading = row.field(kGroupHeadingField); heading != nullptr && heading->asString()) { - return Key{*heading->asString()}; - } - if (!keyExpr) { - Value const rowKey = rowId(row); - return keyOf(rowKey.isNull() ? row : rowKey); - } - ScopeEnv const env{*scope, bindings.get(), &row}; - return keyOf(evaluate(*keyExpr, env)); - }; - if (node.kind == "forEach") { - std::vector content; - for (DocNodePtr const& child : node.nodes("children")) { - content.push_back(child.get()); - } - auto rowView = [this, ctx, &node, content, keyFn](reactive::Signal const& row) -> Node { - std::string key = runtime().untracked([&] { return canonicalJson(valueOfKey(keyFn(row.peek()))); }); - auto scope = rowScope(node, ctx, row, content, std::move(key)); - LowerCtx const rowCtx{.scope = scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; - std::vector children; - children.reserve(content.size()); - for (DocNode const* const child : content) { - children.push_back(lower(*child, rowCtx)); - } - return holding(std::move(children), scope); - }; - ExprPtr const axis = node.prop("axis"); - ExprPtr const gap = node.prop("gap"); - Common common; - commonOf(node, ctx, element, common); - Axis const along = axis ? axisOf(once(ctx, axis)) : Axis::Vertical; - bool wrap = node.flag("wrap"); - if (wrap && along != Axis::Horizontal) { - // Only a computed axis gets here: the loader refuses a literal one that is not horizontal. - report(node.path + "/wrap", - "`wrap` fills lines along a row; this `forEach`'s `axis` is not \"horizontal\""); - wrap = false; - } - bool divided = node.flag("divided"); - if (divided && along != Axis::Vertical) { - report(node.path + "/divided", - "`divided` draws rules between rows of a column; this `forEach`'s `axis` is \"horizontal\""); - divided = false; - } - return ui::forEach(std::move(rows), std::move(keyFn), std::move(rowView), along, - gap ? static_cast(intOf(once(ctx, gap), 0)) : 0, common, wrap, divided); - } - // The table's rows, sorted: the element's own view, which its element values read too, unless names bound - // where the table is lowered (a component's `props`) reach its rows, which the element cannot see. - reactive::Computed const* view = element == nullptr ? nullptr : element->view; - if (view != nullptr && ctx.bindings != nullptr && !ctx.bindings->empty()) { - view = &ctx.scope->nodes.computed( - [this, element, bindings = ctx.bindings] { return tableView(*element, bindings.get()); }); - } - if (view != nullptr) { - // The page's rows, each group's heading entry before the first of its rows the page holds, so a group split - // across pages gets its heading on both. - rows = [view] { - TableView const& shown = view->get(); - std::vector entries; - entries.reserve(shown.last - shown.first); - for (std::size_t index = shown.first; index < shown.last; ++index) { - if (!shown.runOf.empty() && - (index == shown.first || shown.runOf.at(index) != shown.runOf.at(index - 1))) { - entries.push_back(shown.runs.at(shown.runOf.at(index))); - } - entries.push_back(shown.rows.at(index)); - } - return entries; - }; - } - std::vector columns; - std::vector cells; - std::vector fields; - // One entry per column, in the same order as `cells`/`fields`. Captured by `cellsOf` below (not `columns` - // itself, which is moved into `ui::table(...)` further down and so cannot be read from inside a lambda - // that outlives this function) so the default-cell closure can apply each column's role to its generated cell. - std::vector roles; - FormatContext const& format = ctx.scope->formatting(); - // The table's `valign` is the default of every column that gives none; the loader checked both names. - Align const tableValign = cellPlaceNamed(node.name("valign")).value_or(Align::Center); - if (ExprPtr const derived = node.prop("columns")) { - Value const list = once(ctx, derived); - // A computed place that names none is reported once for the table, whichever column and key it was. - bool placeReported = false; - auto const placeOf = [&](Value const& item, std::string_view key, Align fallback) { - Value const* const given = item.field(key); - if (given == nullptr || given->isNull()) { - return fallback; - } - std::string const* const name = given->asString(); - std::optional const placed = name == nullptr ? std::nullopt : cellPlaceNamed(*name); - if (!placed && !placeReported) { - placeReported = true; - report(derived->path, "a column's `" + std::string{key} + "` is " + canonicalJson(*given) + - "; a cell's place is start, center or end"); - } - return placed.value_or(fallback); - }; - if (ValueList const* const items = list.asList()) { - for (Value const& item : *items) { - Value const* const field = item.field("id"); - Value const* const label = item.field("label"); - fields.push_back(field == nullptr ? std::string{} : textOf(*field, format)); - columns.push_back( - TableColumn{.label = textOf(label != nullptr ? *label : Value{fields.back()}, format), - .align = placeOf(item, "align", Align::Start), - .valign = placeOf(item, "valign", tableValign)}); - cells.push_back(nullptr); - roles.push_back(TextRole::Normal); - } - } - } - // A part's column index, which a header click reports, counts the derived columns before it. - std::size_t const derivedCount = columns.size(); - for (DocNodePtr const& part : node.partList("columns")) { - ExprPtr const label = part->prop("label"); - ExprPtr const width = part->prop("width"); - ExprPtr const role = part->prop("role"); - TextRole columnRole = TextRole::Normal; - if (role) { - // Read once, with the rest of the column; a value that names no role is reported, as a text's is. - Value const value = once(ctx, role); - std::optional const named = roleNamed(textOf(value, format)); - if (!named) { - report(role->path, "role is " + canonicalJson(value) + "; " + std::string{kRoleNames}); - } - columnRole = named.value_or(TextRole::Normal); - } - bool const shrink = part->flag("shrink"); - Sizing const sized = width ? sizingOf(once(ctx, width)) : Sizing::content(); - if (shrink && sized.kind != Sizing::Kind::Stretch) { - report(part->path + "/shrink", - "`shrink` lets a stretch column go narrower than its header; this column's width does not stretch"); - } - columns.push_back(TableColumn{.label = label ? textOf(once(ctx, label), format) : std::string{}, - .width = sized, - .role = columnRole, - .align = cellPlaceNamed(part->name("align")).value_or(Align::Start), - .valign = cellPlaceNamed(part->name("valign")).value_or(tableValign), - .sortable = part->flag("sortable"), - .wrap = part->flag("wrap", true), - .shrink = shrink && sized.kind == Sizing::Kind::Stretch}); - cells.push_back(part.get()); - fields.emplace_back(part->id); - roles.push_back(columnRole); - } - auto registry = std::make_shared, std::less<>>>(); - // A value that names no tone is reported once for the table, whichever row and value it was. - auto toneReported = std::make_shared(false); - // Likewise for a `rowSpans` value that is no list of spans. - auto spansReported = std::make_shared(false); - auto cellsOf = [this, ctx, &node, cells, fields, roles, registry, keyFn, toneReported, - spansReported](reactive::Signal const& row) { - if (row.peek().field(kGroupHeadingField) != nullptr) { - return headingRow(node, ctx, row, - runtime().untracked([&] { return canonicalJson(valueOfKey(keyFn(row.peek()))); })); - } - std::vector content; - for (DocNode const* const column : cells) { - if (column != nullptr) { - for (DocNodePtr const& cell : column->nodes("cell")) { - content.push_back(cell.get()); - } - } - } - std::string key = runtime().untracked([&] { return canonicalJson(valueOfKey(keyFn(row.peek()))); }); - auto scope = rowScope(node, ctx, row, content, key); - (*registry)[std::move(key)] = scope; - LowerCtx const rowCtx{.scope = scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; - std::vector out; - for (std::size_t index = 0; index < cells.size(); ++index) { - DocNode const* const column = cells.at(index); - auto const nodes = column == nullptr ? std::span{} : column->nodes("cell"); - if (!nodes.empty()) { - out.push_back(lowerAll(nodes, rowCtx)); - continue; - } - out.push_back( - ui::text(Text{.text = slotProp([scope = rowCtx.scope, &row, field = fields.at(index)] { - Value const* const value = row.get().field(field); - return value == nullptr ? std::string{} : textOf(*value, scope->formatting()); - }), - .role = roles.at(index)})); - } - if (!out.empty()) { - // The row's first cell owns the row's scope, which lives as long as the row's node: a cell is placed by - // its column, so the scope is not held by a wrapping container, which the column would place instead. - auto owner = std::make_shared> const>(out.front(), scope); - out.front() = Node{owner, owner->first.get()}; - } - TableRowView rowView{.cells = std::move(out), .tone = std::nullopt}; - // The row's name, in its own scope: what its select box and assistive technology read. - if (ExprPtr const labelExpr = node.prop("rowLabel")) { - rowView.label = bindProp(rowCtx, labelExpr, std::string{}, stringOf); - } - if (ExprPtr const toneExpr = node.prop("rowTone")) { - rowView.tone = slotProp>( - [this, scope, bindings = ctx.bindings, toneExpr, toneReported]() -> std::optional { - return rowToneOf(evalIn(*scope, bindings.get(), toneExpr), toneExpr->path, *toneReported); - }); - } - if (ExprPtr const spansExpr = node.prop("rowSpans")) { - rowView.spans = slotProp>([this, scope, bindings = ctx.bindings, spansExpr, - spansReported, fields] { - return rowSpansOf(evalIn(*scope, bindings.get(), spansExpr), fields, spansExpr->path, *spansReported); - }); - } - return rowView; - }; - TableOptions options; - options.showHeader = node.flag("showHeader", true); - options.selectColumn = node.flag("selectColumn"); - if (ExprPtr const selectAll = node.prop("selectAllLabel")) { - options.selectAllLabel = bindProp(ctx, selectAll, std::string{}, stringOf); - } - if (ExprPtr const threshold = node.prop("virtualizeThreshold")) { - options.virtualize.threshold = - static_cast(std::max(0, intOf(once(ctx, threshold), 2000))); - } - if (ExprPtr const overscan = node.prop("virtualizeOverscan")) { - options.virtualize.overscan = - static_cast(std::max(0, intOf(once(ctx, overscan), 10))); - } - std::string const mode = - node.prop("selectionMode") ? textOf(once(ctx, node.prop("selectionMode")), format) : std::string{}; - options.selectionMode = SelectionMode::None; - if (mode == "single") { - options.selectionMode = SelectionMode::Single; - } else if (mode == "multiple") { - options.selectionMode = SelectionMode::Multiple; - } - // The selection the table shows: the bound `selection`, or the table's own. A slot even for a literal list, so - // a bound selection is fixed until the document writes it, and a user's change the document leaves unwritten - // snaps back. A bound value that is neither a list nor `null` is reported once. - auto selectionReported = std::make_shared(false); - options.selection = slotProp>([this, element, selectionReported, path = node.path] { - std::vector keys; - if (element->bound != nullptr) { - Value const bound = element->bound->get(); - if (!bound.isNull() && bound.asList() == nullptr && !*selectionReported) { - *selectionReported = true; - report(pointerAppend(path, "selection"), - "selection is " + canonicalJson(bound) + "; a table's selection is a list of keys"); - } - } - Value const selection = tableSelection(*element); - if (ValueList const* const items = selection.asList()) { - for (Value const& item : *items) { - keys.push_back(keyOf(item)); - } - } - return keys; - }); - // A user's change: the table's own selection takes it when no key binds one, then `onSelectionChange` runs with - // `event` the new selection, in the table's scope, in the same batch. The backend holds one page: a `Replace` - // is the whole new selection, and an `Extend` keeps the selected keys of the rows on other pages, before the - // reported ones. A key whose row `rows` no longer has drops on any user change. - options.onSelectionChange = [this, ctx, element, view, keyFn, commands = node.event("onSelectionChange")]( - std::vector const& keys, SelectionChange change) { - ValueList items; - if (change == SelectionChange::Extend && view != nullptr) { - items = runtime().untracked([&] { return selectedOffPage(view->get(), tableSelection(*element), keyFn); }); - } - // A heading is never selected. A virtualized backend knows the keys of rows it has not realized but not - // which of them are headings, so its Ctrl+A or range can name one. - for (Key const& key : keys) { - if (std::string const* const text = std::get_if(&key); - text != nullptr && text->starts_with("\x1Fgroup:")) { - continue; - } - items.push_back(valueOfKey(key)); - } - Value const selected{std::move(items)}; - runtime().batch([&] { - if (element->bound == nullptr) { - session.asUser([&] { - session.noteWrite(); - element->selection.set(selected); - }); - } - runEvent(commands, ctx, selected); - }); - }; - // The header marks the sort's first key; a sort that names no sortable column marks none. - auto const columnIndex = [&node, derivedCount](std::string_view columnId) -> std::optional { - auto const parts = node.partList("columns"); - auto const found = - std::ranges::find_if(parts, [columnId](DocNodePtr const& part) { return part->id == columnId; }); - if (found == parts.end()) { - return std::nullopt; - } - return derivedCount + static_cast(std::distance(parts.begin(), found)); - }; - options.sort = slotProp>([element, &node, columnIndex]() -> std::optional { - std::optional> const keys = sortKeysOf(node, tableSort(*element)); - if (!keys || keys->empty()) { - return std::nullopt; - } - std::optional const index = columnIndex(keys->front().column->id); - if (!index) { - return std::nullopt; - } - return TableSort{.column = *index, - .direction = keys->front().descending ? SortDirection::Descending : SortDirection::Ascending}; - }); - // A header click makes its column the single key: descending when it already is the first key ascending, - // ascending otherwise. The table's own sort takes it when no key binds one, then `onSortChange` runs with - // `event` the new sort. - options.onSort = [this, ctx, element, &node, derivedCount, - commands = node.event("onSortChange")](std::size_t index) { - auto const parts = node.partList("columns"); - if (index < derivedCount || index - derivedCount >= parts.size() || - !parts.subspan(index - derivedCount).front()->flag("sortable")) { - return; - } - std::string const& columnId = parts.subspan(index - derivedCount).front()->id; - Value const current = runtime().untracked([&] { return tableSort(*element); }); - std::optional> const keys = sortKeysOf(node, current); - bool const descending = - keys && !keys->empty() && keys->front().column->id == columnId && !keys->front().descending; - ValueRecord key; - key.insert_or_assign("column", Value{columnId}); - key.insert_or_assign("direction", Value{std::string{descending ? "desc" : "asc"}}); - Value const next{ValueList{Value{std::move(key)}}}; - runtime().batch([&] { - if (element->sortBound == nullptr) { - session.asUser([&] { - session.noteWrite(); - element->sort.set(next); - }); - } - runEvent(commands, ctx, next); - }); - }; - options.onActivate = [this, ctx, element, registry, commands = node.event("onActivate")](Key const& key) { - Value const activated = valueOfKey(key); - session.asUser([&] { - session.noteWrite(); - element->activeKey.set(activated); - }); - auto const found = registry->find(canonicalJson(activated)); - std::shared_ptr const scope = found == registry->end() ? nullptr : found->second.lock(); - LowerCtx const rowCtx{.scope = scope ? scope : ctx.scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; - runEvent(commands, rowCtx, activated); - }; - commonOf(node, ctx, element, options.common); - std::span const empty = node.nodes("empty"); - if (empty.empty()) { - return ui::table(std::move(columns), std::move(rows), std::move(keyFn), std::move(cellsOf), - std::move(options)); - } - // With `empty`, a column holds the table and the content shown in its place while `rows` is an empty list; a - // `null` (a query not answered yet) shows the table. The column is placed as the table would be: it takes the - // node's visibility and layout, and every other common property stays on the table, so its test id and the - // element id `focus` finds name the table. - auto const listed = [scope = ctx.scope, bindings = ctx.bindings, rowsExpr] { - ValueList const* const items = evalIn(*scope, bindings.get(), rowsExpr).asList(); - return items == nullptr || !items->empty(); - }; - Column wrapper; - wrapper.common.visible = std::move(options.common.visible); - wrapper.common.layout = options.common.layout; - options.common.visible = slotProp(listed); - Column content{.children = {lowerAll(empty, ctx)}}; - content.common.visible = slotProp([listed] { return !listed(); }); - wrapper.children.push_back(ui::table(std::move(columns), std::move(rows), std::move(keyFn), - std::move(cellsOf), std::move(options))); - wrapper.children.push_back(ui::column(std::move(content))); - return ui::column(std::move(wrapper)); -} - -inline TableRowView ScreenCore::headingRow(DocNode const& node, LowerCtx const& ctx, - reactive::Signal const& row, std::string key) { - auto const heading = node.partList("group").front()->nodes("heading"); - std::vector content; - content.reserve(heading.size()); - for (DocNodePtr const& child : heading) { - content.push_back(child.get()); - } - auto scope = rowScope(node, ctx, row, content, std::move(key)); - LowerCtx const rowCtx{.scope = scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; - // The cell owns the heading's scope, for as long as the row's node lives, as a data row's first cell does. - auto owner = std::make_shared> const>(lowerAll(heading, rowCtx), scope); - return TableRowView{.cells = {Node{owner, owner->first.get()}}, .tone = std::nullopt, .heading = true}; -} - -inline Node ScreenCore::lowerChart(DocNode const& node, LowerCtx const& ctx, ElementState* element) { - Chart spec; - spec.data = slotProp( - [this, &node, scope = ctx.scope, bindings = ctx.bindings] { return chartData(node, *scope, bindings.get()); }); - commonOf(node, ctx, element, spec.common); - return ui::chart(std::move(spec)); -} - -inline std::optional ScreenCore::chartMagnitude(Value const& value, std::string const& path, - std::optional& unit) { - std::optional const number = numeric(value); - if (!number) { - report(path, "a chart value is a number or a quantity; this one is left out"); - return std::nullopt; - } - std::string const own = number->unit != nullptr ? *number->unit : std::string{}; - if (!unit) { - unit = own; - return number->value; - } - if (*unit == own) { - return number->value; - } - std::optional converted; - if (!own.empty() && !unit->empty()) { - converted = convertUnit(number->value, own, *unit, session.formatting().units); - } - if (!converted) { - report(path, "a chart value does not convert to the unit of the chart's first value; it is left out"); - } - return converted; -} - -inline std::optional ScreenCore::chartToneOf(Value const& value, std::string const& path) { - static constexpr std::array, 5> kTones = {{ - {"neutral", Tone::Neutral}, - {"info", Tone::Info}, - {"ok", Tone::Ok}, - {"warn", Tone::Warn}, - {"err", Tone::Err}, - }}; - if (value.isNull()) { - return std::nullopt; - } - if (std::string const* const text = value.asString()) { - for (auto const& [name, tone] : kTones) { - if (name == *text) { - return tone; - } - } - } - report(path, "a chart tone is neutral, info, ok, warn or err; this one marks nothing"); - return std::nullopt; -} - -inline std::optional ScreenCore::chartPosition(Value const& value, std::string const& path, - detail::ChartAxisKinds& kinds) { - if (value.isNull()) { - return std::nullopt; - } - if (std::optional const number = numeric(value)) { - kinds.numbers = true; - return number->value; - } - if (std::optional const instant = - dateInstantOf(value, session.formatting().utcOffsetMinutes).instant) { - kinds.instants = true; - return math::Rational{instant->value.time_since_epoch().count(), math::DecimalPlaces{0}}; - } - report(path, "a chart's `x` is a number, a date or an instant; this point is left out"); - return std::nullopt; -} - -inline std::vector ScreenCore::chartPoints(DocNode const& series, RtScope const& scope, - Bindings const* bindings, - std::optional& unit, - detail::ChartAxisKinds& kinds) { - // A chart is a picture of a few hundred values; a larger set is a table's. - static constexpr std::size_t kMaxPoints = 1000; - FormatContext const& format = scope.formatting(); - ExprPtr const pointsExpr = series.prop("points"); - Value const listed = evalIn(scope, bindings, pointsExpr); - ValueList const* const list = listed.asList(); - if (list == nullptr) { - // `null` is a query still loading, and draws as empty without a word. - if (!listed.isNull()) { - report(pointsExpr->path, "`points` is a list; the series draws as empty"); - } - return {}; - } - std::size_t const first = list->size() > kMaxPoints ? list->size() - kMaxPoints : 0; - if (first > 0) { - report(pointsExpr->path, "a series draws its last 1000 points"); - } - ExprPtr const yExpr = series.prop("y"); - ExprPtr const xExpr = series.prop("x"); - ExprPtr const labelExpr = series.prop("xLabel"); - ExprPtr const toneExpr = series.prop("tone"); - ExprPtr const noteExpr = series.prop("note"); - std::vector points; - for (std::size_t index = first; index < list->size(); ++index) { - ScopeEnv const env{scope, bindings, &list->at(index)}; - detail::ChartRawPoint point{.index = index}; - if (xExpr) { - point.x = chartPosition(evaluate(*xExpr, env), xExpr->path, kinds); - if (!point.x) { - continue; - } - } - Value const value = evaluate(*yExpr, env); - if (!value.isNull()) { - point.y = chartMagnitude(value, yExpr->path, unit); - if (!point.y) { - continue; - } - } - point.xLabel = labelExpr ? textOf(evaluate(*labelExpr, env), format) : std::string{}; - point.note = noteExpr ? textOf(evaluate(*noteExpr, env), format) : std::string{}; - point.tone = toneExpr ? chartToneOf(evaluate(*toneExpr, env), toneExpr->path) : std::nullopt; - points.push_back(std::move(point)); - } - return points; -} - -/// @brief A chart's exact value at @p places, as the active locale writes it. -/// @param value The value. -/// @param places The places, at most 18. -/// @param format The formatting facts. -/// @return The text; the exact JSON when the rounded value does not fit. -[[nodiscard]] inline std::string chartNumberText(math::Rational const& value, std::uint32_t places, - FormatContext const& format) { - std::optional rounded = - math::checkedRoundToDecimalPlaces(value, math::DecimalPlaces{places}, math::RoundingMode::HalfEven); - if (!rounded) { - return textOf(Value{Decimal{value}}, format); - } - rounded->decimalPlaces = math::DecimalPlaces{places}; - return textOf(Value{Decimal{*rounded}}, format); -} - -/// @brief A reference line's stroke by its document name. -/// @param name `solid`, `dashed`, `dotted`, or empty for solid; the loader refuses any other. -/// @return The stroke. -[[nodiscard]] inline ChartLineStyle chartLineStyle(std::string_view name) { - if (name == "dashed") { - return ChartLineStyle::Dashed; - } - return name == "dotted" ? ChartLineStyle::Dotted : ChartLineStyle::Solid; -} - -/// @brief Where a point sits along a value axis that a document may have fixed, and on which side it is clipped. -/// @param value The point's value. -/// @param range The axis. -/// @return The value drawn, the axis end for a value outside, and the side it lies beyond. -[[nodiscard]] inline std::pair chartClipped(math::Rational const& value, - ChartRange const& range) { - if (value < range.low) { - return {range.low, ChartClip::Below}; - } - if (value > range.high) { - return {range.high, ChartClip::Above}; - } - return {value, ChartClip::None}; -} - -inline std::vector ScreenCore::chartLines(DocNode const& node, RtScope const& scope, - Bindings const* bindings, - std::optional& unit) { - FormatContext const& format = scope.formatting(); - std::vector lines; - for (DocNodePtr const& part : node.partList("lines")) { - ExprPtr const valueExpr = part->prop("value"); - Value const value = evalIn(scope, bindings, valueExpr); - std::optional const magnitude = - value.isNull() ? std::nullopt : chartMagnitude(value, valueExpr->path, unit); - if (!magnitude) { - continue; - } - detail::ChartRawLine line{.value = *magnitude, .label = std::nullopt}; - if (ExprPtr const label = part->prop("label")) { - line.label = textOf(evalIn(scope, bindings, label), format); - } - if (ExprPtr const tone = part->prop("tone")) { - line.tone = chartToneOf(evalIn(scope, bindings, tone), tone->path).value_or(Tone::Neutral); - } - line.style = detail::chartLineStyle(part->name("style")); - lines.push_back(std::move(line)); - } - return lines; -} - -inline ChartRange ScreenCore::chartFixedRange(DocNode const& node, RtScope const& scope, Bindings const* bindings, - std::optional& unit, ChartRange const& range) { - ChartRange fixed = range; - for (auto const& [key, end] : {std::pair{"yMin", &fixed.low}, std::pair{"yMax", &fixed.high}}) { - if (ExprPtr const expr = node.prop(key)) { - Value const value = evalIn(scope, bindings, expr); - if (!value.isNull()) { - *end = chartMagnitude(value, expr->path, unit).value_or(*end); - } - } - } - if (fixed.high > fixed.low) { - return fixed; - } - report(pointerAppend(node.path, "yMin"), "`yMin` is not below `yMax`; the chart takes its range from its values"); - return range; -} - -inline void ScreenCore::chartSeries(ChartData& data, DocNode const& node, RtScope const& scope, - Bindings const* bindings, std::vector>& series, - bool positioned, ChartRange const& range) const { - auto const positionOf = [positioned](detail::ChartRawPoint const& point) { - return positioned && point.x ? *point.x - : math::Rational{static_cast(point.index), math::DecimalPlaces{0}}; - }; - std::vector positions; - for (auto const& points : series) { - std::ranges::transform(points, std::back_inserter(positions), positionOf); - } - // The room one position gives its bars: the least distance between two of their positions, gaps included, so a - // bar never grows over the label of an empty position between two. - std::vector barPositions; - { - std::size_t seriesIndex = 0; - for (DocNodePtr const& part : node.partList("series")) { - if (part->name("style") == "bars") { - std::ranges::transform(series.at(seriesIndex), std::back_inserter(barPositions), positionOf); - } - ++seriesIndex; - } - } - std::ranges::sort(barPositions); - std::optional slot; - for (std::size_t next = 1; next < barPositions.size(); ++next) { - auto const distance = math::checkedSub(barPositions.at(next), barPositions.at(next - 1)); - if (distance && distance->numerator > 0 && (!slot || *distance < *slot)) { - slot = *distance; - } - } - if (!barPositions.empty()) { - data.barSlot = realOf(slot.value_or(math::Rational{1, math::DecimalPlaces{0}})); - } - // A bar is centred on its position and half a slot wide each side, so the axis holds that much beyond the - // outermost position. - if (!barPositions.empty() && !positions.empty()) { - math::Rational const half = math::checkedDiv(slot.value_or(math::Rational{1, math::DecimalPlaces{0}}), - math::Rational{2, math::DecimalPlaces{0}}) - .value_or(math::Rational{0, math::DecimalPlaces{0}}); - auto const [lowest, highest] = std::ranges::minmax(positions); - auto const below = math::checkedSub(lowest, half); - auto const above = math::checkedAdd(highest, half); - if (below && above) { - positions.push_back(*below); - positions.push_back(*above); - } - } - if (std::optional const across = chartRange(positions, 0)) { - data.xMin = realOf(across->low); - data.xMax = realOf(across->high); - } - std::size_t index = 0; - for (DocNodePtr const& part : node.partList("series")) { - ChartSeries drawn; - if (part->name("style") == "bars") { - drawn.style = ChartStyle::Bars; - } - if (ExprPtr const label = part->prop("label")) { - drawn.label = textOf(evalIn(scope, bindings, label), scope.formatting()); - } - drawn.joined = drawn.style == ChartStyle::Line && (!part->flags.contains("joined") || part->flag("joined")); - for (detail::ChartRawPoint& point : series.at(index)) { - ChartPoint out{.x = realOf(positionOf(point)), - .y = std::nullopt, - .clip = ChartClip::None, - .xLabel = std::move(point.xLabel), - .tone = point.tone, - .note = std::move(point.note)}; - if (point.y) { - auto const [shown, clip] = detail::chartClipped(*point.y, range); - out.y = realOf(shown); - out.clip = clip; - } - drawn.points.push_back(std::move(out)); - } - data.series.push_back(std::move(drawn)); - ++index; - } -} - -inline ChartData ScreenCore::chartData(DocNode const& node, RtScope const& scope, Bindings const* bindings) { - FormatContext const& format = scope.formatting(); - ChartData data; - data.summary = textOf(evalIn(scope, bindings, node.prop("summary")), format); - if (ExprPtr const label = node.prop("yLabel")) { - data.yLabel = textOf(evalIn(scope, bindings, label), format); - } - std::optional unit; - detail::ChartAxisKinds kinds; - std::vector> series; - for (DocNodePtr const& part : node.partList("series")) { - series.push_back(chartPoints(*part, scope, bindings, unit, kinds)); - } - std::vector const lines = chartLines(node, scope, bindings, unit); - // The values the axis must hold, and the places they are shown at. - std::vector values; - for (auto const& points : series) { - for (detail::ChartRawPoint const& point : points) { - if (point.y) { - values.push_back(*point.y); - } - } - } - std::ranges::transform(lines, std::back_inserter(values), &detail::ChartRawLine::value); - // A bar grows from 0, so the axis holds 0; the baseline's side is padded only when something lies beyond it, so - // that the baseline is the plot's edge when nothing does. - std::vector axisValues = values; - ChartPadding padding; - bool barsHaveValues = false; - { - std::size_t seriesIndex = 0; - for (DocNodePtr const& part : node.partList("series")) { - barsHaveValues = - barsHaveValues || (part->name("style") == "bars" && - std::ranges::any_of(series.at(seriesIndex), [](detail::ChartRawPoint const& point) { - return point.y.has_value(); - })); - ++seriesIndex; - } - } - if (barsHaveValues) { - axisValues.push_back(math::Rational{0, math::DecimalPlaces{0}}); - padding.low = std::ranges::any_of(values, [](math::Rational const& value) { return value.numerator < 0; }); - padding.high = std::ranges::any_of(values, [](math::Rational const& value) { return value.numerator > 0; }); - } - std::uint32_t widest = 0; - for (math::Rational const& value : values) { - widest = std::max(widest, value.decimalPlaces.value); - } - ExprPtr const placesExpr = node.prop("yPlaces"); - std::int64_t const* const fixedPlaces = placesExpr ? placesExpr->literal.asInt() : nullptr; - std::uint32_t const places = fixedPlaces != nullptr ? static_cast(*fixedPlaces) : widest; - std::optional const computed = chartRange(axisValues, places, padding); - if (!computed) { - report(node.path, "the chart's values overflow its arithmetic; it draws nothing"); - return data; - } - ChartRange const range = chartFixedRange(node, scope, bindings, unit, *computed); - data.yMin = realOf(range.low); - data.yMax = realOf(range.high); - // Three or more lines are the scale a reader reads the chart against; fewer leave the values without one. - std::optional const ticks = lines.size() < 3 ? chartTicks(range) : std::nullopt; - if (ticks) { - std::uint32_t const tickPlaces = std::max(places, ticks->places); - for (math::Rational const& tick : ticks->values) { - data.yTicks.push_back( - ChartTick{.value = realOf(tick), .text = detail::chartNumberText(tick, tickPlaces, format)}); - } - } - for (detail::ChartRawLine const& line : lines) { - data.lines.push_back( - ChartLine{.value = realOf(line.value), - .label = line.label.value_or(detail::chartNumberText(line.value, places, format)), - .tone = line.tone, - .style = line.style}); - } - if (kinds.numbers && kinds.instants) { - report(pointerAppend(node.path, "series"), - "a chart's `x` values are all numbers or all dates and instants; the points are spaced by index"); - } - chartSeries(data, node, scope, bindings, series, kinds.numbers != kinds.instants, range); - return data; -} - -inline std::optional ScreenCore::rowToneOf(Value const& value, std::string const& path, bool& noted) { - if (value.isNull()) { - return std::nullopt; - } - if (std::optional const tone = toneNamed(value)) { - return tone; - } - if (!noted) { - noted = true; - report(path, "rowTone is " + canonicalJson(value) + "; a tone is neutral, info, ok, warn or err"); - } - return std::nullopt; -} - -inline std::vector ScreenCore::rowSpansOf(Value const& value, std::vector const& columns, - std::string const& path, bool& noted) { - std::vector spans; - if (value.isNull()) { - return spans; - } - ValueList const* const items = value.asList(); - bool bad = items == nullptr; - for (Value const& item : items != nullptr ? *items : ValueList{}) { - Value const* const column = item.field("column"); - Value const* const rows = item.field("rows"); - std::string const* const id = column != nullptr ? column->asString() : nullptr; - std::int64_t const* const count = rows != nullptr ? rows->asInt() : nullptr; - auto const found = id != nullptr ? std::ranges::find(columns, *id) : columns.end(); - if (found == columns.end() || count == nullptr || *count < 1) { - bad = true; - continue; - } - spans.push_back(RowSpan{.column = static_cast(found - columns.begin()), - .rows = static_cast(*count)}); - } - if (bad && !noted) { - noted = true; - report(path, - "rowSpans is " + canonicalJson(value) + "; a span is {column: a column's id, rows: an integer from 1}"); - } - return spans; -} - -inline void ScreenCore::ownQueriesOf(ExprPtr const& expr, RtScope const& scope, BoundaryRuntime& boundary, - std::set>& seen) { - if (!expr) { - return; - } - bool const control = expr->kind == ExprKind::Query || expr->kind == ExprKind::Pending || - expr->kind == ExprKind::Error || expr->kind == ExprKind::ErrorKind || - expr->kind == ExprKind::Refusal; - if (control || expr->kind == ExprKind::Ref) { - NameRef const* const found = scope.find(expr->name); - if (found != nullptr && found->category == NameCategory::Query && seen.insert(expr->name).second) { - boundary.queries.push_back(found->query); - } - if (expr->kind == ExprKind::Ref && found != nullptr && found->category == NameCategory::Let && - seen.insert("let:" + expr->name).second) { - ownQueriesOf(found->letExpr, scope, boundary, seen); - } - } - for (ExprPtr const& arg : expr->args) { - ownQueriesOf(arg, scope, boundary, seen); - } - for (auto const& [name, field] : expr->fields) { - static_cast(name); - ownQueriesOf(field, scope, boundary, seen); - } -} - -inline void ScreenCore::ownQueries(DocNode const& node, RtScope const& scope, BoundaryRuntime& boundary, - std::set>& seen) { - if (node.kind == "boundary") { - return; - } - for (auto const& [key, expr] : node.props) { - static_cast(key); - ownQueriesOf(expr, scope, boundary, seen); - } - for (auto const& [key, nodes] : node.children) { - static_cast(key); - for (DocNodePtr const& child : nodes) { - ownQueries(*child, scope, boundary, seen); - } - } - for (auto const& [key, parts] : node.parts) { - static_cast(key); - for (DocNodePtr const& part : parts) { - ownQueries(*part, scope, boundary, seen); - } - } -} - -inline Node ScreenCore::lowerBoundary(DocNode const& node, LowerCtx const& ctx) { - auto boundary = std::make_shared(); - std::set> seen; - for (DocNodePtr const& child : node.nodes("children")) { - ownQueries(*child, *ctx.scope, *boundary, seen); - } - auto bindings = std::make_shared(*ctx.bindings); - bindings->push_back(Binding{.name = "boundary", .read = [boundary] { - for (QueryRuntime const* const query : boundary->queries) { - Value const error = query->error(); - if (!error.isNull() && query->value().isNull()) { - return Value{ValueRecord{{"error", error}}}; - } - } - return Value{ValueRecord{{"error", Value{}}}}; - }}); - LowerCtx const errorCtx{.scope = ctx.scope, .bindings = bindings, .boundary = boundary}; - LowerCtx const childCtx{.scope = ctx.scope, .bindings = ctx.bindings, .boundary = boundary}; - auto group = [this](std::span nodes, LowerCtx const& where) -> Node { - return nodes.empty() ? ui::spacer() : lowerAll(nodes, where); - }; - Switch spec; - spec.cases.push_back(SwitchCase{.key = Key{std::int64_t{0}}, .node = group(node.nodes("loading"), childCtx)}); - spec.cases.push_back(SwitchCase{.key = Key{std::int64_t{1}}, .node = group(node.nodes("error"), errorCtx)}); - spec.cases.push_back(SwitchCase{.key = Key{std::int64_t{2}}, .node = group(node.nodes("children"), childCtx)}); - spec.selector = slotProp([boundary] { - bool loading = false; - for (QueryRuntime const* const query : boundary->queries) { - if (!query->settled()) { - loading = true; - } else if (query->value().isNull() && !query->error().isNull()) { - return Key{std::int64_t{1}}; - } - } - return Key{std::int64_t{loading ? 0 : 2}}; - }); - commonOf(node, ctx, nullptr, spec.common); - return ui::switchOf(std::move(spec)); -} - -inline Node ScreenCore::lowerCustom(DocNode const& node, LowerCtx const& ctx) { - std::string const name{node.name("name")}; - // A loaded document's custom node names a declared component, and every component has a fallback. - Component const& component = _doc->components.at(name); - std::vector> props; - for (DocNodePtr const& record : node.partList("props")) { - for (auto const& [key, expr] : record->props) { - props.emplace_back(key, expr); - } - } - auto bindings = std::make_shared(); - bindings->push_back( - Binding{.name = "props", .read = [scope = ctx.scope, outer = ctx.bindings, props = std::move(props)] { - ValueRecord record; - for (auto const& [key, expr] : props) { - record.insert_or_assign(key, evalIn(*scope, outer.get(), expr)); - } - return Value{std::move(record)}; - }}); - auto scope = std::make_shared(*this, nullptr, nullptr, ctx.scope->nodes.depth() + 1); - scope->formatSource = ctx.scope; - scope->usePrefix = focusKeyOf(node.path, *ctx.scope) + ">"; - DocNode const& fallback = *component.fallback; - declare(*scope, nullptr, {&fallback}, {}); - Node lowered = lower(fallback, LowerCtx{.scope = scope, .bindings = bindings, .boundary = nullptr}); - Custom spec{.name = name, - .fallback = std::move(lowered), - .props = {}, - .minVersion = - static_cast(std::clamp(component.version, 0, std::numeric_limits::max())), - .onEvent = {}}; - // Every declared prop is given, a missing one as its type's empty value: a component lacking one is refused. - for (auto const& [prop, type] : component.props) { - ExprPtr expr; - for (DocNodePtr const& record : node.partList("props")) { - if (ExprPtr const given = record->prop(prop)) { - expr = given; - } - } - if (type == "bool") { - spec.props.push_back(CustomProp{.name = prop, .value = bindProp(ctx, expr, false, boolOf)}); - } else if (type == "number") { - spec.props.push_back(CustomProp{ - .name = prop, .value = bindProp(ctx, expr, 0.0, [](Value const& value, FormatContext const&) { - return componentNumber(value); - })}); - } else { - spec.props.push_back( - CustomProp{.name = prop, - .value = bindProp(ctx, expr, std::string{}, - [type](Value const& value, FormatContext const& format) { - return componentText(value, type, format); - })}); - } - } - spec.onEvent = [this, ctx, site = &node, declared = &component](std::string const& event, - std::string const& payload) { - Commands const* const commands = site->event("on." + event); - if (commands == nullptr) { - return; - } - auto const type = declared->events.find(event); - runEvent(commands, ctx, componentPayload(payload, type == declared->events.end() ? nullptr : &type->second)); - }; - return ui::custom(std::move(spec)); -} - -/// @brief One child of an arranged container, as the user's choice places it. -struct ArrangedChild { - /// @brief The child's id. - std::string id; - /// @brief Whether the choice hides it. - bool hidden = false; -}; - -/// @brief A container's children in the order a stored `arrange` choice gives, each marked shown or hidden. -/// -/// A child the choice does not name keeps its declared place after the named ones, shown, and an entry that names no -/// child, names one twice or is not a `{"id", "hidden"}` record is skipped, so a new document version survives an old -/// choice (spec 5 §12b). A choice that is not a list leaves the declared order. Only `"hidden": true` hides. -/// @param stored The point's current choice. -/// @param declared The container's children, in document order. -/// @return Every child, in order. -[[nodiscard]] inline std::vector arrangedChildren(Value const& stored, - std::span declared) { - auto const isDeclared = [declared](std::string const& childId) { - return std::ranges::find(declared, childId, &DocNode::id) != declared.end(); - }; - std::vector out; - std::set> placed; - if (ValueList const* const entries = stored.asList()) { - for (Value const& entry : *entries) { - Value const* const named = entry.field("id"); - std::string const* const name = named == nullptr ? nullptr : named->asString(); - if (name == nullptr || !isDeclared(*name) || !placed.insert(*name).second) { - continue; - } - Value const* const hidden = entry.field("hidden"); - bool const* const flag = hidden == nullptr ? nullptr : hidden->asBool(); - out.push_back(ArrangedChild{.id = *name, .hidden = flag != nullptr && *flag}); - } - } - for (DocNode const* const child : declared) { - if (!placed.contains(child->id)) { - out.push_back(ArrangedChild{.id = child->id}); - } - } - return out; -} - -/// @brief The ids of the children an `arrange` choice shows, in its order (`arrangedChildren`, without the hidden). -/// @param stored The point's current choice. -/// @param declared The container's children, in document order. -/// @return The ids to show, in order. -[[nodiscard]] inline std::vector arrangedOrder(Value const& stored, std::span declared) { - std::vector order; - for (ArrangedChild const& child : arrangedChildren(stored, declared)) { - if (!child.hidden) { - order.emplace_back(child.id); - } - } - return order; -} - -/// @brief An arrangement as the choice an `arrange` point stores. -/// @param children Every child, in order. -/// @return `[{"id", "hidden"}, …]`. -[[nodiscard]] inline Value arrangementValue(std::vector const& children) { - ValueList entries; - entries.reserve(children.size()); - for (ArrangedChild const& child : children) { - entries.emplace_back(ValueRecord{{"id", Value{child.id}}, {"hidden", Value{child.hidden}}}); - } - return Value{std::move(entries)}; -} - -/// @brief The element of a document tree with @p elementId. -/// @param node The subtree. -/// @param elementId The element's id. -/// @return The element, or `nullptr` when the subtree has none with that id. -// NOLINTNEXTLINE(misc-no-recursion): one level per level of the document tree. -[[nodiscard]] inline DocNode const* elementNode(DocNode const& node, std::string_view elementId) { - if (node.id == elementId) { - return &node; - } - for (auto const* const groups : {&node.children, &node.parts}) { - for (auto const& [slot, nodes] : *groups) { - static_cast(slot); - for (DocNodePtr const& child : nodes) { - if (DocNode const* const found = elementNode(*child, elementId)) { - return found; - } - } - } - } - return nullptr; -} - -inline std::string ScreenCore::arrangedBy(std::string const& elementId) const { - if (elementId.empty()) { - return {}; - } - for (auto const& [name, point] : _doc->customize) { - if (point.kind == "arrange" && point.of == elementId) { - return name; - } - } - return {}; -} - -// A keyed list over the children's ids rather than a stack, so a new choice moves the shown widgets, keeping their -// state and focus, and mounts or unmounts only what it shows or hides. A child is lowered in the container's own -// scope: arranging changes where it is, not what it reads. -inline Node ScreenCore::lowerArranged(DocNode const& node, LowerCtx const& ctx, ElementState* element, - std::string const& point, Axis axis, int gap) { - std::vector declared; - for (DocNodePtr const& child : node.nodes("children")) { - declared.push_back(child.get()); - } - auto order = [this, point, declared] { return arrangedOrder(prefs.get().at(point), declared); }; - auto key = [](Value const& childId) { return keyOf(childId); }; - LowerCtx childCtx = ctx; - childCtx.listGap = axis == Axis::Vertical ? gap : 0; - auto view = [this, childCtx, declared](reactive::Signal const& row) -> Node { - // The order lists only declared ids, so the lookup always finds the child. - auto const found = std::ranges::find(declared, textOf(row.peek(), session.formatting()), &DocNode::id); - return lower(**found, childCtx); - }; - ForEach spec{ - .model = std::make_shared const>(std::move(order), std::move(key), std::move(view)), - .axis = axis, - .gap = gap}; - commonOf(node, ctx, element, spec.common); - return makeNode(std::move(spec)); -} - -// One row per child of the arranged container, hidden ones included: a checkbox shows or hides it, and two buttons -// move it a place. Each edit stores the whole arrangement, so the stored list always names every child. -inline Node ScreenCore::lowerArrangeEditor(DocNode const& node, LowerCtx const& ctx, std::string const& point, - CustomizePoint const& spec, std::function const& choose) { - // The loader checked that `of` names a column or row of this screen. - DocNode const* const container = elementNode(*_doc->view, spec.of); - std::vector declared; - for (DocNodePtr const& child : container->nodes("children")) { - declared.push_back(child.get()); - } - auto const current = [this, point, declared] { return arrangedChildren(prefs.get().at(point), declared); }; - auto const place = [current](std::string const& childId) { - auto const children = current(); - return static_cast(std::ranges::find(children, childId, &ArrangedChild::id) - children.begin()); - }; - // Applies an edit to the arrangement as it stands, read untracked: the edit is a transition, not a binding. - auto const edit = [this, current, choose](std::string const& childId, auto const& change) { - auto children = runtime().untracked(current); - auto const found = std::ranges::find(children, childId, &ArrangedChild::id); - change(children, static_cast(found - children.begin())); - choose(arrangementValue(children)); - }; - auto rows = [current] { - std::vector ids; - for (ArrangedChild const& child : current()) { - ids.emplace_back(child.id); - } - return ids; - }; - auto key = [](Value const& childId) { return keyOf(childId); }; - auto view = [this, current, place, edit](reactive::Signal const& row) -> Node { - std::string const childId = textOf(row.peek(), session.formatting()); - Checkbox shown{.label = childId}; - shown.checked = slotProp([current, childId] { - auto const children = current(); - return !std::ranges::find(children, childId, &ArrangedChild::id)->hidden; - }); - shown.onToggle = [edit, childId](bool checked) { - edit(childId, [checked](std::vector& children, std::size_t index) { - children.at(index).hidden = !checked; - }); - }; - Button moveUp{.label = std::string{"\xE2\x86\x91"}}; - moveUp.onClick = [edit, childId] { - // Clamped rather than refused: at the edge the child swaps with itself, which stores the same order. - edit(childId, [](std::vector& children, std::size_t index) { - std::swap(children.at(index), children.at(std::max(index, std::size_t{1}) - 1)); - }); - }; - moveUp.common.enabled = slotProp([place, childId] { return place(childId) > 0; }); - moveUp.common.a11y.name = "Move " + childId + " up"; - moveUp.common.testId = "arrange-up-" + childId; - Button moveDown{.label = std::string{"\xE2\x86\x93"}}; - moveDown.onClick = [edit, childId] { - edit(childId, [](std::vector& children, std::size_t index) { - std::swap(children.at(index), children.at(std::min(index + 1, children.size() - 1))); - }); - }; - moveDown.common.enabled = - slotProp([current, place, childId] { return place(childId) + 1 < current().size(); }); - moveDown.common.a11y.name = "Move " + childId + " down"; - moveDown.common.testId = "arrange-down-" + childId; - shown.common.testId = "arrange-shown-" + childId; - return ui::row(Row{.children = {ui::checkbox(std::move(shown)), ui::button(std::move(moveUp)), - ui::button(std::move(moveDown))}, - .gap = 1}); - }; - ForEach editor{.model = - std::make_shared const>(std::move(rows), std::move(key), std::move(view))}; - commonOf(node, ctx, nullptr, editor.common); - return makeNode(std::move(editor)); -} - -inline Node ScreenCore::lowerCustomize(DocNode const& node, LowerCtx const& ctx) { - std::string const point{node.name("point")}; - // A loaded document's customize node names a declared point, and every point has a choice in `prefs`. - CustomizePoint const& spec = _doc->customize.at(point); - auto choose = [this, point](Value value) { - session.asUser([&] { - ValueRecord next = prefs.peek(); - next.insert_or_assign(point, value); - prefs.set(std::move(next)); - }); - if (host != nullptr) { - host->preferenceChanged(_doc->id, point, value); - } - }; - if (spec.kind == "arrange") { - return lowerArrangeEditor(node, ctx, point, spec, choose); - } - if (spec.kind == "choice") { - Select select; - std::vector options; - options.reserve(spec.options.size()); - for (std::string const& option : spec.options) { - options.push_back(SelectOption{.key = Key{option}, .label = option}); - } - select.options = std::move(options); - select.selected = slotProp>([this, point]() -> std::optional { - Value const& chosen = prefs.get().at(point); - return chosen.isNull() ? std::nullopt : std::optional{keyOf(chosen)}; - }); - select.onSelect = [choose](Key const& key) { choose(valueOfKey(key)); }; - commonOf(node, ctx, nullptr, select.common); - return ui::select(std::move(select)); - } - if (spec.kind == "value" && (spec.type.kind == TypeKind::String || spec.type.isAny())) { - TextInput input; - input.value = - slotProp([this, point] { return textOf(prefs.get().at(point), session.formatting()); }); - input.onChange = [choose](std::string text) { choose(Value{std::move(text)}); }; - commonOf(node, ctx, nullptr, input.common); - return ui::textInput(std::move(input)); - } - Text placeholder{.text = point, .role = TextRole::Muted}; - commonOf(node, ctx, nullptr, placeholder.common); - return ui::text(std::move(placeholder)); -} -// NOLINTEND(misc-no-recursion) +/// @param type The `value` prop's type. +/// @return The wire value, or why the payload is not one. +[[nodiscard]] MORPH_API std::expected changeWire(std::string const& payload, + std::string_view type); } // namespace detail -inline std::vector Screen::headSpans(ExprPtr const& expr) const { - if (expr == nullptr) { - return {}; - } - bool dropped = false; - bool badTone = false; - std::vector spans = - detail::spansOf(detail::evalIn(*_scope, nullptr, expr), _scope->formatting(), dropped, &badTone); - if (dropped) { - _core->report(expr->path, detail::kSpansReason); - } - if (badTone) { - _core->report(expr->path, detail::kSpanToneReason); - } - return spans; -} - -inline DocNode const* Screen::shownRoot() const { - DocNode const* node = _core->doc().view.get(); - while (node != nullptr && node->kind == "switch") { - Value const value = detail::evalIn(*_scope, nullptr, node->prop("on")); - std::span shown = node->nodes("default"); - for (DocNodePtr const& part : node->partList("cases")) { - if (!(detail::evalIn(*_scope, nullptr, part->prop("when")) == value)) { - continue; - } - if (part->scope.has_value() && detail::declaresNames(*part->scope)) { - return nullptr; - } - shown = part->nodes("children"); - break; - } - node = shown.size() == 1 ? shown.front().get() : nullptr; - } - return node; -} - -inline bool Screen::pageEdge() const { - DocNode const* const node = shownRoot(); - return node != nullptr && node->flag("pageEdge"); -} - -inline bool Screen::headJoined() const { - DocNode const* const node = shownRoot(); - return node != nullptr && node->flag("headJoined"); -} - -inline LeadPlacement Screen::leadPlacement() const { - ExprPtr const& placement = _core->doc().leadPlacement; - if (placement == nullptr) { - return LeadPlacement::Below; - } - Value const value = detail::evalIn(*_scope, nullptr, placement); - if (std::string const* const name = value.asString()) { - if (*name == "inline") { - return LeadPlacement::Inline; - } - if (*name == "end") { - return LeadPlacement::End; - } - if (*name == "below") { - return LeadPlacement::Below; - } - } - if (!value.isNull()) { - _core->report(placement->path, "`leadPlacement` is `below`, `inline` or `end`"); - } - return LeadPlacement::Below; -} - -inline TextRole Screen::titleRole() const { - ExprPtr const& role = _core->doc().titleRole; - if (role == nullptr) { - return TextRole::Heading; - } - Value const value = detail::evalIn(*_scope, nullptr, role); - if (std::string const* const name = value.asString()) { - if (*name == "headline") { - return TextRole::Headline; - } - if (*name == "heading") { - return TextRole::Heading; - } - } - if (!value.isNull()) { - _core->report(role->path, "`titleRole` is `heading` or `headline`"); - } - return TextRole::Heading; -} - -inline std::string Screen::headSurface() const { - Value const value = detail::evalIn(*_scope, nullptr, _core->doc().headSurface); - std::string const* const name = value.asString(); - return name == nullptr ? std::string{} : *name; -} - -inline std::string Screen::pageSurface() const { - Value const value = detail::evalIn(*_scope, nullptr, _core->doc().pageSurface); - std::string const* const name = value.asString(); - return name == nullptr ? std::string{} : *name; -} - -inline std::vector Screen::subtitleSpans() const { return headSpans(_core->doc().subtitleSpans); } - -inline std::vector Screen::titleSpans() const { return headSpans(_core->doc().titleSpans); } - -inline std::vector Screen::eyebrowSpans() const { return headSpans(_core->doc().eyebrowSpans); } - -inline BorrowedModel Screen::lend(std::string_view alias) const { - detail::NameRef const* const found = _scope->find(alias); - if (found == nullptr || found->category != detail::NameCategory::Model) { - return {}; - } - detail::ModelAlias& model = *found->model; - return BorrowedModel{.channel = detail::channelOf(model, *_core), - .token = _core->runtime().untracked([&] { return model.token->get(); })}; -} - -inline std::expected, Refusal> Interpreter::mount(std::shared_ptr doc, - ValueRecord const& params, - IViewBackend& backend, - MountOptions const& options) { - auto refuse = [&](std::string path, std::string reason) { - return std::unexpected(Refusal{.document = doc->id, .path = std::move(path), .reason = std::move(reason)}); - }; - if (!doc->view) { - return refuse("", "the document has no view"); - } - ValueRecord given; - for (auto const& [name, type] : doc->params) { - auto const found = params.find(name); - Value value = found == params.end() ? Value{} : found->second; - if (!type.admits(value)) { - return refuse(pointerAppend("/params", name), value.isNull() - ? "param `" + name + "` is missing" - : "param `" + name + "` is not a " + type.name()); - } - given.insert_or_assign(name, std::move(value)); - } - for (ModelDecl const& model : doc->scope.models) { - if (model.instance == InstanceMode::Borrowed && !options.borrowed.contains(model.name)) { - return refuse(model.path, "alias `" + model.name + "` borrows a model its opener did not lend"); - } - } - reactive::Runtime& runtime = _session->runtime(); - std::unique_ptr screen{new Screen{}}; - screen->_core = std::make_unique(doc, *_session, *_dispatcher, _options, options); - detail::ScreenCore& core = *screen->_core; - if (options.keepStateOf != nullptr) { - core.keptStates = options.keepStateOf->ownState(); - } - screen->_scope = std::make_shared(core, nullptr, nullptr, options.depth); - core.rootScope = screen->_scope; - detail::RtScope& scope = *screen->_scope; - scope.submitted = &core.submitted; - scope.showErrors = doc->showErrors; - for (auto const& [name, value] : given) { - detail::NameRef ref; - ref.category = detail::NameCategory::Param; - ref.param = value; - scope.names.insert_or_assign(name, std::move(ref)); - } - std::vector lists; - for (auto const& [key, commands] : doc->lifecycle) { - static_cast(key); - lists.push_back(&commands); - } - for (auto const& [chord, commands] : doc->keys) { - static_cast(chord); - lists.push_back(&commands); - } - detail::headCommandLists(*doc, lists); - Node root = runtime.untracked([&] { - core.declare(scope, &doc->scope, {doc->view.get()}, lists); - detail::LowerCtx const ctx{ - .scope = screen->_scope, .bindings = std::make_shared(), .boundary = nullptr}; - Node lowered = core.lower(*doc->view, ctx); - screen->_headStatus = core.lowerBadgeParts(doc->status, ctx); - screen->_headActions = core.lowerActionParts(doc->actions, ctx); - screen->_headMenu = core.lowerHeadMenu(doc->menu, ctx); - screen->_headTools = core.lowerHeadTools(doc->tools, ctx); - if (!doc->keys.empty()) { - std::vector keys; - for (auto const& [chord, commands] : doc->keys) { - keys.push_back(KeyBinding{ - .chord = chord, .onPress = [&core, ctx, list = &commands] { core.runEvent(list, ctx, Value{}); }}); - } - Column column{.children = {std::move(lowered)}}; - column.common.keys = std::move(keys); - lowered = ui::column(std::move(column)); - } - return lowered; - }); - screen->_mounted.emplace(runtime, backend, std::move(root), options.parent, options.depth + 1); - screen->_core->focusElement = [mounted = &*screen->_mounted](std::string_view element) { - return mounted->focus(element); - }; - screen->runLifecycle("onMount"); - return screen; -} - -inline std::expected, Refusal> Interpreter::mountApp(std::shared_ptr doc) { - if (doc->id != "app") { - return std::unexpected( - Refusal{.document = doc->id, .path = "/id", .reason = "the app document's id is `app`"}); - } - if (_session->appScope() != nullptr) { - return std::unexpected( - Refusal{.document = doc->id, .path = {}, .reason = "an app document is already mounted on the session"}); - } - std::unique_ptr root{new AppRoot{}}; - root->_core = std::make_unique(doc, *_session, *_dispatcher, _options, MountOptions{}); - detail::ScreenCore& core = *root->_core; - root->_scope = std::make_shared(core, nullptr, nullptr, 0); - core.rootScope = root->_scope; - std::vector lists; - for (auto const& [key, commands] : doc->lifecycle) { - static_cast(key); - lists.push_back(&commands); - } - _session->runtime().untracked([&] { - core.declare(*root->_scope, &doc->scope, {}, lists); - detail::LowerCtx const ctx{ - .scope = root->_scope, .bindings = std::make_shared(), .boundary = nullptr}; - std::vector badges = core.lowerBadgeParts(doc->navigation, ctx); - for (std::size_t index = 0; index < badges.size(); ++index) { - root->_navigation.push_back( - AppRoot::PlacedBadge{.screen = std::string{doc->navigation.at(index)->name("screen")}, - .badge = std::move(badges.at(index))}); - } - }); - root->_navigationBadges = std::make_unique>>( - _session->runtime(), [placed = &root->_navigation] { - std::vector shown; - for (AppRoot::PlacedBadge const& entry : *placed) { - if (entry.badge.visible.evaluate()) { - shown.push_back(NavigationBadge{.screen = entry.screen, - .text = entry.badge.text.evaluate(), - .tone = entry.badge.tone.evaluate()}); - } - } - return shown; - }); - // The app document's date patterns are the application's: every screen of the bundle shows and reads dates so. - if (!doc->datePattern.empty() || !doc->dateTimePattern.empty()) { - _session->setDatePatterns(doc->datePattern, doc->dateTimePattern); - } - _session->setAppScope(root->_scope.get()); - if (auto const found = doc->lifecycle.find("onMount"); found != doc->lifecycle.end()) { - root->runCommands(found->second); - } - return root; -} - } // namespace morph::ui diff --git a/src/ui/interpreter.cpp b/src/ui/interpreter.cpp new file mode 100644 index 000000000..dcf0faa68 --- /dev/null +++ b/src/ui/interpreter.cpp @@ -0,0 +1,8539 @@ +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace morph::ui { + +namespace detail { + +[[nodiscard]] Value evalIn(RtScope const& scope, Bindings const* bindings, ExprPtr const& expr) { + if (!expr) { + return Value{}; + } + ScopeEnv const env{scope, bindings}; + return evaluate(*expr, env); +} + +[[nodiscard]] bool engaged(Value const& value) { + if (value.isNull()) { + return false; + } + if (std::string const* const text = value.asString()) { + return !text->empty(); + } + if (ValueList const* const items = value.asList()) { + return !items->empty(); + } + return true; +} + +[[nodiscard]] std::string textOf(Value const& value, FormatContext const& format) { + if (value.isNull()) { + return {}; + } + if (std::string const* const text = value.asString()) { + return *text; + } + if (bool const* const flag = value.asBool()) { + return *flag ? "true" : "false"; + } + // A number that cannot be rounded at its own places shows as its exact JSON rather than as a clamped value. + if (Quantity const* const quantity = value.asQuantity()) { + auto number = formatNumber(value, withoutGrouping(format.numeric)); + return number ? *number + " " + unitDisplay(quantity->unit, format.units) : canonicalJson(value); + } + if (auto number = formatNumber(value, withoutGrouping(format.numeric))) { + return *std::move(number); + } + if (time::DateTime const* const instant = value.asTimestamp()) { + return instant->toIso8601(); + } + return canonicalJson(value); +} + +namespace { + +/// @brief A value as a view key: an `int` or a string as itself, anything else as its JSON text. +/// @param value The value. +/// @return The key. +[[nodiscard]] Key keyOf(Value const& value) { + if (std::int64_t const* const number = value.asInt()) { + return Key{*number}; + } + if (std::string const* const text = value.asString()) { + return Key{*text}; + } + return Key{canonicalJson(value)}; +} + +} // namespace + +[[nodiscard]] Value valueOfKey(Key const& key) { + if (std::int64_t const* const number = std::get_if(&key)) { + return Value{*number}; + } + return Value{std::get(key)}; +} + +namespace { + +/// @brief A list of strings out of a value: a string, a list of strings, or nothing. +/// @param value The value. +/// @return The strings. +[[nodiscard]] std::vector stringsOf(Value const& value) { + std::vector out; + if (std::string const* const text = value.asString()) { + out.push_back(*text); + } else if (ValueList const* const items = value.asList()) { + for (Value const& item : *items) { + if (std::string const* const element = item.asString()) { + out.push_back(*element); + } + } + } + return out; +} + +/// @brief A list of strings as a value. +/// @param texts The strings. +/// @return The list. +[[nodiscard]] Value listOfStrings(std::vector const& texts) { + ValueList items; + items.reserve(texts.size()); + for (std::string const& text : texts) { + items.emplace_back(text); + } + return Value{std::move(items)}; +} + +/// @brief A command context without its scope: what a callback the host keeps may hold, so that the host never +/// keeps a scope alive past its screen. The callback holds the scope weakly and puts it back. +/// @param ctx The context. +/// @return The context, its scope dropped. +[[nodiscard]] CommandCtx detached(CommandCtx const& ctx) { + CommandCtx kept = ctx; + kept.scope = nullptr; + return kept; +} + +/// @brief Collects the `onClick` lists of menu entries, submenus included. +/// @param entries The entries. +/// @param lists Where they go, in document order. +// NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. +void menuCommandLists(std::span entries, std::vector& lists) { + for (DocNodePtr const& entry : entries) { + if (Commands const* const commands = entry->event("onClick")) { + lists.push_back(commands); + } + menuCommandLists(entry->partList("items"), lists); + } +} + +/// @brief Collects the command lists of a screen's head: its actions', its menu entries' and its tools'. +/// @param doc The screen's document. +/// @param lists Where they go, in document order. +void headCommandLists(Document const& doc, std::vector& lists) { + for (DocNodePtr const& action : doc.actions) { + if (Commands const* const commands = action->event("onClick")) { + lists.push_back(commands); + } + } + menuCommandLists(doc.menu, lists); + for (DocNodePtr const& tool : doc.tools) { + for (std::string_view const key : {"onChange", "onSubmit", "onChoose"}) { + if (Commands const* const commands = tool->event(key)) { + lists.push_back(commands); + } + } + } +} + +/// @brief A kind's key spec, from the kind table. +/// @param kind The kind spec. +/// @param key The key. +/// @return The spec, or `nullptr` when the kind has no such key of its own. +[[nodiscard]] KeySpec const* keySpec(KindSpec const& kind, std::string_view key) { + for (KeySpec const& spec : kind.keys) { + if (spec.key == key) { + return &spec; + } + } + return nullptr; +} + +/// @brief Whether a node kind keeps per-element state even without an id: the inputs, dialogs, tables and the forms +/// engine's screens. +/// @param kind The kind. +/// @return It. +[[nodiscard]] bool statefulKind(std::string_view kind) { + static constexpr std::array kStateful = { + "textInput", "checkbox", "select", "dateTimeInput", "slider", "filePicker", + "dialog", "drawer", "table", "form", "collection", "wizard"}; + return listed(kStateful, kind); +} + +} // namespace + +[[nodiscard]] std::string commandKey(CommandKind kind) { + switch (kind) { + case CommandKind::Set: + return "set"; + case CommandKind::Reset: + return "reset"; + case CommandKind::Run: + return "run"; + case CommandKind::Refetch: + return "refetch"; + case CommandKind::Open: + return "open"; + case CommandKind::Close: + return "close"; + case CommandKind::Navigate: + return "navigate"; + case CommandKind::Return: + return "return"; + case CommandKind::Focus: + return "focus"; + case CommandKind::Host: + return "host"; + case CommandKind::SwitchBackend: + return "switchBackend"; + case CommandKind::ResetPrefs: + return "resetPrefs"; + case CommandKind::SetLocale: + return "setLocale"; + case CommandKind::SetContext: + return "setContext"; + case CommandKind::Notify: + return "notify"; + case CommandKind::Seq: + return "seq"; + case CommandKind::All: + return "all"; + case CommandKind::If: + return "if"; + case CommandKind::CancelClose: + return "cancelClose"; + case CommandKind::Retry: + return "retry"; + case CommandKind::SignIn: + return "signIn"; + case CommandKind::SignOut: + return "signOut"; + case CommandKind::Upload: + return "upload"; + case CommandKind::Download: + return "download"; + default: + return "unknown"; + } +} + +} // namespace detail + +namespace detail { + +[[nodiscard]] std::string failureText(std::exception_ptr const& error) { + try { + std::rethrow_exception(error); + } catch (std::exception const& failure) { + return failure.what(); + } catch (...) { + return "unknown error"; + } +} + +namespace { + +/// @brief A failure's action refusal, as a document reads it. +/// @param error The failure. +/// @return `{"code": c, "args": [{"name": n, "value": v}, ...]}` when it is an `ActionRefusal`, else `null`. +[[nodiscard]] Value refusalValue(std::exception_ptr const& error) { + try { + std::rethrow_exception(error); + } catch (model::ActionRefusal const& refusal) { + ValueList args; + for (model::RefusalArg const& arg : refusal.args()) { + args.emplace_back(ValueRecord{{"name", Value{arg.name}}, {"value", Value{arg.value}}}); + } + return Value{ValueRecord{{"code", Value{refusal.code()}}, {"args", Value{std::move(args)}}}}; + } catch (...) { + return Value{}; + } +} + +} // namespace + +[[nodiscard]] std::string defaultErrorKind(std::exception_ptr const& error) { + try { + std::rethrow_exception(error); + } catch (backend::DisconnectedError const&) { + return "offline"; + } catch (backend::TimeoutError const&) { + return "timeout"; + } catch (backend::ClientTimeoutError const&) { + return "timeout"; + } catch (backend::BackendChangedError const&) { + return "backendChanged"; + } catch (model::ActionRefusal const&) { + // An action's own refusal is an answer about its data, whatever its message says, never the authoriser's. + return "error"; + } catch (wire::UnauthorizedError const&) { + // A refused control request (register, attach): its text carries the request's name before the refusal. + return "denied"; + } catch (std::runtime_error const& refused) { + // The authoriser says no to an execute with this one text; no exception type tells it from another failure. + return std::string_view{refused.what()} == wire::kUnauthorizedMessage ? "denied" : "error"; + } catch (...) { + return "error"; + } +} + +[[nodiscard]] std::string canonicalJson(Value const& value) { + return glz::write_json(valueToJson(value)).value_or(std::string{}); +} + +namespace { + +/// @brief A value with the field at @p path replaced, creating records along the way. +/// @param base The value written into. +/// @param path The field path. +/// @param value The new value at the path. +/// @return The new value. +// NOLINTNEXTLINE(misc-no-recursion): one level per path segment +[[nodiscard]] Value withPath(Value const& base, std::span path, Value value) { + if (path.empty()) { + return value; + } + ValueRecord fields; + if (ValueRecord const* const record = base.asRecord()) { + fields = *record; + } + Value const inner = base.field(path.front()) != nullptr ? *base.field(path.front()) : Value{}; + fields.insert_or_assign(path.front(), withPath(inner, path.subspan(1), std::move(value))); + return Value{std::move(fields)}; +} + +/// @brief A row's identity for `patch` and `optimistic`: its `id` field. +/// @param row The row. +/// @return The `id` field, or `null`. +[[nodiscard]] Value rowId(Value const& row) { + Value const* const found = row.field("id"); + return found == nullptr ? Value{} : *found; +} + +} // namespace + +[[nodiscard]] Value mergeRow(Value const& row, Value const& with) { + ValueRecord const* const fields = row.asRecord(); + ValueRecord const* const over = with.asRecord(); + if (fields == nullptr || over == nullptr) { + return with; + } + ValueRecord merged = *fields; + for (auto const& [name, field] : *over) { + merged.insert_or_assign(name, field); + } + return Value{std::move(merged)}; +} + +// NOLINTBEGIN(bugprone-easily-swappable-parameters): a list, a key and a row are distinct roles of one type. +[[nodiscard]] std::expected patchRows(Value const& value, std::string_view listMember, + Value const& key, Value const& with) { + // NOLINTEND(bugprone-easily-swappable-parameters) + ValueRecord const* const record = listMember.empty() ? nullptr : value.asRecord(); + if (!listMember.empty() && (record == nullptr || !record->contains(listMember))) { + return std::unexpected(PatchMiss::NoList); + } + Value const* const rows = record == nullptr ? &value : &record->find(listMember)->second; + ValueList const* const items = rows->asList(); + if (items == nullptr) { + return std::unexpected(PatchMiss::NoList); + } + if (key.isNull()) { + return std::unexpected(PatchMiss::NoRow); + } + ValueList out = *items; + bool found = false; + for (Value& row : out) { + if (rowId(row) == key) { + row = mergeRow(row, with); + found = true; + } + } + if (!found) { + return std::unexpected(PatchMiss::NoRow); + } + if (record == nullptr) { + return Value{std::move(out)}; + } + ValueRecord patched = *record; + patched.insert_or_assign(std::string{listMember}, Value{std::move(out)}); + return Value{std::move(patched)}; +} + +namespace { + +/// @brief What a patch that found no list reports. +/// @param query The query it patches. +/// @param listMember The record member it names; empty when none. +/// @return The diagnostic's reason. +[[nodiscard]] std::string patchMissReason(std::string_view query, std::string_view listMember) { + if (listMember.empty()) { + return "the value of `" + std::string{query} + + "` is not a list, so the patch changes nothing; `at` names the record member that holds the list"; + } + return "the value of `" + std::string{query} + "` has no list at `" + std::string{listMember} + + "`, so the patch changes nothing"; +} + +} // namespace + +// NOLINTNEXTLINE(misc-no-recursion): one level per nested list or record of the value. +[[nodiscard]] Value withoutFields(Value const& value, std::vector const& fields) { + if (fields.empty()) { + return value; + } + if (ValueRecord const* const record = value.asRecord()) { + ValueRecord kept = *record; + for (std::string const& field : fields) { + kept.erase(field); + } + return Value{std::move(kept)}; + } + if (ValueList const* const items = value.asList()) { + ValueList kept; + kept.reserve(items->size()); + for (Value const& item : *items) { + kept.push_back(withoutFields(item, fields)); + } + return Value{std::move(kept)}; + } + return value; +} + +namespace { + +/// @brief The members of a catalog record path: `"header.rows"` is `header`, then `rows`; `""` is none. +/// @param path The path. +/// @return Its members in order. +[[nodiscard]] std::vector pathMembers(std::string_view path) { + std::vector members; + for (auto const part : std::views::split(path, '.')) { + if (!part.empty()) { + members.emplace_back(part.begin(), part.end()); + } + } + return members; +} + +/// @brief The rows of a keyed record that a value holds at a path. +/// +/// A list on the way is looked through, as the result walker looks through a `std::vector`. At the path's end a +/// record with the key field is a row, and a record without it is a map whose values are the rows. +/// @param value The value. +/// @param path The members still to follow. +/// @param keyField The record's key field. +/// @param out Where the rows go. +// NOLINTNEXTLINE(misc-no-recursion): one level per path member or nested list. +void keyedRowsAt(Value const& value, std::span path, std::string_view keyField, + std::vector& out) { + if (ValueList const* const items = value.asList()) { + for (Value const& item : *items) { + keyedRowsAt(item, path, keyField, out); + } + return; + } + ValueRecord const* const record = value.asRecord(); + if (record == nullptr) { + return; + } + if (!path.empty()) { + if (auto const found = record->find(path.front()); found != record->end()) { + keyedRowsAt(found->second, path.subspan(1), keyField, out); + } + return; + } + if (record->contains(keyField)) { + out.push_back(&value); + return; + } + for (auto const& [name, item] : *record) { + static_cast(name); + if (ValueRecord const* const row = item.asRecord(); row != nullptr && row->contains(keyField)) { + out.push_back(&item); + } + } +} + +/// @brief Merges new rows over the rows with the same key that a value holds at a path. +/// @param value The value. +/// @param path The members still to follow. +/// @param keyField The record's key field. +/// @param rows The new rows. +/// @return The new value, or nothing when no row matched. +// NOLINTNEXTLINE(misc-no-recursion): one level per path member or nested list. +[[nodiscard]] std::optional patchKeyedRows(Value const& value, std::span path, + std::string_view keyField, RowsByKey const& rows) { + if (ValueList const* const items = value.asList()) { + ValueList out = *items; + bool changed = false; + for (Value& item : out) { + if (auto patched = patchKeyedRows(item, path, keyField, rows)) { + item = std::move(*patched); + changed = true; + } + } + return changed ? std::optional{Value{std::move(out)}} : std::nullopt; + } + ValueRecord const* const record = value.asRecord(); + if (record == nullptr) { + return std::nullopt; + } + if (!path.empty()) { + auto const found = record->find(path.front()); + if (found == record->end()) { + return std::nullopt; + } + auto patched = patchKeyedRows(found->second, path.subspan(1), keyField, rows); + if (!patched) { + return std::nullopt; + } + ValueRecord out = *record; + out.insert_or_assign(path.front(), std::move(*patched)); + return Value{std::move(out)}; + } + if (auto const key = record->find(keyField); key != record->end()) { + auto const row = rows.find(canonicalJson(key->second)); + return row == rows.end() ? std::nullopt : std::optional{mergeRow(value, *row->second)}; + } + ValueRecord out = *record; + bool changed = false; + for (auto& [name, item] : out) { + static_cast(name); + if (ValueRecord const* const row = item.asRecord(); row != nullptr && row->contains(keyField)) { + if (auto patched = patchKeyedRows(item, {}, keyField, rows)) { + item = std::move(*patched); + changed = true; + } + } + } + return changed ? std::optional{Value{std::move(out)}} : std::nullopt; +} + +} // namespace + +[[nodiscard]] std::vector keyedRowsOf(Value const& value, std::vector const& paths, + std::string_view keyField) { + std::vector rows; + for (std::string const& path : paths) { + std::vector const members = pathMembers(path); + keyedRowsAt(value, members, keyField, rows); + } + return rows; +} + +[[nodiscard]] std::optional patchHeldRows(Value const& value, std::vector const& paths, + std::string_view keyField, RowsByKey const& rows) { + std::optional patched; + for (std::string const& path : paths) { + std::vector const members = pathMembers(path); + auto next = patched ? patchKeyedRows(*patched, members, keyField, rows) + : patchKeyedRows(value, members, keyField, rows); + if (next) { + patched = std::move(next); + } + } + return patched; +} + +} // namespace detail + +std::shared_ptr BridgeDispatcher::bind(std::string const& typeId, bridge::BindSharing sharing, + std::string const& instanceKey) { + return std::make_shared(*_bridge, _cbExec, _evaluator, typeId, sharing, instanceKey); +} +async::Completion BridgeDispatcher::Channel::execute(std::string const& actionId, + std::string const& bodyJson, CallOptions options) { + if (options.evaluate) { + if (_evaluator) { + return _evaluator(_typeId, actionId, bodyJson); + } + auto [refused, promise] = async::Completion::makeSettleable(_cbExec); + promise.reject(std::make_exception_ptr(std::runtime_error{"evaluate needs the UI service"})); + return std::move(refused); + } + return _handler.execute(actionId, bodyJson); +} +ChannelFacts BridgeDispatcher::Channel::facts() const { + return ChannelFacts{.instanceId = _handler.instanceId(), .primary = _handler.primary()}; +} +bool InterpreterHost::navigate(NavigateRequest const& request, std::function onResult, + std::function onCancel) { + static_cast(request); + static_cast(onResult); + static_cast(onCancel); + return false; +} +bool InterpreterHost::closeSelf(std::string const& screen, std::optional result) { + static_cast(screen); + static_cast(result); + return false; +} +bool InterpreterHost::hostCommand(std::string const& name, Value const& args) { + static_cast(name); + static_cast(args); + return false; +} +bool InterpreterHost::switchBackend(std::string const& name, + std::function)> done) { + static_cast(name); + static_cast(done); + return false; +} +void InterpreterHost::resetPrefs(std::string const& screen, std::string const& point) { + static_cast(screen); + static_cast(point); +} +bool InterpreterHost::notify(std::string const& text, std::string const& role) { + static_cast(text); + static_cast(role); + return false; +} +bool InterpreterHost::signIn(Value const& reply) { + static_cast(reply); + return false; +} +bool InterpreterHost::setAppValue(std::string const& name, Value const& value) { + static_cast(name); + static_cast(value); + return false; +} +bool InterpreterHost::upload(Value const& file, std::function progress, + std::function)> done) { + static_cast(file); + static_cast(progress); + static_cast(done); + return false; +} +bool InterpreterHost::uploadFor(UploadRequest const& request, std::function progress, + std::function)> done) { + return upload(request.file, std::move(progress), std::move(done)); +} +bool InterpreterHost::download(Value const& file, std::string const& option, Value const& name, + std::function)> done) { + static_cast(file); + static_cast(option); + static_cast(name); + static_cast(done); + return false; +} +bool InterpreterHost::readFile(Value const& file, std::size_t maxBytes, + std::function)> done) { + static_cast(file); + static_cast(maxBytes); + static_cast(done); + return false; +} +bool InterpreterHost::saveFile(InlineFile const& file, std::string const& option, + std::function)> done) { + static_cast(file); + static_cast(option); + static_cast(done); + return false; +} +void InterpreterHost::preferenceChanged(std::string const& screen, std::string const& point, Value const& value) { + static_cast(screen); + static_cast(point); + static_cast(value); +} +bool Session::can(std::string_view action) const { + static constexpr std::string_view kHostPrefix = "host:"; + if (action.starts_with(kHostPrefix)) { + return _hostCommandNames.get().contains(action.substr(kHostPrefix.size())); + } + if (action == "context") { + return _contextOffered.get(); + } + return _permitted.get().contains(action); +} +void Session::setFormatLocale(std::string tag) { + _formatLocale = std::move(tag); + applyFacts(_format.peek()->locale); +} +std::shared_ptr Session::scopedFormatting(std::string_view tag) const { + FormatContext next = *_format.get(); + LocaleFacts const& facts = localeFacts(tag); + next.locale = std::string{tag}; + next.numeric = facts.numeric; + next.currency = facts.currency; + next.datePattern = _declaredDate.empty() ? std::string{facts.datePattern} : _declaredDate; + next.dateTimePattern = _declaredDateTime.empty() ? std::string{facts.dateTimePattern} : _declaredDateTime; + return std::make_shared(std::move(next)); +} +bool Session::firstUnlistedLocale(std::string const& tag) { + return findLocaleFacts(tag) == nullptr && _unlistedLocales.insert(tag).second; +} +void Session::setFormatting(FormatContext format) { + // One batch, so an effect never sees the new `env.locale` beside the old facts, and runs once. + _runtime->batch([this, &format] { + setEnvironmentValue("locale", Value{format.locale}); + _format.set(std::make_shared(std::move(format))); + }); +} +void Session::setDatePatterns(std::string date, std::string dateTime) { + _declaredDate = std::move(date); + _declaredDateTime = std::move(dateTime); + FormatContext next = *_format.peek(); + next.datePattern = _declaredDate.empty() ? _localeDate : _declaredDate; + next.dateTimePattern = _declaredDateTime.empty() ? _localeDateTime : _declaredDateTime; + setFormatting(std::move(next)); +} +void Session::setTranslations(render::TranslationProvider translations) { + FormatContext next = *_format.peek(); + next.translations = std::move(translations); + setFormatting(std::move(next)); +} +void Session::setEnvironment(ValueRecord values) { + values.insert_or_assign("locale", Value{_format.peek()->locale}); + _env.set(std::move(values)); +} +void Session::setEnvironmentValue(std::string const& name, Value value) { + ValueRecord env = _env.peek(); + env.insert_or_assign(name, std::move(value)); + _env.set(std::move(env)); +} +void Session::setHostCommands(HostCommands commands) { + _hostCommandRunner = std::move(commands.run); + _hostCommandNames.set(std::move(commands.available)); +} +std::function const& Session::hostCommandRunner() const noexcept { + return _hostCommandRunner; +} +Value Session::client(ExprKind form, std::string_view name) const { + ValueRecord const& values = [&]() -> ValueRecord const& { + if (form == ExprKind::Env) { + return _env.get(); + } + return form == ExprKind::Session ? _sessionValues.get() : _hostValues.get(); + }(); + auto const found = values.find(name); + return found == values.end() ? Value{} : found->second; +} +void Session::clear() { + _runtime->batch([this] { + for (auto const& [key, entry] : _entries) { + static_cast(key); + ++entry->generation; + entry->evict.cancel(); + countTopics(*entry, -1); + } + _entries.clear(); + for (detail::QueryRuntime* const query : _mounted) { + detachQuery(*query); + } + }); +} +void Session::prefetch(std::shared_ptr const& channel, std::string const& token, + std::string const& typeId, std::string const& action, Value const& body) { + auto entry = acquire(token, typeId, action, false, body); + if (!entry->pending.peek() && (!entry->hasValue.peek() || entry->stale)) { + fetch(entry, channel); + } + release(entry); +} +void Session::asUser(std::function const& body) { + ++_userDepth; + try { + body(); + } catch (...) { + --_userDepth; + throw; + } + --_userDepth; +} +std::string Session::cacheKey(std::string const& token, std::string const& typeId, std::string const& action, + bool evaluate, std::string const& body) { + return typeId + '\x1f' + token + '\x1f' + (evaluate ? "evaluate:" : "") + action + '\x1f' + body; +} +std::shared_ptr Session::acquire(std::string const& token, std::string const& typeId, + std::string const& action, bool evaluate, Value const& body) { + std::string const text = detail::canonicalJson(body); + std::string key = cacheKey(token, typeId, action, evaluate, text); + auto found = _entries.find(key); + if (found == _entries.end()) { + auto entry = std::make_shared(*_runtime); + entry->key = key; + entry->typeId = typeId; + entry->action = action; + entry->body = text; + entry->evaluate = evaluate; + entry->instanceToken = token; + if (_options.catalog.action) { + if (auto const info = _options.catalog.action(action)) { + entry->secretFields = info->secretFields; + if (!evaluate) { + entry->records = info->records; + } + } + } + countTopics(*entry, +1); + found = _entries.emplace(std::move(key), std::move(entry)).first; + } + ++found->second->users; + found->second->evict.cancel(); + return found->second; +} +void Session::release(std::shared_ptr const& entry) { + if (--entry->users > 0 || _options.scheduler == nullptr) { + return; + } + std::weak_ptr const weak = entry; + entry->evict = _options.scheduler->after(_options.keepUnused, [this, weak] { + auto const held = weak.lock(); + if (held && held->users == 0) { + countTopics(*held, -1); + _entries.erase(held->key); + flushWatches(); + } + }); +} +void Session::fetch(std::shared_ptr const& entry, std::shared_ptr const& channel) { + // The watch goes out before the read, on the same connection, so a change committed after the read is + // seen as an event. + flushWatches(); + std::uint64_t const generation = ++entry->generation; + if (channel == nullptr) { + settleFailure(*entry, "the model alias has no instance", "error"); + return; + } + entry->pending.set(true); + std::weak_ptr const weak = entry; + try { + auto completion = channel->execute(entry->action, entry->body, CallOptions{.evaluate = entry->evaluate}); + completion + .then([this, weak, generation](std::string const& reply) { + auto const held = weak.lock(); + if (held && held->generation == generation) { + settleReply(*held, reply); + } + }) + .onError([this, weak, generation](std::exception_ptr const& error) { + auto const held = weak.lock(); + if (held && held->generation == generation) { + settleFailure(*held, detail::failureText(error), classify(error), detail::refusalValue(error)); + } + }); + } catch (...) { + std::exception_ptr const error = std::current_exception(); + settleFailure(*entry, detail::failureText(error), classify(error), detail::refusalValue(error)); + } +} +void Session::confirm(detail::CacheEntry& entry, Value const& confirmed) { + entry.confirmed = detail::withoutFields(confirmed, entry.secretFields); + showLayers(entry); +} +void Session::showLayers(detail::CacheEntry& entry) { + Value shown = entry.confirmed; + for (detail::OptimisticLayer const& layer : entry.layers) { + if (auto patched = detail::patchRows(shown, layer.at, layer.key, layer.with)) { + shown = std::move(*patched); + } + } + noteWrite(); + entry.value.set(std::move(shown)); +} +std::string Session::classify(std::exception_ptr const& error) const { + return _options.classify ? _options.classify(error) : detail::defaultErrorKind(error); +} +std::chrono::milliseconds Session::now() const { + if (_options.clock) { + return _options.clock(); + } + return std::chrono::duration_cast(std::chrono::steady_clock::now().time_since_epoch()); +} +void Session::markStale(detail::CacheEntry& entry) { + entry.stale = true; + if (entry.pending.peek()) { + entry.refetchAfter = true; + } +} +SessionOptions Session::checkedOptions(SessionOptions options) { + if (options.maxInlineFileBytes == 0 || options.maxInlineFileBytes > kMaxInlineFileBytes) { + throw std::invalid_argument{"morph::ui::Session: maxInlineFileBytes is " + + std::to_string(options.maxInlineFileBytes) + "; it is 1 to " + + std::to_string(kMaxInlineFileBytes) + " (kMaxInlineFileBytes)"}; + } + return options; +} +void Session::settleReply(detail::CacheEntry& entry, std::string const& reply) { + auto json = parseJson(reply); + auto value = json ? valueFromJson(*json) : std::unexpected(json.error()); + if (!value) { + settleFailure(entry, "the reply is not a document value: " + value.error(), "error"); + return; + } + _runtime->batch([&] { + confirm(entry, *value); + entry.hasValue.set(true); + entry.error.set({}); + entry.errorKind.set({}); + entry.refusal.set(Value{}); + entry.pending.set(false); + entry.fetchedAt = now(); + entry.stale = entry.refetchAfter; + if (entry.refetchAfter) { + entry.refetchAfter = false; + refetchMounted(entry); + } + }); +} +void Session::settleFailure(detail::CacheEntry& entry, std::string text, std::string kind, Value refusal) { + _runtime->batch([&] { + noteWrite(); + entry.error.set(std::move(text)); + entry.errorKind.set(std::move(kind)); + entry.refusal.set(std::move(refusal)); + entry.pending.set(false); + }); +} +void Session::applyFacts(std::string locale) { + LocaleFacts const& facts = localeFacts(_formatLocale.empty() ? locale : _formatLocale); + _localeDate = std::string{facts.datePattern}; + _localeDateTime = std::string{facts.dateTimePattern}; + FormatContext next = *_format.peek(); + next.locale = std::move(locale); + next.numeric = facts.numeric; + next.currency = facts.currency; + next.datePattern = _declaredDate.empty() ? _localeDate : _declaredDate; + next.dateTimePattern = _declaredDateTime.empty() ? _localeDateTime : _declaredDateTime; + setFormatting(std::move(next)); +} +Screen::~Screen() { + try { + if (Commands const* const commands = lifecycleList("onUnmount")) { + runCommands(*commands); + } + } catch (...) { // NOLINT(bugprone-empty-catch): a destructor has no one to report to. + } + _core->focusElement = {}; + _mounted.reset(); + _headActions.clear(); + _headStatus.clear(); + _headMenu.clear(); + _headTools.clear(); + _scope.reset(); +} +Widget& Screen::root() const { + if (!_mounted) { + throw std::logic_error{"the screen is not mounted"}; + } + return _mounted->root(); +} +Value Screen::read(Json const& expression) const { + auto parsed = parseExpression(expression); + if (!parsed) { + return Value{}; + } + return detail::evalIn(*_scope, nullptr, *parsed); +} +auto Screen::boundAliases() const -> std::vector { + std::vector bound; + for (auto const& alias : _scope->models) { + if (alias->channel == nullptr) { + continue; + } + ChannelFacts facts = alias->channel->facts(); + if (facts.instanceId != 0) { + bound.push_back(BoundAlias{.decl = alias->decl, .facts = std::move(facts)}); + } + } + return bound; +} +std::vector Screen::status() const { + std::vector shown; + for (detail::BadgeModel const& badge : _headStatus) { + if (badge.visible.evaluate()) { + shown.push_back(HeadBadge{ + .text = badge.text.evaluate(), .tone = badge.tone.evaluate(), .icon = badge.icon.evaluate()}); + } + } + return shown; +} +std::vector Screen::actions() const { + std::vector shown; + for (detail::ActionModel const& action : _headActions) { + if (action.visible.evaluate()) { + shown.push_back(HeadAction{.id = action.id, + .label = action.label.evaluate(), + .icon = action.icon.evaluate(), + .iconOnly = action.iconOnly.evaluate(), + .emphasis = action.emphasis, + .enabled = action.enabled.evaluate()}); + } + } + return shown; +} +bool Screen::runAction(std::string_view actionId) { + auto const found = std::ranges::find(_headActions, actionId, &detail::ActionModel::id); + if (found == _headActions.end()) { + _core->report("/actions", "head action " + std::string{actionId} + " is unknown"); + return false; + } + auto const [visible, enabled] = + runtime().untracked([&] { return std::pair{found->visible.evaluate(), found->enabled.evaluate()}; }); + if (!visible || !enabled) { + _core->report(found->path, "head action " + found->id + (visible ? " is disabled" : " is hidden")); + return false; + } + if (found->run) { + found->run(); + } + return true; +} +std::string Screen::menuLabel() const { + if (!_core->doc().menuLabel) { + return "More actions"; + } + return detail::textOf(detail::evalIn(*_scope, nullptr, _core->doc().menuLabel), _scope->formatting()); +} +bool Screen::chooseMenuEntry(std::string_view entryId) { + FoundEntry const found = runtime().untracked([&] { return findHeadEntry(_headMenu, entryId, FoundEntry{}); }); + if (found.model == nullptr) { + _core->report("/menu", "head menu entry " + std::string{entryId} + " is unknown"); + return false; + } + if (!found.visible || !found.enabled) { + _core->report(found.model->path, + "head menu entry " + found.model->id + (found.visible ? " is disabled" : " is hidden")); + return false; + } + if (found.model->item.onSelect) { + found.model->item.onSelect(); + } + return true; +} +std::vector Screen::tools() const { + std::vector shown; + for (detail::HeadToolModel const& tool : _headTools) { + if (!tool.visible.evaluate()) { + continue; + } + bool const search = tool.kind == HeadToolKind::Search; + shown.push_back(HeadTool{.id = tool.id, + .kind = tool.kind, + .label = tool.label.evaluate(), + .value = search ? tool.value.evaluate() : std::string{}, + .placeholder = search ? tool.placeholder.evaluate() : std::string{}, + .options = search ? std::vector{} : tool.options.evaluate(), + .selected = search ? std::nullopt : tool.selected.evaluate(), + .width = tool.width, + .enabled = tool.enabled.evaluate()}); + } + return shown; +} +bool Screen::editTool(std::string_view toolId, Value const& value) { + detail::HeadToolModel const* const tool = usableTool(toolId); + if (tool == nullptr) { + return false; + } + if (tool->kind == HeadToolKind::Search && value.asString() == nullptr) { + _core->report(tool->path, "head tool " + tool->id + " is a search, edited with text"); + return false; + } + tool->edit(value); + return true; +} +bool Screen::submitTool(std::string_view toolId) { + detail::HeadToolModel const* const tool = usableTool(toolId); + if (tool == nullptr) { + return false; + } + if (tool->kind != HeadToolKind::Search) { + _core->report(tool->path, "head tool " + tool->id + " is a select, which is not submitted"); + return false; + } + tool->submit(Value{runtime().untracked([&] { return tool->value.evaluate(); })}); + return true; +} +bool Screen::dirty() const { + Value const value = detail::evalIn(*_scope, nullptr, _core->doc().dirty); + bool const* const flag = value.asBool(); + return flag != nullptr && *flag; +} +bool Screen::requestClose() { + std::shared_ptr const cancelled = beginClose(); + return cancelled == nullptr || !*cancelled; +} +std::shared_ptr Screen::beginClose() { + Commands const* const commands = lifecycleList("onClose"); + if (commands == nullptr) { + return nullptr; + } + return runCommandsFlag(*commands); +} +void Screen::runLifecycle(std::string_view key) { + if (Commands const* const commands = lifecycleList(key)) { + runCommands(*commands); + } +} +bool Screen::setPreference(std::string const& point, Value value) { + auto const found = _core->doc().customize.find(point); + if (found == _core->doc().customize.end() || !fits(found->second, value)) { + return false; + } + ValueRecord prefs = _core->prefs.peek(); + prefs.insert_or_assign(point, std::move(value)); + _core->prefs.set(std::move(prefs)); + return true; +} +std::map> Screen::ownState() const { + std::map> states; + for (auto const& slot : _scope->states) { + if (slot->value) { + states.insert_or_assign(slot->decl->name, detail::ScreenCore::KeptState{.type = slot->decl->type.name(), + .value = slot->value->peek()}); + } + } + return states; +} +Commands const* Screen::lifecycleList(std::string_view key) const { + auto const found = _core->doc().lifecycle.find(key); + return found == _core->doc().lifecycle.end() ? nullptr : &found->second; +} +std::shared_ptr Screen::runCommandsFlag(Commands const& commands) { + detail::CommandCtx const ctx{.scope = _scope, + .bindings = std::make_shared(), + .cancelClose = std::make_shared(false), + .boundary = nullptr}; + _core->runtime().batch([&] { _core->runList(commands, ctx, {}); }); + return ctx.cancelClose; +} +bool Screen::fits(CustomizePoint const& point, Value const& value) { + if (point.kind == "choice") { + std::string const* const text = value.asString(); + return text != nullptr && listed(std::span{point.options}, *text); + } + if (point.kind == "value") { + return point.type.admits(value); + } + return true; +} +bool Screen::listed(std::span options, std::string const& text) { + return std::ranges::find(options, text) != options.end(); +} +detail::HeadToolModel const* Screen::usableTool(std::string_view toolId) const { + auto const found = std::ranges::find(_headTools, toolId, &detail::HeadToolModel::id); + if (found == _headTools.end()) { + _core->report("/tools", "head tool " + std::string{toolId} + " is unknown"); + return nullptr; + } + auto const [visible, enabled] = + runtime().untracked([&] { return std::pair{found->visible.evaluate(), found->enabled.evaluate()}; }); + if (!visible || !enabled) { + _core->report(found->path, "head tool " + found->id + (visible ? " is disabled" : " is hidden")); + return nullptr; + } + return &*found; +} +auto Screen::findHeadEntry(std::vector const& level, std::string_view entryId, + FoundEntry const& outer) -> FoundEntry { + for (detail::HeadMenuModel const& model : level) { + FoundEntry const here{.model = &model, + .visible = outer.visible && model.item.visible.evaluate(), + .enabled = outer.enabled && model.item.enabled.evaluate()}; + if (!model.id.empty() && model.id == entryId) { + return here; + } + if (FoundEntry const inner = findHeadEntry(model.items, entryId, here); inner.model != nullptr) { + return inner; + } + } + return FoundEntry{}; +} +std::vector Screen::shownHeadMenu(std::vector const& level) { + std::vector shown; + for (detail::HeadMenuModel const& model : level) { + MenuItem const& item = model.item; + if (item.separator) { + if (!shown.empty() && !shown.back().separator) { + shown.push_back(HeadMenuEntry{.separator = true}); + } + continue; + } + if (!item.visible.evaluate()) { + continue; + } + shown.push_back(HeadMenuEntry{.id = model.id, + .label = item.label.evaluate(), + .icon = item.icon, + .keys = item.keys, + .checked = item.checked.evaluate(), + .enabled = item.enabled.evaluate(), + .items = shownHeadMenu(model.items), + .separator = false, + .description = item.description.evaluate()}); + } + if (!shown.empty() && shown.back().separator) { + shown.pop_back(); + } + return shown; +} +AppRoot::~AppRoot() { + try { + if (auto const found = _core->doc().lifecycle.find("onUnmount"); found != _core->doc().lifecycle.end()) { + runCommands(found->second); + } + } catch (...) { // NOLINT(bugprone-empty-catch): a destructor has no one to report to. + } + // The counts read the scope, so they go before it. + _navigationBadges.reset(); + _navigation.clear(); + _core->session.setAppScope(nullptr); + _scope.reset(); +} +reactive::Computed> const& AppRoot::navigationBadges() const { + return *_navigationBadges; +} +PrincipalPlacement AppRoot::principalPlacement() const noexcept { + return _core->doc().principalPlacement == "head" ? PrincipalPlacement::Head : PrincipalPlacement::Sidebar; +} +Value AppRoot::read(Json const& expression) const { + auto parsed = parseExpression(expression); + if (!parsed) { + return Value{}; + } + return detail::evalIn(*_scope, nullptr, *parsed); +} +auto AppRoot::query(std::string_view name) const -> QueryRead { + detail::NameRef const* const found = _scope->find(name); + if (found == nullptr || found->category != detail::NameCategory::Query) { + return QueryRead{}; + } + detail::QueryRuntime const& runtime = *found->query; + Value const error = runtime.error(); + Value const kind = runtime.errorKind(); + std::string const* const kindText = kind.asString(); + return QueryRead{.value = runtime.value(), + .pending = runtime.pending(), + .failed = !error.isNull(), + .declared = true, + .denied = kindText != nullptr && *kindText == "denied"}; +} +bool AppRoot::setState(std::string_view name, Value value) { + detail::NameRef const* const found = _scope->find(name); + if (found == nullptr || found->category != detail::NameCategory::State) { + return false; + } + detail::StateSlot& slot = *found->state; + slot.scope->core.initState(*slot.scope, slot); + _core->session.noteWrite(); + slot.value->set(std::move(value)); + return true; +} +bool AppRoot::runMutation(std::string_view name, Value body, std::function done) { + detail::NameRef const* const found = _scope->find(name); + if (found == nullptr || found->category != detail::NameCategory::Mutation) { + return false; + } + detail::MutationRuntime& mutation = *found->mutation; + _core->runtime().batch([&] { + mutation.run(std::move(body), std::make_shared(), + [done = std::move(done)](bool succeeded, Value const& /*reply*/) { + if (done) { + done(succeeded); + } + }); + }); + return true; +} +void AppRoot::runCommands(Commands const& commands) { + detail::CommandCtx const ctx{.scope = _scope, + .bindings = std::make_shared(), + .cancelClose = std::make_shared(false), + .boundary = nullptr}; + _core->runtime().batch([&] { _core->runList(commands, ctx, {}); }); +} + +namespace detail { + +ActionRecordInfo const* CacheEntry::holding(std::string_view record) const { + auto const found = std::ranges::find(records, record, &ActionRecordInfo::record); + return found == records.end() ? nullptr : &*found; +} + +void Marks::add(CacheEntry& entry) { + if (std::ranges::find(entries, &entry) == entries.end()) { + entries.push_back(&entry); + } +} + +CheckRuntime::~CheckRuntime() { + for (ElementState* const target : targets) { + std::erase(target->checks, this); + target->checksVersion.set(target->checksVersion.peek() + 1); + } +} + +NameRef const* RtScope::find(std::string_view name) const { + for (RtScope const* scope = this; scope != nullptr; scope = scope->parent.get()) { + auto const found = scope->names.find(name); + if (found != scope->names.end()) { + return &found->second; + } + } + return nullptr; +} + +reactive::Signal const* RtScope::innermostRow() const { + for (RtScope const* scope = this; scope != nullptr; scope = scope->parent.get()) { + if (scope->row != nullptr) { + return scope->row; + } + } + return nullptr; +} + +RtScope const& RtScope::policyScope() const { + RtScope const* scope = this; + while (scope->submitted == nullptr && scope->parent != nullptr) { + scope = scope->parent.get(); + } + return *scope; +} + +Value ScopeEnv::row(std::span path) const { + if (_row != nullptr) { + return walk(*_row, path); + } + reactive::Signal const* const current = _scope->innermostRow(); + return current == nullptr ? Value{} : walk(current->get(), path); +} + +void QueryRuntime::invalidate() { + if (auto const& current = _entry.peek()) { + current->stale = true; + } + refetch(); +} + +void QueryRuntime::detach() { + _entry.set(nullptr); + _carried.set(Value{}); + _target = {}; +} + +bool QueryRuntime::Target::operator==(Target const& other) const { + return idle == other.idle && token == other.token && bodyText == other.bodyText; +} + +ScreenCore::ScreenCore(std::shared_ptr doc, Session& owner, Dispatcher& calls, + InterpreterOptions const& options, MountOptions const& mount) + : session{owner}, + dispatcher{calls}, + host{options.host}, + onDiagnostic{options.diagnostics}, + borrowed{mount.borrowed}, + depth{mount.depth}, + prefs{session.runtime()}, + submitted{session.runtime(), false}, + pendingWork{session.runtime(), 0}, + recording{owner.options().developmentTools == DevelopmentTools::On}, + _doc{std::move(doc)} { + ValueRecord defaults; + for (auto const& [name, point] : _doc->customize) { + defaults.insert_or_assign(name, point.defaultValue); + } + prefDefaults = defaults; + prefs.set(std::move(defaults)); + session.attachScreen(*this); +} + +void ScreenCore::runLifecycleOf(std::string_view key) { + auto const found = _doc->lifecycle.find(key); + auto const scope = rootScope.lock(); + if (found == _doc->lifecycle.end() || !scope) { + return; + } + CommandCtx const ctx{.scope = scope, + .bindings = std::make_shared(), + .cancelClose = std::make_shared(false), + .boundary = nullptr}; + runList(found->second, ctx, {}); +} + +void ScreenCore::report(std::string_view path, std::string_view reason) { + if (inspecting) { + return; + } + std::string key = std::string{path} + '\x1f' + std::string{reason}; + if (!reported.insert(std::move(key)).second) { + return; + } + Refusal const refusal{.document = _doc->id, .path = std::string{path}, .reason = std::string{reason}}; + diagnostics.push_back(refusal); + if (onDiagnostic) { + onDiagnostic(refusal); + } +} + +void ScreenCore::initState(RtScope const& scope, StateSlot& slot) const { + if (slot.value || slot.initializing) { + return; + } + if (std::optional keptValue = keptState(scope, *slot.decl)) { + slot.value = std::make_unique>(runtime(), std::move(*keptValue)); + return; + } + slot.initializing = true; + Value init = runtime().untracked([&] { return evalIn(scope, nullptr, slot.decl->init); }); + slot.value = std::make_unique>(runtime(), std::move(init)); + slot.initializing = false; +} + +void ScreenCore::runEvent(Commands const* commands, LowerCtx const& ctx, Value event) { + if (commands == nullptr || commands->empty()) { + return; + } + auto bindings = std::make_shared(*ctx.bindings); + bindings->push_back(Binding{.name = "event", .read = [event = std::move(event)] { return event; }}); + CommandCtx const command{.scope = ctx.scope, + .bindings = std::move(bindings), + .cancelClose = std::make_shared(false), + .boundary = ctx.boundary}; + session.asUser([&] { runtime().batch([&] { runList(*commands, command, {}); }); }); +} + +std::optional ScreenCore::keptState(RtScope const& scope, StateDecl const& decl) const { + if (keptStates.empty() || rootScope.lock().get() != &scope) { + return std::nullopt; + } + auto const found = keptStates.find(decl.name); + if (found == keptStates.end() || found->second.type != decl.type.name() || + !decl.type.admits(found->second.value)) { + return std::nullopt; + } + return found->second.value; +} + +bool ScreenCore::unsupported(Command const& command, std::string_view what) { + report(command.path, std::string{what} + " is not supported by the host"); + return false; +} + +Value ScreenCore::once(LowerCtx const& ctx, ExprPtr const& expr) const { + return runtime().untracked([&] { return evalIn(*ctx.scope, ctx.bindings.get(), expr); }); +} + +void ScreenCore::logList(Commands const& commands) { + CommandLogEntry entry{.event = {}, .commands = {}, .batch = runtime().core()->currentBatch()}; + std::string_view const first = commands.front().path; + entry.event = std::string{first.substr(0, first.rfind('/') == std::string_view::npos ? 0 : first.rfind('/'))}; + for (Command const& command : commands) { + entry.commands.push_back( + LoggedCommand{.kind = commandKey(command.kind), .target = command.target, .path = command.path}); + } + if (commandLog.size() == kCommandLogSize) { + commandLog.pop_front(); + } + commandLog.push_back(std::move(entry)); +} + +} // namespace detail + +void Session::backendChanged(std::string const& backend) { + _runtime->batch([this, &backend] { + std::vector const screens = _screens; + for (detail::ScreenCore* const screen : screens) { + if (std::ranges::find(_screens, screen) != _screens.end()) { + screen->runLifecycleOf("onBackendChange"); + } + } + ValueRecord env = _env.peek(); + env.insert_or_assign("backend", Value{backend}); + _env.set(std::move(env)); + for (auto const& [key, entry] : _entries) { + static_cast(key); + markStale(*entry); + } + std::vector const mounted = _mounted; + for (detail::QueryRuntime* const query : mounted) { + query->refetchCurrent(); + } + }); +} + +void Session::refetchMounted(detail::CacheEntry const& entry) { + std::vector const mounted = _mounted; + for (detail::QueryRuntime* const query : mounted) { + if (_runtime->untracked([query] { return query->entry(); }).get() == &entry) { + query->refetchCurrent(); + } + } +} + +// NOLINTNEXTLINE(bugprone-easily-swappable-parameters): a model type and an action id, as every caller names them. +void Session::applyReplyEffects(std::string const& typeId, std::string const& actionId, Value const& reply, + ReplyUse use, std::string const& instanceToken) { + if (!_options.catalog.action) { + return; + } + std::optional const info = _options.catalog.action(actionId); + if (!info || !info->effects) { + return; + } + detail::Marks marks; + for (ActionEffect const& effect : *info->effects) { + if (effect.kind == "changesInstance") { + for (auto const& [key, entry] : _entries) { + static_cast(key); + if (!entry->evaluate && entry->typeId == typeId && entry->instanceToken == instanceToken) { + marks.add(*entry); + } + } + } else if (effect.record && (effect.kind == "updates" || effect.kind == "changes")) { + applyRecordEffect(effect, *effect.record, *info, reply, use, marks); + } + } + markAndRefetch(marks); +} + +void Session::applyRecordEffect(ActionEffect const& effect, std::string const& record, ActionInfo const& info, + Value const& reply, ReplyUse use, detail::Marks& marks) { + // The reply's rows of the record, by key; none when the reply does not hold it keyed, or must only mark. + auto const own = std::ranges::find(info.records, record, &ActionRecordInfo::record); + std::optional const ownKey = + effect.kind == "updates" && use == ReplyUse::Applied && own != info.records.end() ? own->keyField + : std::nullopt; + detail::RowsByKey rows; + if (ownKey) { + for (Value const* const row : detail::keyedRowsOf(reply, own->paths, *ownKey)) { + rows.insert_or_assign(detail::canonicalJson(*row->field(*ownKey)), row); + } + } + for (auto const& [key, entry] : _entries) { + static_cast(key); + ActionRecordInfo const* const held = entry->holding(record); + if (held == nullptr) { + continue; + } + if (!ownKey || !held->keyField) { + marks.add(*entry); + continue; + } + if (auto patched = detail::patchHeldRows(entry->confirmed, held->paths, *held->keyField, rows)) { + confirm(*entry, *patched); + } + // A fetch in flight may have read before the write, and would settle over the patch. + if (entry->pending.peek()) { + markStale(*entry); + } + } +} + +void Session::markAndRefetch(detail::Marks const& marks) { + for (detail::CacheEntry* const entry : marks.entries) { + markStale(*entry); + } + for (detail::CacheEntry const* const entry : marks.entries) { + refetchMounted(*entry); + } +} + +void Session::countTopics(detail::CacheEntry const& entry, int delta) { + if (entry.evaluate) { + return; + } + // One topic: its count, and the queues a change of the count from or to zero goes to. + auto const count = [delta](auto& refs, auto const& topic, auto& watches, auto& unwatches) { + int& refsOf = refs[topic]; + refsOf += delta; + if (delta > 0 && refsOf == 1 && unwatches.erase(topic) == 0) { + watches.insert(topic); + } else if (refsOf <= 0) { + refs.erase(topic); + if (watches.erase(topic) == 0) { + unwatches.insert(topic); + } + } + }; + if (!entry.records.empty()) { + for (ActionRecordInfo const& record : entry.records) { + count(_recordRefs, record.record, _watchRecords, _unwatchRecords); + } + return; + } + constexpr std::string_view kShared = "shared:"; + if (entry.instanceToken.starts_with(kShared)) { + count(_instanceRefs, std::pair{entry.typeId, entry.instanceToken.substr(kShared.size())}, _watchInstances, + _unwatchInstances); + } +} + +void Session::sendWatch(std::string_view kind, wire::WatchBody const& body) const { + auto completion = _options.watcher(std::string{kind}, glz::write_json(body).value_or(std::string{})); + completion.then([](std::string const&) {}).onError([](std::exception_ptr const&) {}); +} + +void Session::flushWatches() { + if (!_options.watcher) { + _watchRecords.clear(); + _unwatchRecords.clear(); + _watchInstances.clear(); + _unwatchInstances.clear(); + return; + } + auto const take = [](auto& records, auto& instances) { + wire::WatchBody body; + body.records.assign(records.begin(), records.end()); + for (auto const& [modelType, primary] : instances) { + body.instances.push_back(wire::InstanceTopic{.modelType = modelType, .primary = primary, .instance = 0}); + } + records.clear(); + instances.clear(); + return body; + }; + if (!_watchRecords.empty() || !_watchInstances.empty()) { + sendWatch(wire::kWatchKind, take(_watchRecords, _watchInstances)); + } + if (!_unwatchRecords.empty() || !_unwatchInstances.empty()) { + sendWatch(wire::kUnwatchKind, take(_unwatchRecords, _unwatchInstances)); + } +} + +wire::WatchBody Session::watchSet() const { + wire::WatchBody body; + for (auto const& [record, refs] : _recordRefs) { + static_cast(refs); + body.records.push_back(record); + } + for (auto const& [topic, refs] : _instanceRefs) { + static_cast(refs); + body.instances.push_back( + wire::InstanceTopic{.modelType = topic.first, .primary = topic.second, .instance = 0}); + } + return body; +} + +void Session::markAllStale() { + _runtime->batch([this] { + detail::Marks marks; + for (auto const& [key, entry] : _entries) { + static_cast(key); + if (!entry->evaluate) { + marks.add(*entry); + } + } + markAndRefetch(marks); + }); +} + +void Session::reconnected() { + // The whole set replaces what the server holds, so the queued changes are superseded. + _watchRecords.clear(); + _unwatchRecords.clear(); + _watchInstances.clear(); + _unwatchInstances.clear(); + if (_options.watcher) { + wire::WatchBody body = watchSet(); + body.replace = true; + sendWatch(wire::kWatchKind, body); + } + markAllStale(); +} + +void Session::deliverEvent(wire::EventBody const& event) { + if (event.topic == wire::kResyncTopic) { + reconnected(); + return; + } + if (event.topic != wire::kChangesTopic) { + return; + } + if (auto changes = wire::readChangesBody(event.payload.str)) { + applyChanges(*changes); + } +} + +void Session::applyChanges(wire::ChangesBody const& changes) { + _runtime->batch([&] { + detail::Marks marks; + for (effects::RecordChange const& change : changes.records) { + markRecordChange(change, marks); + } + for (wire::InstanceTopic const& instance : changes.instances) { + markInstanceChange(instance, marks); + } + markAndRefetch(marks); + }); +} + +void Session::markRecordChange(effects::RecordChange const& change, detail::Marks& marks) { + // The keys' canonical text, so a key the server wrote is compared with the rows' own. + std::set> keys; + for (glz::raw_json const& key : change.keys.value_or(std::vector{})) { + auto json = parseJson(key.str); + auto value = json ? valueFromJson(*json) : std::unexpected(json.error()); + if (value) { + keys.insert(detail::canonicalJson(*value)); + } + } + for (auto const& [name, entry] : _entries) { + static_cast(name); + ActionRecordInfo const* const held = entry->holding(change.record); + if (held == nullptr) { + continue; + } + // An entry still waiting for its first value may come to hold a key; keyless rows cannot be told apart. + if (!change.keys || !held->keyField || !entry->hasValue.peek()) { + marks.add(*entry); + continue; + } + std::string const& keyField = *held->keyField; + bool const holdsKey = std::ranges::any_of( + detail::keyedRowsOf(entry->confirmed, held->paths, keyField), + [&](Value const* row) { return keys.contains(detail::canonicalJson(*row->field(keyField))); }); + if (holdsKey) { + marks.add(*entry); + } + } +} + +void Session::markInstanceChange(wire::InstanceTopic const& instance, detail::Marks& marks) { + std::string const shared = "shared:" + instance.primary; + for (auto const& [name, entry] : _entries) { + static_cast(name); + if (entry->evaluate || entry->typeId != instance.modelType) { + continue; + } + // Without a primary key, the instance is one of the connection's own private ones. + bool const same = + instance.primary.empty() ? !entry->instanceToken.starts_with("shared") : entry->instanceToken == shared; + if (same) { + marks.add(*entry); + } + } +} + +void Session::actionSucceeded(std::string const& typeId, std::string const& actionId, Value const& reply, ReplyUse use, + std::string const& instanceToken) { + _runtime->batch([&] { applyReplyEffects(typeId, actionId, reply, use, instanceToken); }); +} + +void Session::detachQuery(detail::QueryRuntime& query) { query.detach(); } + +namespace detail { + +[[nodiscard]] std::string instanceKeyText(Value const& key) { + if (key.isNull()) { + return {}; + } + if (std::int64_t const* const number = key.asInt()) { + return std::to_string(*number); + } + if (std::string const* const text = key.asString()) { + return *text; + } + return canonicalJson(key); +} +namespace { + +/// @brief The channel an alias is bound to for its current token, binding it when the token changed. +/// @param alias The alias. +/// @param core The screen. +/// @return The channel, or `nullptr` while the alias is unbound. +[[nodiscard]] std::shared_ptr channelOf(ModelAlias& alias, ScreenCore& core) { + std::string const token = core.runtime().untracked([&] { return alias.token->get(); }); + if (token.empty()) { + return nullptr; + } + if (alias.channel && alias.boundToken == token) { + return alias.channel; + } + std::string const& type = alias.decl->type; + switch (alias.mode) { + case InstanceMode::Borrowed: { + auto const found = core.borrowed.find(alias.decl->name); + alias.channel = found == core.borrowed.end() ? nullptr : found->second.channel; + break; + } + case InstanceMode::Shared: + // `shared` is for a stateless model, whose instances are interchangeable: its calls go to an instance of + // the alias's own, and what it shares with other screens is the query cache, through the token. + alias.channel = core.dispatcher.bind(type, bridge::BindSharing::Private, {}); + break; + case InstanceMode::Keyed: + alias.channel = core.dispatcher.bind(type, bridge::BindSharing::Shared, token.substr(7)); + break; + case InstanceMode::Private: + case InstanceMode::Default: + default: + alias.channel = core.dispatcher.bind(type, bridge::BindSharing::Private, {}); + break; + } + alias.boundToken = token; + return alias.channel; +} +} // namespace + +RtScope::RtScope(ScreenCore& screen, std::shared_ptr enclosing, reactive::Signal const* current, + std::size_t depth) + : core{screen}, parent{std::move(enclosing)}, row{current}, nodes{screen.runtime(), depth} { + if (core.recording) { + core.scopes.push_back(this); + } +} + +RtScope::~RtScope() { + if (core.recording) { + std::erase(core.scopes, this); + } + if (owner != nullptr) { + core.addPending(-1); + if (owner->inner.peek() == this) { + owner->inner.set(nullptr); + } + } +} + +// NOLINTNEXTLINE(misc-no-recursion): an element's value can read a nested scope's readiness, one level per nesting. +bool RtScope::ready() const { + for (auto const& element : elements) { + Value const shown = core.elementValue(*element, "visible"); + bool const* const visible = shown.asBool(); + ValueList const* const errors = element->errors->get().asList(); + if ((visible == nullptr || *visible) && errors != nullptr && !errors->empty()) { + return false; + } + } + for (auto const& check : checks) { + if (check->decl->blocking && check->failing->get()) { + return false; + } + } + return true; +} + +// NOLINTNEXTLINE(misc-no-recursion): an `app.` name is read in the root scope with its head consumed, once per segment. +Value ScopeEnv::ref(std::string_view head, std::span path) const { + if (head == "app") { + RtScope const* const app = _scope->core.session.appScope(); + if (app == nullptr || path.empty()) { + return Value{}; + } + return ScopeEnv{*app, nullptr}.ref(path.front(), path.subspan(1)); + } + if (_bindings != nullptr) { + for (Binding const& bound : std::views::reverse(*_bindings)) { + if (bound.name == head) { + return walk(bound.read(), path); + } + } + } + NameRef const* const name = _scope->find(head); + if (name == nullptr) { + return Value{}; + } + switch (name->category) { + case NameCategory::Param: + return walk(name->param, path); + case NameCategory::State: + _scope->core.initState(*name->state->scope, *name->state); + // State inits are acyclic (`loadDocument` checks it), so the value is made by now. + return walk(name->state->value->get(), path); + case NameCategory::Let: + return walk(name->let->get(), path); + case NameCategory::Query: + return walk(name->query->value(), path); + case NameCategory::Element: + if (path.empty()) { + return Value{}; + } + return walk(_scope->core.elementValue(*name->element, path.front()), path.subspan(1)); + case NameCategory::Transfer: { + if (path.empty()) { + return Value{}; + } + TransferState const& transfer = *name->transfer; + Value value; + if (path.front() == "progress") { + value = transfer.progress.get(); + } else if (path.front() == "pending") { + value = Value{transfer.pending.get()}; + } else if (path.front() == "error") { + value = transfer.error.get(); + } + return walk(value, path.subspan(1)); + } + case NameCategory::Model: + case NameCategory::Mutation: + default: + return Value{}; + } +} + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per control form and kind of name. +Value ScopeEnv::control(ExprKind form, std::string_view name) const { + Session const& session = _scope->core.session; + NameRef const* const found = _scope->find(name); + if (form == ExprKind::Can) { + if (found != nullptr && found->category == NameCategory::Query) { + return session.can(found->query->decl().action); + } + if (found != nullptr && found->category == NameCategory::Mutation) { + return session.can(found->mutation->decl().action); + } + return session.can(name); + } + if (found != nullptr && found->category == NameCategory::Query) { + QueryRuntime const& query = *found->query; + if (form == ExprKind::Query) { + return query.value(); + } + if (form == ExprKind::Pending) { + return query.pending(); + } + if (form == ExprKind::Error) { + return query.error(); + } + if (form == ExprKind::Refusal) { + return query.refusal(); + } + return form == ExprKind::ErrorKind ? query.errorKind() : Value{}; + } + if (found != nullptr && found->category == NameCategory::Mutation) { + MutationRuntime const& mutation = *found->mutation; + if (form == ExprKind::Result) { + return mutation.result(); + } + if (form == ExprKind::Pending) { + return mutation.pending(); + } + if (form == ExprKind::Error) { + return mutation.error(); + } + if (form == ExprKind::Refusal) { + return mutation.refusal(); + } + return form == ExprKind::ErrorKind ? mutation.errorKind() : Value{}; + } + return Value{}; +} + +Value ScopeEnv::pref(std::string_view point, std::span path) const { + ValueRecord const& prefs = _scope->core.prefs.get(); + auto const found = prefs.find(point); + return found == prefs.end() ? Value{} : walk(found->second, path); +} + +Value ScopeEnv::client(ExprKind form, std::string_view name) const { return _scope->core.session.client(form, name); } + +FormatContext const& RtScope::formatting() const { + for (RtScope const* scope = this; scope != nullptr; + scope = scope->parent != nullptr ? scope->parent.get() : scope->formatSource.get()) { + if (scope->localeFormat != nullptr) { + return *scope->localeFormat->get(); + } + } + return core.session.formatting(); +} + +FormatContext const& ScopeEnv::formatting() const { return _scope->formatting(); } + +FormatContext const& ScopeEnv::entryFormatting() const { return _scope->core.session.formatting(); } + +void ScopeEnv::report(std::string_view path, std::string_view reason) const { _scope->core.report(path, reason); } + +// --- Queries --------------------------------------------------------------------------------------------------- + +QueryRuntime::QueryRuntime(QueryDecl const& decl, RtScope& scope, ModelAlias* alias) + : _decl{&decl}, + _typeId{alias->decl->type}, + _scope{&scope}, + _alias{alias}, + _entry{scope.core.runtime()}, + _carried{scope.core.runtime()}, + _waiting{scope.core.runtime(), false} { + scope.core.session.attachQuery(*this); +} + +QueryRuntime::~QueryRuntime() { + _debounce.cancel(); + _refresh.cancel(); + _scope->core.session.forgetQuery(*this); + if (auto const& current = _entry.peek()) { + _scope->core.session.release(current); + } +} + +std::shared_ptr QueryRuntime::channel() const { return channelOf(*_alias, _scope->core); } + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): the query's key, its fetch and its refresh triggers. +void QueryRuntime::start() { + RtScope& scope = *_scope; + auto& key = scope.nodes.computed([this]() -> Target { + Target target; + if (_decl->when) { + Value const when = evalIn(*_scope, nullptr, _decl->when); + bool const* const flag = when.asBool(); + if (flag == nullptr || !*flag) { + return target; + } + } + std::string token = _alias->token->get(); + if (token.empty()) { + return target; + } + Value body = _decl->body ? evalIn(*_scope, nullptr, _decl->body) : Value{ValueRecord{}}; + if (body.isNull()) { + return target; + } + target.idle = false; + target.token = std::move(token); + target.bodyText = canonicalJson(body); + target.body = std::move(body); + return target; + }); + _key = &key; + reactive::Scheduler* const scheduler = scope.core.session.options().scheduler; + std::weak_ptr const alive = _alive; + scope.nodes.effect([this, &key, scheduler, alive, first = true]() mutable { + Target target = key.get(); + _scope->core.runtime().untracked([&] { + if (first || target.idle || _decl->debounce <= 0 || scheduler == nullptr) { + first = false; + _debounce.cancel(); + _waiting.set(false); + switchTo(target); + return; + } + _pendingTarget = std::move(target); + _waiting.set(true); + _debounce = scheduler->after(std::chrono::milliseconds{_decl->debounce}, [this, alive] { + if (alive.expired()) { + return; + } + _scope->core.runtime().batch([this] { + _waiting.set(false); + switchTo(_pendingTarget); + }); + }); + }); + }); + if (_decl->refreshEvery > 0 && scheduler != nullptr) { + _refresh = scheduler->every(std::chrono::milliseconds{_decl->refreshEvery}, [this, alive] { + if (alive.expired()) { + return; + } + auto const current = _entry.peek(); + if (!current || _waiting.peek() || current->pending.peek()) { + return; + } + _scope->core.runtime().batch([&] { _scope->core.session.fetch(current, channel()); }); + }); + } +} + +void QueryRuntime::switchTo(Target const& target) { + Session& session = _scope->core.session; + std::shared_ptr const old = _entry.peek(); + if (old && target == _target) { + return; + } + Value shown = old && old->hasValue.peek() ? old->value.peek() : _carried.peek(); + _target = target; + if (target.idle) { + _carried.set(Value{}); + _entry.set(nullptr); + if (old) { + session.release(old); + } + return; + } + auto fresh = session.acquire(target.token, _typeId, _decl->action, _decl->evaluate, target.body); + _carried.set(std::move(shown)); + _entry.set(fresh); + if (old) { + session.release(old); + } + bool const young = fresh->fetchedAt.has_value() && + session.now() - *fresh->fetchedAt < std::chrono::milliseconds{_decl->staleTime}; + if (!fresh->pending.peek() && (!fresh->hasValue.peek() || fresh->stale || !young)) { + session.fetch(fresh, channel()); + } +} + +void QueryRuntime::refetch() { + _scope->core.runtime().batch([this] { + bool switched = false; + if (_waiting.peek()) { + _debounce.cancel(); + _waiting.set(false); + switchTo(_pendingTarget); + switched = true; + } + auto const current = _entry.peek(); + if (current && !(switched && current->pending.peek())) { + _scope->core.session.fetch(current, channel()); + } + }); +} + +void QueryRuntime::refetchCurrent() { + if (_key == nullptr) { + refetch(); + return; + } + _scope->core.runtime().batch([this] { + _debounce.cancel(); + _waiting.set(false); + Target const target = _key->peek(); + if (!(_entry.peek() && target == _target)) { + switchTo(target); + return; + } + if (auto const current = _entry.peek(); current && !current->pending.peek()) { + _scope->core.session.fetch(current, channel()); + } + }); +} + +Value QueryRuntime::value() const { + auto const& current = _entry.get(); + if (current) { + if (current->hasValue.get()) { + return current->value.get(); + } + if (!current->error.get().empty()) { + return Value{}; + } + } + return _carried.get(); +} + +bool QueryRuntime::pending() const { + if (_waiting.get()) { + return true; + } + auto const& current = _entry.get(); + return current && current->pending.get(); +} + +Value QueryRuntime::error() const { + auto const& current = _entry.get(); + if (!current || current->error.get().empty()) { + return Value{}; + } + return Value{current->error.get()}; +} + +Value QueryRuntime::errorKind() const { + auto const& current = _entry.get(); + if (!current || current->errorKind.get().empty()) { + return Value{}; + } + return Value{current->errorKind.get()}; +} + +Value QueryRuntime::refusal() const { + auto const& current = _entry.get(); + return current ? current->refusal.get() : Value{}; +} + +bool QueryRuntime::settled() const { + auto const& current = _entry.get(); + return !current || current->hasValue.get() || !current->error.get().empty(); +} + +// --- Mutations ------------------------------------------------------------------------------------------------- + +MutationRuntime::MutationRuntime(MutationDecl const& decl, RtScope& scope, ModelAlias* alias) + : _decl{&decl}, + _scope{&scope}, + _alias{alias}, + _typeId{alias->decl->type}, + _core{&scope.core}, + _inFlight{scope.core.runtime(), 0}, + _result{scope.core.runtime()}, + _error{scope.core.runtime()}, + _errorKind{scope.core.runtime()}, + _refusal{scope.core.runtime()} {} + +MutationRuntime::~MutationRuntime() { + *_alive = false; + // A run whose reply will now never be read is no longer pending. + if (int const running = _inFlight.peek(); running > 0) { + _core->addPending(-running); + } +} + +// NOLINTBEGIN(misc-no-recursion): a mutation's commands can run another mutation, and a serial queue sends its next +// run as the last one settles. +void MutationRuntime::run(Value body, std::shared_ptr bindings, RunDone done) { + auto run = std::make_shared(); + run->body = std::move(body); + run->bindings = std::move(bindings); + run->done = std::move(done); + if (_decl->concurrency == Concurrency::Exclusive && _inFlight.peek() > 0) { + run->done(false, Value{}); + return; + } + _inFlight.set(_inFlight.peek() + 1); + _core->addPending(1); + if (_decl->concurrency == Concurrency::Serial) { + // The key reads the run's body, so a run keys the same whichever command started it. + Bindings withBody = *run->bindings; + withBody.push_back(Binding{.name = "body", .read = [body = run->body] { return body; }}); + Value const key = evalIn(*_scope, &withBody, _decl->serialKey); + run->serialKey = key.isNull() ? std::string{} : canonicalJson(key); + if (_busy.contains(run->serialKey)) { + _queues[run->serialKey].push_back(run); + return; + } + _busy.insert(run->serialKey); + } + send(run); +} + +void MutationRuntime::send(std::shared_ptr const& run) { + run->id = ++_runs; + _latest = run->id; + applyOptimistic(*run); + std::shared_ptr const channel = channelOf(*_alias, _scope->core); + if (channel == nullptr) { + settle(run, std::nullopt, std::make_exception_ptr(std::runtime_error{"the model alias has no instance"})); + return; + } + std::weak_ptr const alive = _alive; + try { + auto completion = channel->execute(_decl->action, canonicalJson(run->body), + CallOptions{.queueOffline = _decl->offlineQueue}); + completion + .then([this, alive, run](std::string const& reply) { + if (alive.expired()) { + return; + } + auto json = parseJson(reply); + auto value = json ? valueFromJson(*json) : std::unexpected(json.error()); + if (!value) { + settle(run, std::nullopt, + std::make_exception_ptr( + std::runtime_error{"the reply is not a document value: " + value.error()})); + return; + } + settle(run, std::move(*value), nullptr); + }) + .onError([this, alive, run](std::exception_ptr const& error) { + if (!alive.expired()) { + settle(run, std::nullopt, error); + } + }); + } catch (...) { + settle(run, std::nullopt, std::current_exception()); + } +} + +void MutationRuntime::applyOptimistic(Run& run) { + if (!_decl->optimistic) { + return; + } + NameRef const* const target = _scope->find(_decl->optimistic->query); + if (target == nullptr || target->category != NameCategory::Query) { + return; + } + auto entry = _scope->core.runtime().untracked([&] { return target->query->entry(); }); + if (!entry) { + return; + } + Bindings bindings = *run.bindings; + bindings.push_back(Binding{.name = "body", .read = [body = run.body] { return body; }}); + Value key = _scope->core.runtime().untracked([&] { return evalIn(*_scope, &bindings, _decl->optimistic->key); }); + Value with = _scope->core.runtime().untracked([&] { return evalIn(*_scope, &bindings, _decl->optimistic->with); }); + // Before a value has arrived there is no list to miss. + if (entry->hasValue.peek() && + patchRows(entry->confirmed, _decl->optimistic->at, key, with).error_or(PatchMiss::NoRow) == + PatchMiss::NoList) { + _scope->core.report(pointerAppend(_decl->path, "optimistic"), + patchMissReason(_decl->optimistic->query, _decl->optimistic->at)); + } + entry->layers.push_back( + OptimisticLayer{.run = run.id, .at = _decl->optimistic->at, .key = std::move(key), .with = std::move(with)}); + _scope->core.session.showLayers(*entry); + run.layered.push_back(std::move(entry)); +} + +void MutationRuntime::dropLayers(Run& run) { + for (auto const& entry : run.layered) { + std::erase_if(entry->layers, [&](OptimisticLayer const& layer) { return layer.run == run.id; }); + _scope->core.session.showLayers(*entry); + } + run.layered.clear(); +} + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one branch per outcome a reply can have. +void MutationRuntime::settle(std::shared_ptr const& run, std::optional reply, + std::exception_ptr const& error) { + ScreenCore& core = _scope->core; + Session& session = core.session; + bool const applied = _decl->concurrency != Concurrency::Latest || run->id == _latest; + std::shared_ptr const scope = _scope->shared_from_this(); + auto commandCtx = [&](Bindings extra) { + return CommandCtx{.scope = scope, + .bindings = std::make_shared(std::move(extra)), + .cancelClose = std::make_shared(false), + .boundary = nullptr}; + }; + Value delivered; + bool succeeded = false; + // NOLINTNEXTLINE(readability-function-cognitive-complexity): one branch per outcome a reply can have. + core.runtime().batch([&] { + _inFlight.set(_inFlight.peek() - 1); + _core->addPending(-1); + if (reply) { + succeeded = true; + // The run's optimistic writes are confirmed by the reply: they become part of the confirmed rows. + for (auto const& entry : run->layered) { + Value confirmed = entry->confirmed; + for (OptimisticLayer const& layer : entry->layers) { + if (layer.run == run->id) { + if (auto patched = patchRows(confirmed, layer.at, layer.key, layer.with)) { + confirmed = std::move(*patched); + } + } + } + std::erase_if(entry->layers, [&](OptimisticLayer const& layer) { return layer.run == run->id; }); + session.confirm(*entry, confirmed); + } + run->layered.clear(); + std::vector secret; + if (session.options().catalog.action) { + if (auto const info = session.options().catalog.action(_decl->action)) { + secret = info->secretFields; + } + } + delivered = withoutFields(*reply, secret); + std::string const token = + _alias == nullptr ? std::string{} : core.runtime().untracked([&] { return _alias->token->get(); }); + if (!applied) { + session.actionSucceeded(_typeId, _decl->action, *reply, ReplyUse::Discarded, token); + return; + } + _result.set(*reply); + _error.set(Value{}); + _errorKind.set(Value{}); + _refusal.set(Value{}); + session.actionSucceeded(_typeId, _decl->action, *reply, ReplyUse::Applied, token); + core.runList(_decl->onSuccess, commandCtx(*run->bindings), {}); + if (!secret.empty()) { + _result.set(delivered); + } + return; + } + dropLayers(*run); + std::string const kind = session.classify(error); + if (applied) { + _error.set(Value{failureText(error)}); + _errorKind.set(Value{kind}); + _refusal.set(detail::refusalValue(error)); + core.runList(_decl->onError, commandCtx(*run->bindings), {}); + } + if (kind == "denied" && core.host != nullptr) { + core.host->permissionsStale(); + } + }); + if (_decl->concurrency == Concurrency::Serial) { + next(run->serialKey); + } + run->done(succeeded, delivered); +} + +void MutationRuntime::next(std::string const& serialKey) { + auto const found = _queues.find(serialKey); + if (found == _queues.end() || found->second.empty()) { + _queues.erase(serialKey); + _busy.erase(serialKey); + return; + } + std::shared_ptr const queued = found->second.front(); + found->second.pop_front(); + _scope->core.runtime().batch([&] { send(queued); }); +} +// NOLINTEND(misc-no-recursion) + +} // namespace detail + +namespace detail { +namespace { + +// --- Declaring scopes ------------------------------------------------------------------------------------------ + +/// @brief The element a node of a scope keeps its state in. +/// @param scope The scope that declares it. +/// @param node The node. +/// @return The element, or `nullptr` for a node that keeps none. +[[nodiscard]] ElementState* elementFor(RtScope const& scope, DocNode const& node) { + // A scope that declares nothing (a locale scope and the scope of its mounted content) leaves its children's + // elements to the enclosing scope, where `collect` registered them, so the lookup continues there. + for (RtScope const* at = &scope; at != nullptr; at = at->transparent ? at->parent.get() : nullptr) { + for (auto const& element : at->elements) { + if (element->node == &node) { + return element.get(); + } + } + } + return nullptr; +} + +/// @brief The transfers of the `upload` commands in a list, nested lists included. +/// @param commands The list. +/// @param out Where the transfer ids go. +// NOLINTNEXTLINE(misc-no-recursion): one level per nested command list +void transfersOf(Commands const& commands, std::vector& out) { + for (Command const& command : commands) { + if (command.kind == CommandKind::Upload && !command.transfer.empty()) { + out.push_back(command.transfer); + } + transfersOf(command.commands, out); + transfersOf(command.alternative, out); + } +} +} // namespace + +// NOLINTBEGIN(misc-no-recursion): a document is a tree of nodes and parts, and collecting descends it. +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of node and part. +void ScreenCore::collect(DocNode const& node, RtScope& scope, std::vector& commands) { + KindSpec const* const spec = findKind(node.kind, false); + if (!node.id.empty() || statefulKind(node.kind)) { + auto element = std::make_unique(runtime()); + element->node = &node; + element->scope = &scope; + if (!node.id.empty()) { + NameRef name; + name.category = NameCategory::Element; + name.element = element.get(); + scope.names.insert_or_assign(node.id, name); + } + wireErrors(*element); + scope.elements.push_back(std::move(element)); + } + bool const createsScope = spec != nullptr && (spec->flags & kScope) != 0; + for (auto const& [key, list] : node.events) { + KeySpec const* const keyed = spec == nullptr ? nullptr : keySpec(*spec, key); + if (!createsScope || keyed == nullptr || (keyed->flags & kInner) == 0) { + commands.push_back(&list); + } + } + for (auto const& [chord, list] : node.keys) { + static_cast(chord); + commands.push_back(&list); + } + for (auto const& [key, nodes] : node.children) { + KeySpec const* const keyed = spec == nullptr ? nullptr : keySpec(*spec, key); + if (createsScope && keyed != nullptr && (keyed->flags & kInner) != 0) { + continue; + } + for (DocNodePtr const& child : nodes) { + collect(*child, scope, commands); + } + } + for (auto const& [key, parts] : node.parts) { + static_cast(key); + for (DocNodePtr const& part : parts) { + KindSpec const* const partSpec = findKind(part->kind, true); + if (partSpec != nullptr && (partSpec->flags & kScope) != 0) { + continue; + } + for (auto const& [event, list] : part->events) { + static_cast(event); + commands.push_back(&list); + } + for (auto const& [childKey, nodes] : part->children) { + KeySpec const* const keyed = partSpec == nullptr ? nullptr : keySpec(*partSpec, childKey); + if (keyed != nullptr && (keyed->flags & kInner) != 0) { + continue; + } + for (DocNodePtr const& child : nodes) { + collect(*child, scope, commands); + } + } + } + } +} +// NOLINTEND(misc-no-recursion) + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one section per kind of declaration. +void ScreenCore::declare(RtScope& scope, ScopeDecl const* decl, std::vector const& content, + std::vector const& commands) { + std::vector lists = commands; + for (DocNode const* const node : content) { + collect(*node, scope, lists); + } + std::vector transferIds; + for (Commands const* const list : lists) { + transfersOf(*list, transferIds); + } + for (std::string const& transferId : transferIds) { + if (scope.names.contains(transferId)) { + continue; + } + scope.transfers.push_back(std::make_unique(runtime())); + NameRef name; + name.category = NameCategory::Transfer; + name.transfer = scope.transfers.back().get(); + scope.names.insert_or_assign(transferId, name); + } + if (decl != nullptr) { + for (ModelDecl const& model : decl->models) { + auto alias = std::make_unique(); + alias->decl = &model; + alias->mode = model.instance; + if (alias->mode == InstanceMode::Default) { + std::optional const info = + session.options().catalog.model ? session.options().catalog.model(model.type) : std::nullopt; + alias->mode = info && info->stateless ? InstanceMode::Shared : InstanceMode::Private; + } + ModelAlias* const raw = alias.get(); + switch (raw->mode) { + case InstanceMode::Keyed: + raw->token = &scope.nodes.computed([&scope, raw]() -> std::string { + std::string const key = instanceKeyText(evalIn(scope, nullptr, raw->decl->key)); + return key.empty() ? std::string{} : "shared:" + key; + }); + break; + case InstanceMode::Shared: + raw->token = &scope.nodes.computed([] { return std::string{"shared"}; }); + break; + case InstanceMode::Borrowed: { + auto const found = borrowed.find(model.name); + std::string token = found == borrowed.end() ? std::string{} : found->second.token; + raw->token = &scope.nodes.computed([token = std::move(token)] { return token; }); + break; + } + case InstanceMode::Private: + case InstanceMode::Default: + default: { + std::string token = session.privateToken(); + raw->token = &scope.nodes.computed([token = std::move(token)] { return token; }); + break; + } + } + NameRef name; + name.category = NameCategory::Model; + name.model = raw; + scope.names.insert_or_assign(model.name, name); + scope.models.push_back(std::move(alias)); + } + for (LetDecl const& let : decl->lets) { + NameRef name; + name.category = NameCategory::Let; + name.letExpr = let.value; + name.let = &scope.nodes.computed([&scope, expr = let.value] { return evalIn(scope, nullptr, expr); }); + scope.names.insert_or_assign(let.name, name); + } + for (StateDecl const& state : decl->state) { + auto slot = std::make_unique(); + slot->decl = &state; + slot->scope = &scope; + NameRef name; + name.category = NameCategory::State; + name.state = slot.get(); + scope.names.insert_or_assign(state.name, name); + scope.states.push_back(std::move(slot)); + } + auto aliasOf = [&scope](std::string const& model) -> ModelAlias* { + NameRef const* const found = scope.find(model); + return found != nullptr && found->category == NameCategory::Model ? found->model : nullptr; + }; + for (QueryDecl const& query : decl->queries) { + scope.queries.push_back(std::make_unique(query, scope, aliasOf(query.model))); + NameRef name; + name.category = NameCategory::Query; + name.query = scope.queries.back().get(); + scope.names.insert_or_assign(query.name, name); + } + for (MutationDecl const& mutation : decl->mutations) { + scope.mutations.push_back(std::make_unique(mutation, scope, aliasOf(mutation.model))); + NameRef name; + name.category = NameCategory::Mutation; + name.mutation = scope.mutations.back().get(); + scope.names.insert_or_assign(mutation.name, name); + } + } + for (auto const& slot : scope.states) { + initState(scope, *slot); + } + for (auto const& element : scope.elements) { + wireElement(*element); + } + if (decl == nullptr) { + return; + } + for (CheckDecl const& check : decl->checks) { + auto made = std::make_unique(); + made->decl = ✓ + made->failing = &scope.nodes.computed([&scope, expr = check.assertion] { + Value const asserted = evalIn(scope, nullptr, expr); + bool const* const flag = asserted.asBool(); + return flag != nullptr && !*flag; + }); + made->message = &scope.nodes.computed( + [&scope, expr = check.message] { return textOf(evalIn(scope, nullptr, expr), scope.formatting()); }); + for (std::string const& target : check.targets) { + NameRef const* const found = scope.find(target); + if (found != nullptr && found->category == NameCategory::Element) { + found->element->checks.push_back(made.get()); + made->targets.push_back(found->element); + found->element->checksVersion.set(found->element->checksVersion.peek() + 1); + } + } + scope.checks.push_back(std::move(made)); + } + for (auto const& query : scope.queries) { + query->start(); + } + for (WatchDecl const& watch : decl->watches) { + auto& source = scope.nodes.computed([&scope, expr = watch.on] { return evalIn(scope, nullptr, expr); }); + scope.nodes.effect([this, &scope, &source, watched = &watch, first = true]() mutable { + static_cast(source.get()); + if (first) { + first = false; + return; + } + bool const user = session.lastWriteByUser(); + if (watched->source == WatchSource::User && !user) { + return; + } + runtime().untracked([&] { + CommandCtx const ctx{.scope = scope.shared_from_this(), + .bindings = std::make_shared(), + .cancelClose = std::make_shared(false), + .boundary = nullptr}; + if (user) { + session.asUser([&] { runList(watched->body, ctx, {}); }); + } else { + runList(watched->body, ctx, {}); + } + }); + }); + } +} +namespace { + +/// @brief What a date input reads from a value: the instant it shows, and whether the value names one at all. +struct DateReading { + /// @brief The instant shown; empty for an empty field. + std::optional instant; + /// @brief Whether the value names a date, an instant or nothing; `false` for text that names no date. + bool readable = true; +}; + +/// @brief Reads what a date input shows for @p value, in a display zone @p offsetMinutes from UTC. +/// +/// The value is read as the date functions read it (`readDateValue`): a timestamp is its instant; a `yyyy-MM-dd` +/// string is midnight of that date in the display zone; a string `DateTime::fromIso8601` reads is its instant; `null` +/// and `""` are empty. Any other value is empty and unreadable. +/// @param value The value. +/// @param offsetMinutes The display zone's offset from UTC, in minutes. +/// @return The instant, or nothing, and whether the value was readable. +[[nodiscard]] DateReading dateInstantOf(Value const& value, std::int32_t offsetMinutes) { + DateValue const reading = readDateValue(value); + switch (reading.form) { + case DateForm::Absent: + return {}; + case DateForm::Date: + return {.instant = + time::DateTime{std::chrono::sys_days{reading.date} - std::chrono::minutes{offsetMinutes}}}; + case DateForm::Timestamp: + case DateForm::InstantText: + return {.instant = reading.instant}; + case DateForm::Unreadable: + default: + return {.instant = std::nullopt, .readable = false}; + } +} + +/// @brief A date input's date text for @p instant in a display zone @p offsetMinutes from UTC. +/// @param instant The instant. +/// @param offsetMinutes The display zone's offset from UTC, in minutes. +/// @return `yyyy-MM-dd`. +[[nodiscard]] std::string dateTextOf(time::DateTime const& instant, std::int32_t offsetMinutes) { + auto const local = instant.value + std::chrono::minutes{offsetMinutes}; + std::chrono::year_month_day const date{std::chrono::floor(local)}; + return std::format("{:04}-{:02}-{:02}", static_cast(date.year()), static_cast(date.month()), + static_cast(date.day())); +} + +/// @brief A value as the places a number is entered with. +/// @param value The value. +/// @param format The formatting facts. +/// @return The places, 0 to the most a decimal holds; -1 for a value that is not a non-negative integer. +[[nodiscard]] int placesOf(Value const& value, FormatContext const& format) { + static_cast(format); // Only to fit `bindProp`'s converter signature. + std::int64_t const* const whole = value.asInt(); + if (whole == nullptr || *whole < 0) { + return -1; + } + return static_cast(std::min(*whole, math::kMaxDecimalPlaces)); +} + +/// @brief The fraction digits of a number as typed in the active locale. +/// @param text The typed text. +/// @param format The formatting facts. +/// @return The digits after the decimal separator; 0 for a text that is not a number, which no places rule judges. +[[nodiscard]] std::size_t fractionDigits(std::string_view text, FormatContext const& format) { + std::optional const canonical = render::normalizeLocaleNumber(text, withoutGrouping(format.numeric)); + if (!canonical.has_value()) { + return 0; + } + auto const dot = canonical->find('.'); + return dot == std::string::npos ? 0 : canonical->size() - dot - 1; +} + +/// @brief Whether two values show the same in an input: by text for a text input, by instant for a date input, by +/// value otherwise. +/// @param kind The input's kind. +/// @param lhs One value. +/// @param rhs The other. +/// @param format The formatting facts. +/// @return It. +[[nodiscard]] bool sameShown(std::string_view kind, Value const& lhs, Value const& rhs, FormatContext const& format) { + if (kind == "textInput" || kind == "filePicker") { + return textOf(lhs, format) == textOf(rhs, format); + } + if (kind == "dateTimeInput") { + return dateInstantOf(lhs, format.utcOffsetMinutes).instant == + dateInstantOf(rhs, format.utcOffsetMinutes).instant; + } + return lhs == rhs; +} + +/// @brief The key of a select option: a record's `key`, `id` or `value` field, or the option itself. +/// @param option The option. +/// @return The key. +[[nodiscard]] Value optionKey(Value const& option) { + if (option.asRecord() == nullptr) { + return option; + } + for (std::string_view const field : {"key", "id", "value"}) { + if (Value const* const found = option.field(field)) { + return *found; + } + } + return Value{}; +} +} // namespace + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one rule per source of an error. +void ScreenCore::wireErrors(ElementState& element) { + RtScope& scope = *element.scope; + element.errors = &scope.nodes.computed([this, &element]() -> Value { + static_cast(element.checksVersion.get()); + DocNode const& field = *element.node; + RtScope const& owner = *element.scope; + std::vector errors; + // A group's `required` is its legend's mark only: a group has no value, so no `Required` is derived from it. + if (ExprPtr const required = field.kind != "group" ? field.prop("required") : nullptr) { + Value const requiredNow = evalIn(owner, nullptr, required); + bool const* const flag = requiredNow.asBool(); + if (flag != nullptr && *flag && !engaged(inputValue(element))) { + errors.emplace_back("Required"); + } + } + for (std::string& text : stringsOf(evalIn(owner, nullptr, field.prop("errors")))) { + errors.push_back(std::move(text)); + } + if (ExprPtr const places = field.kind == "textInput" ? field.prop("decimals") : nullptr) { + int const allowed = placesOf(evalIn(owner, nullptr, places), session.formatting()); + if (allowed >= 0 && fractionDigits(textOf(inputValue(element), session.formatting()), + session.formatting()) > static_cast(allowed)) { + // The key and fallback of a form field's `too-precise`, so both read alike in any language. + errors.emplace_back(render::resolveText(session.formatting().translations, session.formatting().locale, + std::nullopt, "morph.forms.error.too-precise", + "Too many decimal places")); + } + } + if (!field.id.empty()) { + std::vector const path{"errors", field.id}; + for (auto const& query : owner.queries) { + for (std::string& text : stringsOf(walk(query->value(), path))) { + errors.push_back(std::move(text)); + } + } + for (auto const& mutation : owner.mutations) { + for (std::string& text : stringsOf(walk(mutation->result(), path))) { + errors.push_back(std::move(text)); + } + } + } + for (CheckRuntime const* const check : element.checks) { + if (check->failing->get()) { + errors.push_back(check->message->get()); + } + } + return listOfStrings(errors); + }); +} + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of element. +void ScreenCore::wireElement(ElementState& element) { + DocNode const& node = *element.node; + RtScope& scope = *element.scope; + std::string_view const kind = node.kind; + if (kind == "form") { + wireForm(element); + return; + } + if (kind == "collection" || kind == "wizard") { + wireComposite(element); + return; + } + bool const input = kind == "textInput" || kind == "checkbox" || kind == "select" || kind == "dateTimeInput" || + kind == "slider" || kind == "filePicker"; + if (input) { + std::string_view key = "value"; + if (kind == "checkbox") { + key = "checked"; + } else if (kind == "select") { + key = "selected"; + } + ExprPtr const expr = kind == "filePicker" ? nullptr : node.prop(key); + bool const controlled = expr && (expr->kind != ExprKind::Literal || !expr->literal.isNull()); + if (controlled) { + element.bound = &scope.nodes.computed([&scope, expr] { return evalIn(scope, nullptr, expr); }); + element.draft.set(runtime().untracked([&] { return element.bound->get(); })); + scope.nodes.effect([this, &element, kind] { + Value const bound = element.bound->get(); + runtime().untracked([&] { + if (!element.edited.peek()) { + element.draft.set(bound); + } else if (sameShown(kind, element.draft.peek(), bound, session.formatting())) { + element.edited.set(false); + } + }); + }); + } else if (kind == "checkbox") { + element.draft.set(false); + } + } + if (kind == "select") { + element.rows = + &scope.nodes.computed([&scope, expr = node.prop("options")] { return evalIn(scope, nullptr, expr); }); + if (element.bound == nullptr && node.name("onStale") == "clear") { + scope.nodes.effect([this, &element] { + Value const options = element.rows->get(); + runtime().untracked([&] { + Value const selected = element.draft.peek(); + if (selected.isNull()) { + return; + } + ValueList const* const items = options.asList(); + bool const kept = items != nullptr && std::ranges::any_of(*items, [&](Value const& option) { + return optionKey(option) == selected; + }); + if (!kept) { + session.noteWrite(); + element.draft.set(Value{}); + } + }); + }); + } + } + if (kind == "table" && node.prop("rows")) { + element.rows = + &scope.nodes.computed([&scope, expr = node.prop("rows")] { return evalIn(scope, nullptr, expr); }); + // A bound selection is controlled, as a select's `selected` is: any expression but a literal `null` binds it. + ExprPtr const selection = node.prop("selection"); + if (selection && (selection->kind != ExprKind::Literal || !selection->literal.isNull())) { + element.bound = &scope.nodes.computed([&scope, selection] { return evalIn(scope, nullptr, selection); }); + } + // A bound sort is controlled as the selection is. + ExprPtr const sort = node.prop("sort"); + if (sort && (sort->kind != ExprKind::Literal || !sort->literal.isNull())) { + element.sortBound = &scope.nodes.computed([&scope, sort] { return evalIn(scope, nullptr, sort); }); + } + element.view = &scope.nodes.computed([this, &element] { return tableView(element, nullptr); }); + } +} +namespace { + +/// @brief A table's sort as its element value reads it: the bound `sort` when the key binds one, else the table's +/// own. +/// @param element The table's element. +/// @return The sort. Tracked. +[[nodiscard]] Value tableSort(ElementState const& element) { + return element.sortBound != nullptr ? element.sortBound->get() : element.sort.get(); +} + +/// @brief A table's page values: `viewCount` (the rows it orders, every page), `page`, `pageCount`, and +/// `pageFirst` and `pageLast`, the 1-based positions of the page's first and last rows, both 0 when there are +/// none. A table that does not page reads page 0 of 1, over every row. +/// @param element The table's element. +/// @param name The value's name. +/// @return The value. Tracked. +[[nodiscard]] Value tablePageValue(ElementState const& element, std::string_view name) { + if (element.view == nullptr) { + return name == "pageCount" ? std::int64_t{1} : std::int64_t{0}; + } + TableView const& view = element.view->get(); + if (name == "viewCount") { + return static_cast(view.rows.size()); + } + if (name == "page") { + return view.page; + } + if (name == "pageCount") { + return view.pageCount; + } + bool const none = view.first == view.last; + if (name == "pageFirst") { + return none ? std::int64_t{0} : static_cast(view.first + 1); + } + return static_cast(view.last); +} + +/// @brief The selected keys of the rows a table holds on pages other than the one shown, in their order: what an +/// `Extend` report keeps, since the backend holds the shown page alone. +/// @param view The table's rows and page. +/// @param selection The selection, a list of keys. +/// @param rowKey A row's key. +/// @return The keys. +[[nodiscard]] ValueList selectedOffPage(TableView const& view, Value const& selection, + std::function const& rowKey) { + std::unordered_set onPage; + std::unordered_set offPage; + for (std::size_t index = 0; index < view.rows.size(); ++index) { + (index >= view.first && index < view.last ? onPage : offPage).insert(rowKey(view.rows.at(index))); + } + ValueList kept; + if (ValueList const* const selected = selection.asList()) { + for (Value const& item : *selected) { + Key const key = keyOf(item); + if (offPage.contains(key) && !onPage.contains(key)) { + kept.push_back(item); + } + } + } + return kept; +} + +/// @brief The sortable column part of a table with the id @p columnId. +/// @param table The table. +/// @param columnId The column's id. +/// @return The part, or `nullptr` when no sortable column has that id. +[[nodiscard]] DocNode const* sortableColumn(DocNode const& table, std::string_view columnId) { + for (DocNodePtr const& column : table.partList("columns")) { + if (column->id == columnId && column->flag("sortable")) { + return column.get(); + } + } + return nullptr; +} + +/// @brief One key of a table's sort: the column part that orders the rows, and whether it is descending. +struct SortKey { + /// @brief The sortable column. + DocNode const* column = nullptr; + /// @brief Whether the key sorts descending. + bool descending = false; +}; + +/// @brief A table's sort read as its keys: a list of `{"column", "direction"}` records naming sortable columns. +/// @param table The table. +/// @param sort The sort; `null` is the source order, as `[]` is. +/// @return The keys, most significant first; `nullopt` when @p sort is not such a list. +[[nodiscard]] std::optional> sortKeysOf(DocNode const& table, Value const& sort) { + std::vector keys; + if (sort.isNull()) { + return keys; + } + ValueList const* const items = sort.asList(); + if (items == nullptr) { + return std::nullopt; + } + for (Value const& item : *items) { + Value const* const column = item.field("column"); + Value const* const direction = item.field("direction"); + std::string const* const columnId = column == nullptr ? nullptr : column->asString(); + std::string const* const way = direction == nullptr ? nullptr : direction->asString(); + DocNode const* const part = columnId == nullptr ? nullptr : sortableColumn(table, *columnId); + if (part == nullptr || way == nullptr || (*way != "asc" && *way != "desc")) { + return std::nullopt; + } + keys.push_back(SortKey{.column = part, .descending = *way == "desc"}); + } + return keys; +} +} // namespace + +void ScreenCore::groupRows(ElementState const& element, Bindings const* bindings, TableView& view) { + auto const parts = element.node->partList("group"); + if (parts.empty()) { + return; + } + ExprPtr const groupBy = parts.front()->prop("by"); + RtScope const& scope = *element.scope; + ScopeEnv const tableEnv{scope, bindings}; + Evaluator runs{tableEnv}; + // A heading's key is its run's key and its ordinal among the runs with an equal key, since adjacent grouping + // can give two runs one key (samples A, B, A); the ordinal stays put across a sort, which moves no run. + std::map> ordinals; + Value key; + ValueList run; + auto const close = [&] { + std::string const json = canonicalJson(key); + Value const record = runRecord(key, std::exchange(run, {})); + ValueRecord entry = *record.asRecord(); + entry.insert_or_assign(std::string{kGroupHeadingField}, + Value{"\x1Fgroup:" + json + ":" + std::to_string(ordinals[json]++)}); + view.runs.emplace_back(std::move(entry)); + }; + for (Value const& row : view.rows) { + Value value = evaluate(*groupBy, ScopeEnv{scope, bindings, &row}); + if (!run.empty() && !runs.sameRun(key, value)) { + close(); + } + if (run.empty()) { + key = std::move(value); + } + run.push_back(row); + view.runOf.push_back(view.runs.size()); + } + if (!run.empty()) { + close(); + } +} + +void ScreenCore::sortedRows(ElementState const& element, Bindings const* bindings, TableView& view) { + DocNode const& node = *element.node; + RtScope const& scope = *element.scope; + Value const source = bindings == nullptr ? element.rows->get() : evalIn(scope, bindings, node.prop("rows")); + ValueList const* const items = source.asList(); + if (items == nullptr) { + return; + } + view.rows.assign(items->begin(), items->end()); + groupRows(element, bindings, view); + Value const sort = tableSort(element); + std::optional> const keys = sortKeysOf(node, sort); + std::string const sortPath = pointerAppend(node.path, "sort"); + if (!keys) { + report( + sortPath, + "sort is " + canonicalJson(sort) + + R"(; a table's sort is a list of {"column": , "direction": "asc" or "desc"})"); + return; + } + if (keys->empty()) { + return; + } + // Each row's keys are read once, then the rows are ordered by them: a change to the sort, the rows, or anything + // a `sortBy` reads sorts again. A grouped table orders by the group first, so every group keeps its place in + // the source order and its rows are sorted within it. + bool const grouped = !view.runOf.empty(); + std::vector> rowKeys; + rowKeys.reserve(view.rows.size()); + for (std::size_t index = 0; index < view.rows.size(); ++index) { + Value const& row = view.rows.at(index); + ScopeEnv const env{scope, bindings, &row}; + std::vector values; + values.reserve(keys->size() + 1); + if (grouped) { + values.emplace_back(static_cast(view.runOf.at(index))); + } + for (SortKey const& key : *keys) { + if (ExprPtr const sortBy = key.column->prop("sortBy")) { + values.push_back(evaluate(*sortBy, env)); + } else { + Value const* const field = row.field(key.column->id); + values.push_back(field == nullptr ? Value{} : *field); + } + } + rowKeys.push_back(std::move(values)); + } + std::vector descending; + descending.reserve(keys->size() + 1); + if (grouped) { + descending.push_back(false); + } + for (SortKey const& key : *keys) { + descending.push_back(key.descending); + } + ScopeEnv const env{scope, bindings}; + std::optional> const order = Evaluator{env}.sortRows(rowKeys, descending); + if (!order) { + report(sortPath, "the rows' values for the sort are not of one comparable kind; the rows keep their order"); + return; + } + std::vector sorted; + std::vector runOf; + sorted.reserve(view.rows.size()); + for (std::size_t const index : *order) { + sorted.push_back(view.rows.at(index)); + if (grouped) { + runOf.push_back(view.runOf.at(index)); + } + } + view.rows = std::move(sorted); + view.runOf = std::move(runOf); +} + +TableView ScreenCore::tableView(ElementState const& element, Bindings const* bindings) { + DocNode const& node = *element.node; + RtScope const& scope = *element.scope; + TableView view; + sortedRows(element, bindings, view); + view.last = view.rows.size(); + ExprPtr const sizeExpr = node.prop("pageSize"); + if (!sizeExpr) { + return view; + } + // A `pageSize` of `null` does not page; one that is no positive integer is reported and does not page either. + Value const size = evalIn(scope, bindings, sizeExpr); + std::int64_t const* const perPage = size.asInt(); + if (size.isNull() || perPage == nullptr || *perPage < 1) { + if (!size.isNull()) { + report(pointerAppend(node.path, "pageSize"), + "pageSize is " + canonicalJson(size) + "; a page holds a positive whole number of rows"); + } + return view; + } + // A `page` of `null` is the first; one that is negative or not a whole number is reported and shows the first. + // One past the last is the last: a filter that shrinks the rows under the user is normal, not an error. + std::int64_t asked = 0; + if (ExprPtr const pageExpr = node.prop("page")) { + Value const page = evalIn(scope, bindings, pageExpr); + std::int64_t const* const index = page.asInt(); + if (index != nullptr && *index >= 0) { + asked = *index; + } else if (!page.isNull()) { + report(pointerAppend(node.path, "page"), + "page is " + canonicalJson(page) + "; a page is a whole number from 0"); + } + } + auto const total = static_cast(view.rows.size()); + view.pageCount = std::max(1, (total + *perPage - 1) / *perPage); + view.page = std::min(asked, view.pageCount - 1); + view.first = static_cast(std::min(total, view.page * *perPage)); + view.last = static_cast(std::min(total, (view.page + 1) * *perPage)); + return view; +} +namespace { + +/// @brief A table's selection as its element value reads it: the bound `selection` when the key binds one, else +/// the table's own. A bound value that is not a list (`null` while state starts empty) selects nothing. +/// @param element The table's element. +/// @return A list of keys. Tracked. +[[nodiscard]] Value tableSelection(ElementState const& element) { + if (element.bound == nullptr) { + return element.selection.get(); + } + Value const bound = element.bound->get(); + return bound.asList() != nullptr ? bound : Value{ValueList{}}; +} +} // namespace + +[[nodiscard]] Value jsonTextValue(std::string_view text) { + auto const json = parseJson(text); + if (!json) { + return Value{}; + } + auto value = valueFromJson(*json); + return value ? *std::move(value) : Value{}; +} +namespace { + +/// @brief One field of a form as a record: `value` (the encoded value, `null` while blank or invalid), `draft` (the +/// text), `valid`, `required`, `visible`, `readonly` and `errors`. Tracked. +/// @param field The field. +/// @return The record. +[[nodiscard]] Value formFieldValue(forms::FieldState const& field) { + ValueRecord record; + forms::Encoding const& encoding = field.encoded().get(); + Value value; + if (encoding.has_value() && encoding->has_value()) { + value = (*encoding)->value.isNull() ? jsonTextValue((*encoding)->json) : (*encoding)->value; + } + std::optional const& error = field.error().get(); + record.insert_or_assign("value", std::move(value)); + record.insert_or_assign("draft", Value{field.spec().kind == forms::FieldKind::Object || + field.spec().kind == forms::FieldKind::ObjectArray + ? std::string{} + : field.draft()}); + record.insert_or_assign("valid", Value{!error.has_value()}); + record.insert_or_assign("required", Value{field.required().get()}); + record.insert_or_assign("visible", Value{field.visible().get()}); + record.insert_or_assign("readonly", Value{field.readonly().get()}); + record.insert_or_assign("errors", + error.has_value() ? Value{ValueList{Value{error->message}}} : Value{ValueList{}}); + return Value{std::move(record)}; +} + +/// @brief A form's element values (spec 5 §6): `ready`, `body` (the record the form would submit, `null` while not +/// ready), `submitted` (whether a submission was sent), `pending`, and each field by its wire name. Tracked. +/// @param element The form's element. +/// @param name The value's name. +/// @return The value; `null` for a name the form does not have, or a form without a session. +[[nodiscard]] Value formValue(ElementState const& element, std::string_view name) { + forms::FormSession const* const form = element.form.get(); + if (form == nullptr) { + return Value{}; + } + if (name == "ready") { + return form->ready(); + } + if (name == "body") { + std::optional const body = form->body(); + return body.has_value() ? jsonTextValue(*body) : Value{}; + } + if (name == "submitted") { + return form->submitAttempts() > 0; + } + if (name == "pending") { + return form->pending(); + } + for (auto const& field : form->fields()) { + if (field->spec().name == name) { + return formFieldValue(*field); + } + } + return Value{}; +} +} // namespace + +Value ScreenCore::inputValue(ElementState const& element) const { + std::string_view const kind = element.node->kind; + if (kind == "checkbox") { + return elementValue(element, "checked"); + } + if (kind == "select") { + return elementValue(element, "selected"); + } + return elementValue(element, "value"); +} + +// NOLINTNEXTLINE(misc-no-recursion,readability-function-cognitive-complexity): one case per element value. +Value ScreenCore::elementValue(ElementState const& element, std::string_view name) const { + DocNode const& node = *element.node; + RtScope const& scope = *element.scope; + std::string_view const kind = node.kind; + auto flagOf = [&](std::string_view key, bool fallback) -> Value { + ExprPtr const expr = node.prop(key); + if (!expr) { + return fallback; + } + Value const value = evalIn(scope, nullptr, expr); + bool const* const flag = value.asBool(); + return flag != nullptr && *flag; + }; + auto errors = [&]() -> Value { return element.errors->get(); }; + auto count = [](Value const& list) -> Value { + ValueList const* const items = list.asList(); + return static_cast(items == nullptr ? 0 : items->size()); + }; + if (name == "visible" || name == "enabled") { + return flagOf(name, true); + } + if (name == "errors") { + return errors(); + } + if (name == "valid") { + Value const current = errors(); + ValueList const* const items = current.asList(); + return items == nullptr || items->empty(); + } + if (name == "shownErrors") { + RtScope const& policy = scope.policyScope(); + std::string const mode = policy.showErrors.empty() ? _doc->showErrors : policy.showErrors; + bool const submittedNow = policy.submitted != nullptr && policy.submitted->get(); + if (mode == "always" || (mode == "submit" && submittedNow) || + (mode != "submit" && (submittedNow || element.touched.get() || touchedWithin(element)))) { + return errors(); + } + return Value{ValueList{}}; + } + if (kind == "dialog" || kind == "drawer") { + if (name == "open") { + return node.prop("open") ? flagOf("open", false) : Value{element.open.get()}; + } + if (name == "ready") { + RtScope const* const inner = element.inner.get(); + return inner != nullptr && inner->ready(); + } + if (name == "submitted") { + return element.submitted.get(); + } + return Value{}; + } + if (kind == "table") { + if (name == "selection") { + return tableSelection(element); + } + if (name == "activeKey") { + return element.activeKey.get(); + } + if (name == "selectedCount") { + return count(tableSelection(element)); + } + if (name == "sort") { + return tableSort(element); + } + if (name == "viewCount" || name == "page" || name == "pageCount" || name == "pageFirst" || + name == "pageLast") { + return tablePageValue(element, name); + } + if (name == "sourceCount") { + return element.rows == nullptr ? Value{std::int64_t{0}} : count(element.rows->get()); + } + ExprPtr const rows = node.prop("rows"); + if ((name == "pending" || name == "error") && rows && rows->kind == ExprKind::Query) { + ScopeEnv const env{scope, nullptr}; + return env.control(name == "pending" ? ExprKind::Pending : ExprKind::Error, rows->name); + } + return name == "pending" ? Value{false} : Value{}; + } + if (kind == "tabs") { + // The shown tab's id: the bound one, else the user's own pick, else the first tab's. + ExprPtr const selected = node.prop("selected"); + if (name != "selected") { + return Value{}; + } + if (selected && (selected->kind != ExprKind::Literal || !selected->literal.isNull())) { + return evalIn(scope, nullptr, selected); + } + if (Value picked = element.draft.get(); !picked.isNull()) { + return picked; + } + auto const tabs = node.partList("tabs"); + return tabs.empty() || tabs.front()->id.empty() ? Value{} : Value{tabs.front()->id}; + } + if (kind == "form") { + return formValue(element, name); + } + if (name == "draft") { + return element.draft.get(); + } + if (name == "dirty") { + return element.edited.get(); + } + if (name == "focused") { + return element.focused.get(); + } + if (name == "touched") { + return element.touched.get(); + } + if (name == "checked" || name == "selected") { + return element.bound != nullptr ? element.bound->get() : element.draft.get(); + } + if (name == "selectedOption") { + Value const selected = elementValue(element, "selected"); + ValueList const* const options = element.rows == nullptr ? nullptr : element.rows->get().asList(); + if (options != nullptr && !selected.isNull()) { + for (Value const& option : *options) { + if (optionKey(option) == selected) { + return option; + } + } + } + return Value{}; + } + if (name == "value") { + if (element.bound != nullptr) { + return element.bound->get(); + } + return element.committed.get(); + } + return Value{}; +} + +bool ScreenCore::touchedWithin(ElementState const& element) { + if (element.node->kind != "group") { + return false; + } + std::string const inside = element.node->path + "/"; + return std::ranges::any_of(element.scope->elements, [&inside](std::unique_ptr const& other) { + return other->node->path.starts_with(inside) && other->touched.get(); + }); +} + +// --- Commands -------------------------------------------------------------------------------------------------- + +// NOLINTBEGIN(misc-no-recursion): command lists nest +void ScreenCore::runList(Commands const& commands, CommandCtx const& ctx, Done done) { + if (!done) { + done = [](bool) {}; + } + if (commands.empty()) { + done(true); + return; + } + struct Join { + std::size_t left = 0; + bool ok = true; + Done done; + }; + if (recording) { + logList(commands); + } + auto join = std::make_shared(Join{.left = commands.size() + 1, .ok = true, .done = std::move(done)}); + auto finish = [join](bool succeeded) { + join->ok = join->ok && succeeded; + if (--join->left == 0) { + join->done(join->ok); + } + }; + for (Command const& command : commands) { + runOne(command, ctx, finish); + } + finish(true); +} + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per command of ui/1. +void ScreenCore::runOne(Command const& command, CommandCtx const& ctx, Done done) { + if (!done) { + done = [](bool) {}; + } + RtScope const& scope = *ctx.scope; + auto eval = [&](ExprPtr const& expr) { return evalIn(scope, ctx.bindings.get(), expr); }; + auto finish = [&done](bool succeeded) { done(succeeded); }; + switch (command.kind) { + case CommandKind::Set: + runSet(command, ctx, done); + return; + case CommandKind::Reset: + runReset(command, ctx, done); + return; + case CommandKind::Run: + runMutation(command, ctx, std::move(done)); + return; + case CommandKind::Refetch: { + // A loaded document's `refetch` names a query in scope (`loadDocument` checks it), as `run` names a + // mutation and `open` a dialog. + scope.find(command.target)->query->refetch(); + finish(true); + return; + } + case CommandKind::Open: + case CommandKind::Close: { + ElementState* target = nullptr; + if (command.kind == CommandKind::Close && command.target == "self") { + // `self` is the innermost dialog or drawer whose content holds the command, found lexically. A + // component's fallback scope has no parent, so the walk stops at its boundary as its names do. + RtScope const* walk = &scope; + while (walk->owner == nullptr && walk->parent) { + walk = walk->parent.get(); + } + target = walk->owner; + if (target == nullptr && walk != rootScope.lock().get()) { + report(command.path, "`close: self` inside a component names no dialog or drawer"); + finish(false); + return; + } + if (target == nullptr) { + finish((host != nullptr && host->closeSelf(_doc->id, std::nullopt)) || + unsupported(command, "`close: self`")); + return; + } + } else { + target = scope.find(command.target)->element; + } + ElementState& element = *target; + if (element.node->prop("open")) { + report(command.path, "the dialog's `open` is bound to an expression"); + finish(false); + return; + } + bool const opening = command.kind == CommandKind::Open; + if (opening && !element.open.peek()) { + element.submitted.set(false); + } + session.noteWrite(); + element.open.set(opening); + finish(true); + return; + } + case CommandKind::Navigate: { + NavigateRequest const request{.screen = command.target, + .route = eval(command.extra), + .params = eval(command.value), + .as = command.option, + .call = false}; + if (host == nullptr) { + finish(unsupported(command, "`navigate`")); + return; + } + // A navigation without `onResult` and `onCancel` asks for no answer, so it files no call: the screen it + // opens answers nobody, and its `return` is the application's. + if (command.commands.empty() && command.alternative.empty()) { + finish(host->navigate(request, {}, {}) || unsupported(command, "`navigate`")); + return; + } + std::weak_ptr const weak = ctx.scope; + CommandCtx const kept = detached(ctx); + auto onResult = [this, weak, kept, list = &command.commands](Value const& result) { + if (auto const held = weak.lock()) { + auto bindings = std::make_shared(*kept.bindings); + bindings->push_back(Binding{.name = "event", .read = [result] { return result; }}); + CommandCtx const next{.scope = held, + .bindings = bindings, + .cancelClose = kept.cancelClose, + .boundary = kept.boundary}; + runtime().batch([&] { runList(*list, next, {}); }); + } + }; + auto onCancel = [this, weak, kept, list = &command.alternative] { + if (auto const held = weak.lock()) { + CommandCtx next = kept; + next.scope = held; + runtime().batch([&] { runList(*list, next, {}); }); + } + }; + finish(host->navigate(request, std::move(onResult), std::move(onCancel)) || + unsupported(command, "`navigate`")); + return; + } + case CommandKind::Return: + finish(host != nullptr && host->closeSelf(_doc->id, eval(command.value)) + ? true + : unsupported(command, "`return`")); + return; + case CommandKind::Focus: + if (focusTarget(command, scope, ctx.bindings.get())) { + finish(true); + return; + } + report(command.path, "`" + command.target + "` is not mounted"); + finish(false); + return; + case CommandKind::Host: + runHostCommand(command, ctx, done); + return; + case CommandKind::SwitchBackend: { + std::weak_ptr const weak = ctx.scope; + auto committed = [this, weak, target = command.target, path = command.path, + done](std::expected const& outcome) { + if (!weak.lock()) { + return; + } + if (!outcome) { + report(path, "backendSwitchFailed: " + outcome.error()); + done(false); + return; + } + session.backendChanged(target); + done(true); + }; + if (host != nullptr && host->switchBackend(command.target, std::move(committed))) { + return; + } + report(command.path, "backend `" + command.target + "` is not listed"); + finish(false); + return; + } + case CommandKind::ResetPrefs: { + ValueRecord prefsNow = prefs.peek(); + if (command.target == "all") { + prefsNow = prefDefaults; + } else if (auto const found = prefDefaults.find(command.target); found != prefDefaults.end()) { + prefsNow.insert_or_assign(command.target, found->second); + } + prefs.set(std::move(prefsNow)); + if (host != nullptr) { + host->resetPrefs(_doc->id, command.target); + } + finish(true); + return; + } + case CommandKind::SetLocale: + session.setLocale(command.target); + if (host != nullptr) { + host->setLocale(command.target); + } + finish(true); + return; + case CommandKind::SetContext: { + // The shell checks the value against the switcher's options; with no switcher it is unsupported. + Value const requested = eval(command.value); + if (session.requestContext(requested)) { + finish(true); + } else { + report(command.path, + "`setContext` was refused: " + std::string{session.can("context") + ? "the value is not one of the scope's options" + : "no scope switcher is declared"}); + finish(false); + } + return; + } + case CommandKind::Notify: { + std::string const text = textOf(eval(command.value), ctx.scope->formatting()); + finish(host != nullptr && host->notify(text, command.option) ? true : unsupported(command, "`notify`")); + return; + } + case CommandKind::Seq: { + // A step that waits for a reply keeps the rest of the sequence in that reply's handler, which the + // dispatcher may hold past the screen: the sequence holds its scope weakly and stops once it is gone. + CommandCtx const inner = detached(CommandCtx{.scope = nullptr, + .bindings = std::make_shared(*ctx.bindings), + .cancelClose = ctx.cancelClose, + .boundary = ctx.boundary}); + std::weak_ptr const weak = ctx.scope; + auto step = std::make_shared>(); + *step = [this, inner, weak, list = &command.commands, done = std::move(done), + weakStep = std::weak_ptr>{step}](std::size_t index) { + auto const held = weak.lock(); + if (index == list->size() || !held) { + done(held != nullptr); + return; + } + auto const self = weakStep.lock(); + CommandCtx current = inner; + current.scope = held; + runOne(list->at(index), current, [self, index, done](bool succeeded) { + if (!succeeded) { + done(false); + return; + } + (*self)(index + 1); + }); + }; + (*step)(0); + return; + } + case CommandKind::All: { + CommandCtx const inner{.scope = ctx.scope, + .bindings = std::make_shared(*ctx.bindings), + .cancelClose = ctx.cancelClose, + .boundary = ctx.boundary}; + runList(command.commands, inner, std::move(done)); + return; + } + case CommandKind::If: { + Value const condition = eval(command.value); + bool const* const flag = condition.asBool(); + if (flag == nullptr) { + finish(true); + return; + } + runList(*flag ? command.commands : command.alternative, ctx, std::move(done)); + return; + } + case CommandKind::CancelClose: + *ctx.cancelClose = true; + finish(true); + return; + case CommandKind::Retry: + // `retry` is valid only inside a boundary's `error`, which is lowered with its boundary. + for (QueryRuntime* const query : ctx.boundary->queries) { + if (!runtime().untracked([&] { return query->error(); }).isNull()) { + query->refetch(); + } + } + finish(true); + return; + case CommandKind::SignIn: { + NameRef const* const found = scope.find(command.target); + Value const reply = found != nullptr && found->category == NameCategory::Mutation + ? runtime().untracked([&] { return found->mutation->result(); }) + : Value{}; + session.clear(); + finish(host != nullptr && host->signIn(reply) ? true : unsupported(command, "`signIn`")); + return; + } + case CommandKind::SignOut: + session.clear(); + if (host != nullptr) { + host->signOut(); + } + finish(true); + return; + case CommandKind::Upload: + case CommandKind::Download: + default: + runTransfer(command, ctx, std::move(done)); + return; + } +} + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): a single run, or a run per list item. +void ScreenCore::runMutation(Command const& command, CommandCtx const& ctx, Done done) const { + RtScope const& scope = *ctx.scope; + MutationRuntime& mutation = *scope.find(command.target)->mutation; + RtScope const& policy = scope.policyScope(); + if (policy.submitted != nullptr) { + policy.submitted->set(true); + } + if (policy.owner != nullptr && !runtime().untracked([&] { return policy.ready(); })) { + done(false); + return; + } + RtScope const& declaring = *[&]() -> RtScope const* { + for (RtScope const* candidate = &scope; candidate != nullptr; candidate = candidate->parent.get()) { + if (candidate->names.contains(command.target)) { + return candidate; + } + } + return &scope; + }(); + auto bodyFor = [&](Bindings const& bindings) { + if (command.value) { + return evalIn(scope, &bindings, command.value); + } + if (mutation.decl().body) { + return evalIn(declaring, &bindings, mutation.decl().body); + } + return Value{ValueRecord{}}; + }; + if (!command.extra) { + Value body = bodyFor(*ctx.bindings); + mutation.run(std::move(body), std::make_shared(*ctx.bindings), + [bindings = ctx.bindings, bindAs = command.binding, done = std::move(done)](bool succeeded, + Value const& reply) { + if (succeeded && !bindAs.empty()) { + bindings->push_back(Binding{.name = bindAs, .read = [reply] { return reply; }}); + } + done(succeeded); + }); + return; + } + Value const each = evalIn(scope, ctx.bindings.get(), command.extra); + ValueList const items = each.asList() == nullptr ? ValueList{} : *each.asList(); + if (items.empty()) { + done(true); + return; + } + struct Each { + std::size_t left = 0; + bool ok = true; + Done done; + }; + auto state = std::make_shared(Each{.left = items.size(), .ok = true, .done = std::move(done)}); + std::vector bodies; + std::vector> bound; + for (Value const& item : items) { + Bindings bindings = *ctx.bindings; + if (!command.binding.empty()) { + bindings.push_back(Binding{.name = command.binding, .read = [item] { return item; }}); + } + bodies.push_back(bodyFor(bindings)); + bound.push_back(std::make_shared(std::move(bindings))); + } + if (mutation.decl().concurrency != Concurrency::Exclusive) { + for (std::size_t index = 0; index < bodies.size(); ++index) { + mutation.run(bodies.at(index), bound.at(index), [state](bool succeeded, Value const&) { + state->ok = state->ok && succeeded; + if (--state->left == 0) { + state->done(state->ok); + } + }); + } + return; + } + // An exclusive mutation refuses a run while another is in flight, so its elements go one after another. + auto step = std::make_shared>(); + *step = [&mutation, bodies, bound, state, + weakStep = std::weak_ptr>{step}](std::size_t index) { + if (index == bodies.size()) { + state->done(state->ok); + return; + } + auto const self = weakStep.lock(); + mutation.run(bodies.at(index), bound.at(index), [self, state, index](bool succeeded, Value const&) { + if (!succeeded) { + state->done(false); + return; + } + (*self)(index + 1); + }); + }; + (*step)(0); +} + +// NOLINTEND(misc-no-recursion) +void ScreenCore::writeSlot(StateSlot& slot, std::span within, Value value, Command const& command, + Done const& done) { + slot.scope->core.initState(*slot.scope, slot); + Type const& type = slot.decl->type; + if (within.empty() && !type.isAny() && !type.admits(value)) { + report(command.path, "`set` writes a value that is not a " + type.name()); + done(false); + return; + } + Value next = withPath(slot.value->peek(), within, std::move(value)); + session.noteWrite(); + slot.value->set(std::move(next)); + done(true); +} + +void ScreenCore::runSetApp(Command const& command, std::span rest, Value value, Done const& done) { + if (RtScope const* const app = session.appScope(); app != nullptr && !rest.empty()) { + NameRef const* const named = app->find(rest.front()); + if (named != nullptr && named->category == NameCategory::State) { + writeSlot(*named->state, rest.subspan(1), std::move(value), command, done); + return; + } + report(command.path, "`app." + rest.front() + "` is not state of the app document"); + done(false); + return; + } + std::string name; + for (std::string const& segment : rest) { + name += name.empty() ? segment : "." + segment; + } + done(host != nullptr && host->setAppValue(name, value) ? true : unsupported(command, "`set` of `app`")); +} + +void ScreenCore::runSet(Command const& command, CommandCtx const& ctx, Done const& done) { + RtScope const& scope = *ctx.scope; + auto path = splitPath(command.target); + if (!path || path->empty()) { + done(false); + return; + } + std::string const head = path->front(); + std::span const rest = std::span{*path}.subspan(1); + Value value = evalIn(scope, ctx.bindings.get(), command.value); + if (head == "app") { + runSetApp(command, rest, std::move(value), done); + return; + } + NameRef const* const found = scope.find(head); + if (found != nullptr && found->category == NameCategory::State) { + writeSlot(*found->state, rest, std::move(value), command, done); + return; + } + if (found != nullptr && found->category == NameCategory::Element) { + ElementState& element = *found->element; + session.noteWrite(); + element.draft.set(value); + if (element.bound == nullptr) { + element.committed.set(std::move(value)); + } + done(true); + return; + } + report(command.path, "`set` names nothing writable here"); + done(false); +} + +void ScreenCore::runReset(Command const& command, CommandCtx const& ctx, Done const& done) { + RtScope const& scope = *ctx.scope; + NameRef const* const found = scope.find(command.target); + auto resetStates = [this](RtScope const& owner) { + for (auto const& slot : owner.states) { + if (slot->value) { + Value init = runtime().untracked([&] { return evalIn(owner, nullptr, slot->decl->init); }); + slot->value->set(std::move(init)); + } + } + for (auto const& element : owner.elements) { + element->draft.set(element->bound != nullptr ? runtime().untracked([&] { return element->bound->get(); }) + : Value{}); + element->committed.set(Value{}); + element->edited.set(false); + element->touched.set(false); + } + }; + bool known = true; + session.noteWrite(); + if (found != nullptr && found->category == NameCategory::State) { + StateSlot& slot = *found->state; + initState(*slot.scope, slot); + slot.value->set(runtime().untracked([&] { return evalIn(*slot.scope, nullptr, slot.decl->init); })); + } else if (found != nullptr && found->category == NameCategory::Element) { + ElementState& element = *found->element; + element.submitted.set(false); + if (RtScope const* const inner = element.inner.peek()) { + resetStates(*inner); + } + } else { + report(command.path, "`reset` names no state or dialog here"); + known = false; + } + done(known); +} + +void ScreenCore::runHostCommand(Command const& command, CommandCtx const& ctx, Done const& done) { + Value const args = evalIn(*ctx.scope, ctx.bindings.get(), command.value); + if (auto const& run = session.hostCommandRunner()) { + HostCommandResult const result = run(command.target, args); + if (result.kind == HostCommandResult::Kind::Missing) { + report(command.path, "host command `" + command.target + "` is missing"); + } else if (result.kind == HostCommandResult::Kind::Refused) { + report(command.path, result.reason); + } + done(result.kind == HostCommandResult::Kind::Ran); + return; + } + bool const known = host != nullptr && host->hostCommand(command.target, args); + if (!known) { + report(command.path, "host command `" + command.target + "` is missing"); + } + done(known); +} +namespace { + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): a download and an upload, each settled. +/// @brief A transfer's share of its screen's pending count. +/// +/// A transfer is pending from the host accepting it to its settle: its completion carries on the command list that +/// started it, which the close protocol and save-and-close wait for. The count is taken once the host accepts, so a +/// refused transfer never counts, and a host that settles before it returns leaves nothing taken. It is given back +/// once, also when the transfer settles after its scope is gone, but not after the screen itself is gone, since the +/// count went with it. +class TransferHold { +public: + /// @brief A hold that counts nothing yet. + /// @param core The screen whose count it moves. + /// @param alive Expires with the screen. + TransferHold(ScreenCore& core, std::weak_ptr alive) : _core{&core}, _alive{std::move(alive)} {} + + /// @brief Counts the transfer, unless it has already settled. + void take() { + if (_state == State::NotTaken) { + _state = State::Taken; + _core->addPending(1); + } + } + + /// @brief Gives the count back, if one was taken and the screen is still there; the transfer counts no more. + void release() { + if (_state == State::Taken && !_alive.expired()) { + _core->addPending(-1); + } + _state = State::Released; + } + +private: + enum class State : std::uint8_t { NotTaken, Taken, Released }; + + ScreenCore* _core; + std::weak_ptr _alive; + State _state = State::NotTaken; +}; + +/// @brief Bytes as base64 (RFC 4648, with padding): how a document carries an inline file. +/// @param bytes The bytes. +/// @return The text. +[[nodiscard]] std::string base64Encode(std::string_view bytes) { + static constexpr std::string_view kAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"; + std::string out; + out.reserve(((bytes.size() + 2) / 3) * 4); + for (std::size_t index = 0; index < bytes.size(); index += 3) { + std::size_t const left = std::min(3, bytes.size() - index); + std::uint32_t group = 0; + for (std::size_t offset = 0; offset < 3; ++offset) { + group <<= 8U; + if (offset < left) { + group |= static_cast(bytes.at(index + offset)); + } + } + for (std::size_t digit = 0; digit < 4; ++digit) { + out.push_back(digit <= left ? kAlphabet.at((group >> (18U - (6U * digit))) & 0x3FU) : '='); + } + } + return out; +} +} // namespace + +[[nodiscard]] std::optional base64Decode(std::string_view text) { + while (!text.empty() && text.back() == '=') { + text.remove_suffix(1); + } + if (text.size() % 4 == 1) { + return std::nullopt; + } + auto digitOf = [](char chr) -> int { + if (chr >= 'A' && chr <= 'Z') { + return chr - 'A'; + } + if (chr >= 'a' && chr <= 'z') { + return chr - 'a' + 26; + } + if (chr >= '0' && chr <= '9') { + return chr - '0' + 52; + } + if (chr == '+') { + return 62; + } + return chr == '/' ? 63 : -1; + }; + std::string out; + out.reserve((text.size() * 3) / 4); + std::uint32_t group = 0; + int bits = 0; + for (char const chr : text) { + int const digit = digitOf(chr); + if (digit < 0) { + return std::nullopt; + } + group = (group << 6U) | static_cast(digit); + bits += 6; + if (bits >= 8) { + bits -= 8; + out.push_back(static_cast((group >> static_cast(bits)) & 0xFFU)); + } + } + return out; +} + +[[nodiscard]] std::size_t base64Size(std::string_view text) { + while (!text.empty() && text.back() == '=') { + text.remove_suffix(1); + } + return (text.size() * 3) / 4; +} + +[[nodiscard]] std::string sizeText(std::size_t bytes) { + constexpr std::size_t kKiB = 1024; + if (bytes < kKiB) { + return std::to_string(bytes) + " bytes"; + } + bool const mebi = bytes >= kKiB * kKiB; + std::size_t const unit = mebi ? kKiB * kKiB : kKiB; + // One decimal place, rounded half up, and none when it is zero. + std::size_t const tenths = ((bytes * 10) + (unit / 2)) / unit; + std::string text = std::to_string(tenths / 10); + if (tenths % 10 != 0) { + text += "." + std::to_string(tenths % 10); + } + return text + (mebi ? " MiB" : " KiB"); +} + +[[nodiscard]] std::expected inlineBytes(Value const& value) { + if (std::string const* const text = value.asString()) { + if (std::optional bytes = base64Decode(*text)) { + return *std::move(bytes); + } + return std::unexpected(std::string{"the text is not base64"}); + } + if (ValueList const* const list = value.asList()) { + std::string bytes; + bytes.reserve(list->size()); + for (Value const& item : *list) { + std::int64_t const* const byte = item.asInt(); + if (byte == nullptr || *byte < 0 || *byte > 255) { + return std::unexpected(std::string{"a byte list holds integers 0 to 255"}); + } + bytes.push_back(static_cast(static_cast(*byte))); + } + return bytes; + } + return std::unexpected(std::string{"inline bytes are base64 text or a list of bytes"}); +} + +void ScreenCore::runTransfer(Command const& command, CommandCtx const& ctx, Done done) { + Value const file = evalIn(*ctx.scope, ctx.bindings.get(), command.value); + if (command.kind == CommandKind::Download) { + runDownload(command, ctx, file, std::move(done)); + } else { + runUpload(command, ctx, file, std::move(done)); + } +} + +void ScreenCore::runDownload(Command const& command, CommandCtx const& ctx, Value const& file, Done done) { + Value const name = evalIn(*ctx.scope, ctx.bindings.get(), command.extra); + auto const hold = std::make_shared(*this, _alive); + auto const settled = [this, weak = std::weak_ptr{ctx.scope}, target = command.target, + preview = command.option == "preview", done, + hold](std::expected const& reply) { + auto const held = weak.lock(); + if (!held) { + hold->release(); + return; + } + runtime().batch([&] { + bool const succeeded = reply.has_value(); + NameRef const* const found = succeeded && preview ? held->find(target) : nullptr; + if (found != nullptr && found->category == NameCategory::State) { + initState(*found->state->scope, *found->state); + session.noteWrite(); + found->state->value->set(*reply); + } + done(succeeded); + hold->release(); + }); + }; + if (command.bytes) { + std::optional const inlined = inlineDownload(command, ctx, file, name); + if (!inlined) { + done(false); + return; + } + if (host == nullptr || !host->saveFile(*inlined, command.option, settled)) { + unsupported(command, "`download`"); + done(false); + return; + } + hold->take(); + return; + } + if (host == nullptr || !host->download(file, command.option, name, settled)) { + unsupported(command, "`download`"); + done(false); + return; + } + hold->take(); +} + +// Inline bytes are checked before the host is asked: content over the cap, or that does not decode, never reaches it. +std::optional ScreenCore::inlineDownload( + Command const& command, CommandCtx const& ctx, + // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the command's `file` and `name`, in its order. + Value const& file, Value const& name) { + std::size_t const cap = session.options().maxInlineFileBytes; + std::size_t size = 0; + if (std::string const* const text = file.asString()) { + size = base64Size(*text); + } else if (ValueList const* const list = file.asList()) { + size = list->size(); + } + std::expected bytes = size > cap ? std::unexpected(std::string{}) : inlineBytes(file); + if (size > cap || (bytes && bytes->size() > cap)) { + report(command.path, "download: " + sizeText(bytes ? bytes->size() : size) + " is over the " + sizeText(cap) + + " inline cap; serve it through the file store"); + return std::nullopt; + } + if (!bytes) { + report(command.path, "download: " + bytes.error()); + return std::nullopt; + } + return InlineFile{ + .name = textOf(name, ctx.scope->formatting()), + .mediaType = command.mediaType + ? textOf(evalIn(*ctx.scope, ctx.bindings.get(), command.mediaType), ctx.scope->formatting()) + : std::string{}, + .bytes = *std::move(bytes)}; +} + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one branch per outcome an upload can have. +void ScreenCore::runUpload(Command const& command, CommandCtx const& ctx, Value const& file, Done done) { + RtScope const& scope = *ctx.scope; + std::weak_ptr const weak = ctx.scope; + auto const hold = std::make_shared(*this, _alive); + NameRef const* const transferName = command.transfer.empty() ? nullptr : scope.find(command.transfer); + TransferState* const transfer = + transferName != nullptr && transferName->category == NameCategory::Transfer ? transferName->transfer : nullptr; + auto const progress = [weak, transfer](Value fraction) { + if (weak.lock() && transfer != nullptr) { + transfer->progress.set(std::move(fraction)); + } + }; + // Settles with the members the mutation's body gets beside its own (the reference or the inline file), or the + // failure. + auto const settled = [this, weak, kept = detached(ctx), transfer, command = &command, done, + hold](std::expected reply) { + auto const held = weak.lock(); + if (!held) { + hold->release(); + return; + } + runtime().batch([&] { + if (transfer != nullptr) { + transfer->pending.set(false); + transfer->error.set(reply ? Value{} : Value{reply.error()}); + } + if (!reply) { + done(false); + hold->release(); + return; + } + NameRef const* const found = held->find(command->target); + // The mutation's body cannot name the reference (a body is checked where the mutation is declared), + // so the reference is added to it under `as`, `file` by default. + MutationRuntime& mutation = *found->mutation; + Value const base = evalIn(*held, kept.bindings.get(), mutation.decl().body); + ValueRecord fields = base.asRecord() == nullptr ? ValueRecord{} : *base.asRecord(); + for (auto& [member, value] : *reply) { + fields.insert_or_assign(member, std::move(value)); + } + // The run takes its own count before this one is given back, so pending never reads zero in between. + mutation.run(Value{std::move(fields)}, std::make_shared(*kept.bindings), + [done](bool succeeded, Value const&) { done(succeeded); }); + hold->release(); + }); + }; + if (host == nullptr) { + unsupported(command, "`upload`"); + done(false); + return; + } + if (transfer != nullptr) { + transfer->pending.set(true); + transfer->progress.set(Value{std::int64_t{0}}); + transfer->error.set(Value{}); + } + NameRef const* const target = scope.find(command.target); + UploadRequest request{.file = file, .modelType = {}, .action = {}}; + if (target != nullptr && target->category == NameCategory::Mutation && target->mutation != nullptr) { + request.modelType = target->mutation->typeId(); + request.action = target->mutation->decl().action; + } + std::string const member = command.binding.empty() ? std::string{"file"} : command.binding; + bool started = false; + if (command.bytes) { + std::size_t const cap = session.options().maxInlineFileBytes; + started = host->readFile( + file, cap, + [this, settled, progress, cap, member, command = &command](std::expected read) { + if (!read) { + settled(std::unexpected(read.error())); + return; + } + if (read->bytes.size() > cap) { + // The host should have refused it; the cap holds whether or not it did. + std::string why = "upload: " + sizeText(read->bytes.size()) + " is over the " + sizeText(cap) + + " inline cap; send it through the file store"; + report(command->path, why); + settled(std::unexpected(std::move(why))); + return; + } + progress(Value{std::int64_t{1}}); + ValueRecord added; + added.insert_or_assign(member, Value{base64Encode(read->bytes)}); + if (!command->nameAs.empty()) { + added.insert_or_assign(command->nameAs, Value{read->name}); + } + if (!command->typeAs.empty()) { + added.insert_or_assign(command->typeAs, Value{read->mediaType}); + } + settled(std::move(added)); + }); + } else { + started = host->uploadFor(request, progress, [settled, member](std::expected reference) { + if (!reference) { + settled(std::unexpected(reference.error())); + return; + } + ValueRecord added; + added.insert_or_assign(member, *std::move(reference)); + settled(std::move(added)); + }); + } + if (!started) { + if (transfer != nullptr) { + transfer->pending.set(false); + transfer->progress.set(Value{}); + } + unsupported(command, "`upload`"); + done(false); + return; + } + hold->take(); +} + +} // namespace detail + +namespace detail { +namespace { + +// --- Lowering -------------------------------------------------------------------------------------------------- + +/// @brief A value as a `bool` property: `true` only for `true`. +/// @param value The value. +/// @param format Unused. +/// @return It. +[[nodiscard]] bool boolOf(Value const& value, FormatContext const& format) { + static_cast(format); + bool const* const flag = value.asBool(); + return flag != nullptr && *flag; +} + +/// @brief A value as a text property. +/// @param value The value. +/// @param format The formatting facts. +/// @return Its text. +[[nodiscard]] std::string stringOf(Value const& value, FormatContext const& format) { return textOf(value, format); } +} // namespace + +[[nodiscard]] std::string componentText(Value const& value, std::string_view type, FormatContext const& format) { + if (type == "json") { + return canonicalJson(value); + } + if (type == "int" || type == "exact") { + if (std::int64_t const* const whole = value.asInt()) { + return std::to_string(*whole); + } + // A value that cannot be rounded at its own places is written as its exact JSON, never clamped. + if (Decimal const* const number = value.asDecimal()) { + return detail::decimalText(number->value, static_cast(number->value.decimalPlaces.value)) + .value_or(canonicalJson(value)); + } + if (Quantity const* const quantity = value.asQuantity()) { + auto const text = + detail::decimalText(quantity->value, static_cast(quantity->value.decimalPlaces.value)); + return text ? *text + " " + quantity->unit : canonicalJson(value); + } + } + return textOf(value, format); +} +namespace { + +/// @brief An exact rational as the nearest double, unrounded. +/// +/// `Rational::toDouble` rounds to the value's own places, which is a display reading: `29 / 100` keeps its operands' +/// 0 places and would read as 0. The view tree wants the magnitude, so the lowering reads it here. +/// @param value The rational. +/// @return Its numerator divided by its denominator. +[[nodiscard]] double realOf(math::Rational const& value) noexcept { + return static_cast(value.numerator) / static_cast(value.denominator); +} +} // namespace + +[[nodiscard]] double componentNumber(Value const& value) { + if (std::int64_t const* const whole = value.asInt()) { + return static_cast(*whole); + } + if (Decimal const* const number = value.asDecimal()) { + return realOf(number->value); + } + if (Quantity const* const quantity = value.asQuantity()) { + return realOf(quantity->value); + } + return 0.0; +} + +[[nodiscard]] Value componentPayload(std::string const& payload, Type const* type) { + std::string_view const text{payload}; + if (text.starts_with("i:")) { + std::int64_t whole = 0; + std::string_view const digits = text.substr(2); + char const* const last = std::to_address(digits.end()); + auto const [end, error] = std::from_chars(std::to_address(digits.begin()), last, whole); + if (error == std::errc{} && end == last) { + return Value{whole}; + } + } + if (text.starts_with("s:")) { + return Value{std::string{text.substr(2)}}; + } + if (auto json = parseJson(text); json && type != nullptr) { + if (auto value = valueFromJson(*json, *type)) { + return std::move(*value); + } + } + return Value{payload}; +} + +[[nodiscard]] std::int64_t intOf(Value const& value, std::int64_t fallback) { + if (std::int64_t const* const number = value.asInt()) { + return *number; + } + if (Decimal const* const number = value.asDecimal()) { + // Integer division truncates toward zero, and reads the exact value rather than one rounded to its places. + return number->value.numerator / number->value.denominator; + } + return fallback; +} +namespace { + +/// @brief A text role by name. +/// @param name `normal`, `muted`, `heading` (or `title`), `section`, `error`, `success`, `mono`, `display`, `small`, +/// `overline`, `caption`, `label`, `headline`. +/// @return The role; `nullopt` for any other name. +[[nodiscard]] std::optional roleNamed(std::string_view name) { + if (name == "normal") { + return TextRole::Normal; + } + if (name == "muted") { + return TextRole::Muted; + } + if (name == "heading" || name == "title") { + return TextRole::Heading; + } + if (name == "section") { + return TextRole::Section; + } + if (name == "error") { + return TextRole::Error; + } + if (name == "success") { + return TextRole::Success; + } + if (name == "mono") { + return TextRole::Mono; + } + if (name == "display") { + return TextRole::Display; + } + if (name == "small") { + return TextRole::Small; + } + if (name == "overline") { + return TextRole::Overline; + } + if (name == "caption") { + return TextRole::Caption; + } + if (name == "label") { + return TextRole::Label; + } + if (name == "headline") { + return TextRole::Headline; + } + return std::nullopt; +} + +/// @brief What a role that names none is told: the names `roleNamed` reads. +constexpr std::string_view kRoleNames = + "a role is normal, muted, heading, section, error, success, mono, display, small, overline, caption, label or " + "headline"; + +/// @brief A text role by name, as `roleNamed` reads it. +/// @param value The name. +/// @param format Unused. +/// @return The role; `Normal` for any other name. +[[nodiscard]] TextRole roleOf(Value const& value, FormatContext const& format) { + return roleNamed(textOf(value, format)).value_or(TextRole::Normal); +} + +/// @brief A tone by name. +/// @param value `neutral`, `info`, `ok` (or `success`), `warn` (or `warning`), `err` (or `error`). +/// @param format Unused. +/// @return The tone; `Neutral` for anything else. +[[nodiscard]] Tone toneOf(Value const& value, FormatContext const& format) { + std::string const text = textOf(value, format); + if (text == "info") { + return Tone::Info; + } + if (text == "ok" || text == "success") { + return Tone::Ok; + } + if (text == "warn" || text == "warning") { + return Tone::Warn; + } + if (text == "err" || text == "error") { + return Tone::Err; + } + return Tone::Neutral; +} +} // namespace + +[[nodiscard]] std::optional toneNamed(Value const& value) { + if (value.isNull()) { + return Tone::Neutral; + } + static constexpr std::array, 5> kTones = {{ + {"neutral", Tone::Neutral}, + {"info", Tone::Info}, + {"ok", Tone::Ok}, + {"warn", Tone::Warn}, + {"err", Tone::Err}, + }}; + if (std::string const* const text = value.asString()) { + // A loop, not std::ranges::find: an array's iterator is a pointer on some standard libraries and not on + // others, so `auto` there reads differently to each. + for (auto const& [name, tone] : kTones) { + if (name == *text) { + return tone; + } + } + } + return std::nullopt; +} + +[[nodiscard]] std::vector spansOf(Value const& value, FormatContext const& format, bool& dropped, + bool* badTone) { + std::vector spans; + if (value.isNull()) { + return spans; + } + ValueList const* const runs = value.asList(); + if (runs == nullptr) { + dropped = true; + return spans; + } + auto const flag = [](Value const* field) { + bool const* const set = field != nullptr ? field->asBool() : nullptr; + return set != nullptr && *set; + }; + for (Value const& run : *runs) { + if (run.asRecord() == nullptr) { + if (run.isNull() || run.asList() != nullptr) { + dropped = true; + } else { + spans.push_back(TextSpan{.text = textOf(run, format)}); + } + continue; + } + Value const* const text = run.field("text"); + if (text == nullptr) { + dropped = true; + continue; + } + Tone tone = Tone::Neutral; + if (Value const* const named = run.field("tone")) { + if (std::optional const known = toneNamed(*named)) { + tone = *known; + } else if (badTone != nullptr) { + *badTone = true; + } + } + spans.push_back(TextSpan{.text = textOf(*text, format), + .strong = flag(run.field("strong")), + .mono = flag(run.field("mono")), + .tone = tone, + .action = flag(run.field("action"))}); + } + return spans; +} +namespace { + +/// @brief Whether a scope declares any name, so a node in it reads names the screen's own scope lacks. +/// @param scope The scope. +/// @return True when it declares a model, state, let, query, mutation, watch or check. +[[nodiscard]] bool declaresNames(ScopeDecl const& scope) noexcept { + return !(scope.models.empty() && scope.state.empty() && scope.lets.empty() && scope.queries.empty() && + scope.mutations.empty() && scope.watches.empty() && scope.checks.empty()); +} + +/// @brief What a span list with a run it drops is told. +constexpr std::string_view kSpansReason = + "spans is a list of runs, each a value or a record with `text`; a list, a null or a record without `text` is " + "dropped"; + +/// @brief What a tone of no known name is told. +constexpr std::string_view kToneNames = "a tone is neutral, info, ok, warn or err, or null for none"; + +/// @brief What a span list with a run of a tone of no known name is told. +constexpr std::string_view kSpanToneReason = + "a run's tone is neutral, info, ok, warn or err, or null for none; a run of another tone is drawn untoned"; + +/// @brief A splitter's `sizes`: a list of numbers, each read as `intOf` reads it. +/// @param value The value. +/// @return The sizes; `nullopt` for anything but a list whose every item is an `int` or a decimal. +[[nodiscard]] std::optional> splitterSizesOf(Value const& value) { + ValueList const* const items = value.asList(); + if (items == nullptr) { + return std::nullopt; + } + std::vector sizes; + sizes.reserve(items->size()); + for (Value const& item : *items) { + if (item.asInt() == nullptr && item.asDecimal() == nullptr) { + return std::nullopt; + } + sizes.push_back(static_cast(intOf(item, 0))); + } + return sizes; +} +} // namespace + +[[nodiscard]] Sizing sizingOf(Value const& value) { + if (Value const* const fixed = value.field("fixed")) { + return Sizing::fixed(static_cast(intOf(*fixed, 0))); + } + if (Value const* const percent = value.field("percent")) { + return Sizing::percent(static_cast(intOf(*percent, 1))); + } + if (Value const* const stretch = value.field("stretch")) { + return Sizing::stretch(static_cast(intOf(*stretch, 1))); + } + return Sizing::content(); +} + +[[nodiscard]] bool isSizing(Value const& value) { + if (std::string const* const text = value.asString()) { + return *text == "content"; + } + ValueRecord const* const record = value.asRecord(); + if (record == nullptr || record->size() != 1 || record->begin()->second.asInt() == nullptr) { + return false; + } + if (record->contains("percent")) { + std::int64_t const share = *record->begin()->second.asInt(); + return share >= 1 && share <= 100; + } + return record->contains("fixed") || record->contains("stretch"); +} +namespace { + +/// @brief An alignment by name, as the loader checked it: `start`, `center`, `end`, or stretch for none. +/// @param name The name; empty for none. +/// @return The alignment. +[[nodiscard]] Align alignOf(std::string_view name) { + if (name == "start") { + return Align::Start; + } + if (name == "center") { + return Align::Center; + } + if (name == "end") { + return Align::End; + } + return Align::Stretch; +} + +/// @brief A table cell's place by name: across its column (`align`) or down its row (`valign`). +/// @param name `start`, `center` or `end`. +/// @return The place; `nullopt` for any other name, `stretch` included. +[[nodiscard]] std::optional cellPlaceNamed(std::string_view name) { + if (name == "start") { + return Align::Start; + } + if (name == "center") { + return Align::Center; + } + if (name == "end") { + return Align::End; + } + return std::nullopt; +} + +/// @brief A justification by name, as the loader checked it: `center`, `end`, `between`, or start for none. +/// @param name The name; empty for none. +/// @return The justification. +[[nodiscard]] Justify justifyOf(std::string_view name) { + if (name == "center") { + return Justify::Center; + } + if (name == "end") { + return Justify::End; + } + if (name == "between") { + return Justify::Between; + } + return Justify::Start; +} + +/// @brief An axis by name: `horizontal`, or vertical for anything else. +/// @param value The value. +/// @return The axis. +[[nodiscard]] Axis axisOf(Value const& value) { + std::string const* const text = value.asString(); + return text != nullptr && *text == "horizontal" ? Axis::Horizontal : Axis::Vertical; +} + +/// @brief A step's state by name: `active`, `done`, `failed`, or pending for anything else. +/// @param name The name. +/// @return The state. +[[nodiscard]] StepState stepStateOf(std::string_view name) { + if (name == "active") { + return StepState::Active; + } + if (name == "done") { + return StepState::Done; + } + return name == "failed" ? StepState::Failed : StepState::Pending; +} + +/// @brief The options of a select, from a list of scalars or of records with a key and a `label`. +/// @param options The list. +/// @param format The formatting facts. +/// @return The options. +[[nodiscard]] std::vector selectOptions(Value const& options, FormatContext const& format) { + std::vector out; + if (ValueList const* const items = options.asList()) { + for (Value const& option : *items) { + Value const key = optionKey(option); + Value const* const label = option.field("label"); + out.push_back(SelectOption{.key = keyOf(key), .label = textOf(label != nullptr ? *label : key, format)}); + } + } + return out; +} + +/// @brief What a percent sizes, as a refusal or a report says it. +constexpr std::string_view kPercentPlaces = + "`percent` sizes a width along a row or a horizontal splitter; nothing here takes a share"; +/// @brief Why a percent inside a case or an overlay's content is not a share. +constexpr std::string_view kPercentInHolder = "size the `switch` or the overlay itself; its content fills it"; + +/// @brief The default spacing step between the children of a document panel or collapsible, the mockups' 8 px. +constexpr int kPanelGap = 2; +/// @brief The default spacing step between the children of a document dialog or drawer, the mockups' 12 px. +constexpr int kDialogGap = 3; + +/// @brief A node's size request. +/// @param node The node; may be null. +/// @return Its layout hints, or none for a null node or a kind that has no `Common`. +[[nodiscard]] LayoutHints layoutHintsOf(Node const& node) { + if (!node) { + return {}; + } + return std::visit( + [](auto const& spec) -> LayoutHints { + if constexpr (requires { spec.common.layout; }) { + return spec.common.layout; + } else { + return {}; + } + }, + node->kind); +} + +/// @brief A node with its width sizing replaced; a node of a kind with no layout is returned as it is. +/// @param node The node. +/// @param width The sizing. +/// @return The node. +[[nodiscard]] Node withWidth(Node const& node, Sizing width) { + if (!node) { + return node; + } + auto copy = std::make_shared(*node); + std::visit( + [&width](auto& spec) { + if constexpr (requires { spec.common.layout; }) { + spec.common.layout.width = width; + } + }, + copy->kind); + return copy; +} + +/// @brief The size request of a holder of @p sizings: a stretch by the largest weight where any is a stretch, and +/// content otherwise (a share of a row is not a holder's: `listColumn` passes a lone child's on). +/// @param sizings One dimension's sizing of each child. +/// @return The holder's sizing. +[[nodiscard]] Sizing holderSizing(std::span sizings) { + int weight = 0; + for (Sizing const& sizing : sizings) { + if (sizing.kind == Sizing::Kind::Stretch) { + weight = std::max(weight, sizing.amount); + } + } + return weight > 0 ? Sizing::stretch(weight) : Sizing::content(); +} + +/// @brief The column that holds a node list. It stretches along an axis when one of its children does, so the +/// content means what its nodes would mean written inline in the holder's parent. +/// @param children The content. +/// @param gap The spacing step between children. +/// @return The column; bounds and `alignSelf` stay unset, because they belong to a child. +[[nodiscard]] Column listColumn(std::vector children, int gap = 0) { + std::vector widths; + std::vector heights; + for (Node const& child : children) { + LayoutHints const hints = layoutHintsOf(child); + widths.push_back(hints.width); + heights.push_back(hints.height); + } + // A lone child's share of its row is the holder's, and the child fills the holder, so the share is taken once. + if (children.size() == 1 && widths.front().kind == Sizing::Kind::Percent) { + Sizing const share = widths.front(); + children.front() = withWidth(children.front(), Sizing::stretch(1)); + Column column{.children = std::move(children), .gap = gap}; + column.common.layout.width = share; + column.common.layout.height = holderSizing(heights); + return column; + } + Column column{.children = std::move(children), .gap = gap}; + column.common.layout.width = holderSizing(widths); + column.common.layout.height = holderSizing(heights); + return column; +} + +/// @brief Content whose scope is made when it mounts and released when it unmounts: a one-row `forEach` whose +/// row view builds it. +/// @param build Builds the content, its scope included. +/// @param hints The size request of the content. A slot reads the sizing of its direct child alone, which is this +/// `forEach`, so the content's stretch reaches the slot only through these. +/// @return The node. +[[nodiscard]] Node lazy(std::function build, LayoutHints const& hints = {}) { + Common common; + common.layout = hints; + return ui::forEach([] { return std::vector{0}; }, [](int const&) { return Key{std::int64_t{0}}; }, + [build = std::move(build)](reactive::Signal const&) { return build(); }, + Axis::Vertical, 0, common); +} + +/// @brief A column of content that holds its scope for as long as it is mounted: its `visible` is a binding +/// that keeps the scope alive and reads nothing. +/// @param children The content. +/// @param scope The scope. +/// @param keys The chords of the content. +/// @param gap The spacing step between the children. +/// @return The node. +[[nodiscard]] Node holding(std::vector children, std::shared_ptr scope, + std::vector keys = {}, int gap = 0) { + Column column = listColumn(std::move(children), gap); + column.common.visible = Prop{[held = std::move(scope)] { return held != nullptr; }}; + column.common.keys = std::move(keys); + return ui::column(std::move(column)); +} + +/// @brief Whether an expression reads a name in @p names. +/// @param expr The expression. +/// @param names The names. +/// @return Whether any form of the expression names one. +// NOLINTBEGIN(misc-no-recursion): an expression nests its arguments and fields, and the walk follows them. +[[nodiscard]] bool readsAny(ExprPtr const& expr, std::set> const& names) { + if (!expr) { + return false; + } + if (!expr->name.empty() && names.contains(expr->name)) { + return true; + } + return std::ranges::any_of(expr->args, [&](ExprPtr const& arg) { return readsAny(arg, names); }) || + std::ranges::any_of(expr->fields, [&](auto const& field) { return readsAny(field.second, names); }); +} +// NOLINTEND(misc-no-recursion) + +/// @brief Collects the element ids of a document subtree. +/// @param node The root. +/// @param out Receives the ids. +// NOLINTNEXTLINE(misc-no-recursion): a node's children and parts are nodes, and the walk follows them. +void collectIds(DocNode const& node, std::set>& out) { + if (!node.id.empty()) { + out.insert(node.id); + } + for (auto const* group : {&node.children, &node.parts}) { + for (auto const& [key, list] : *group) { + for (DocNodePtr const& child : list) { + collectIds(*child, out); + } + } + } +} +} // namespace + +// NOLINTNEXTLINE(misc-no-recursion): lowering a node lowers its children, which come back through here. +Node ScreenCore::lowerAll(std::span nodes, LowerCtx const& ctx, int gap) { + LowerCtx listCtx = ctx; + listCtx.listGap = gap; + if (nodes.size() == 1) { + return lower(*nodes.front(), listCtx); + } + std::vector children; + children.reserve(nodes.size()); + for (DocNodePtr const& child : nodes) { + children.push_back(lower(*child, listCtx)); + } + // Several nodes share a holder, and a share of a row is not a share of a holder: each is reported and takes its + // content size. + for (auto&& [child, written] : std::views::zip(children, nodes)) { + if (layoutHintsOf(child).width.kind == Sizing::Kind::Percent) { + report(written->path, + "a percent among several nodes is a share of their holder; " + std::string{kPercentPlaces}); + child = withWidth(child, Sizing::content()); + } + } + Column holder = listColumn(std::move(children), gap); + // The column is the mount's, not the document's: a child that bleeds reaches past the padding of the container + // the document names, so the column passes that padding on instead of hiding it. + holder.holder = true; + return ui::column(std::move(holder)); +} + +void ScreenCore::fillHolder(std::vector& children, std::string const& path) { + for (Node& child : children) { + if (layoutHintsOf(child).width.kind == Sizing::Kind::Percent) { + report(path, std::string{kPercentInHolder}); + child = withWidth(child, Sizing::stretch(1)); + } + } +} + +LayoutHints ScreenCore::nodeHints(DocNode const& node, std::set> const& own, + LowerCtx const& ctx) { + LayoutHints hints; + if (ExprPtr const sizing = node.prop("sizing")) { + if (sizing->kind != ExprKind::Literal && readsAny(sizing, own)) { + report(sizing->path, + "this sizing reads a name the case declares, so the case is held at its " + "content size"); + } else { + Value const value = once(ctx, sizing); + Value const* const width = value.field("width"); + Value const* const height = value.field("height"); + if (width != nullptr || height != nullptr) { + hints.width = width != nullptr && isSizing(*width) ? sizingOf(*width) : Sizing::content(); + hints.height = height != nullptr && isSizing(*height) ? sizingOf(*height) : Sizing::content(); + } else if (isSizing(value)) { + hints.width = sizingOf(value); + } + } + } + return hints; +} + +LayoutHints ScreenCore::holderHints(std::span content, ScopeDecl const* decl, + LowerCtx const& ctx) { + std::set> own; + for (DocNode const* const node : content) { + collectIds(*node, own); + } + if (decl != nullptr) { + for (ModelDecl const& model : decl->models) { + own.insert(model.name); + } + for (StateDecl const& state : decl->state) { + own.insert(state.name); + } + for (LetDecl const& let : decl->lets) { + own.insert(let.name); + } + for (QueryDecl const& query : decl->queries) { + own.insert(query.name); + } + for (MutationDecl const& mutation : decl->mutations) { + own.insert(mutation.name); + } + } + std::vector widths; + std::vector heights; + for (DocNode const* const node : content) { + LayoutHints const hints = nodeHints(*node, own, ctx); + widths.push_back(hints.width); + heights.push_back(hints.height); + } + LayoutHints out; + out.width = holderSizing(widths); + out.height = holderSizing(heights); + return out; +} + +// NOLINTBEGIN(misc-no-recursion): a menu nests, and lowering descends the document. +Node ScreenCore::lower(DocNode const& node, LowerCtx const& ctx) { + if (recording) { + if (loweredNodes.size() >= kPruneLoweredAt && loweredNodes.size() % kPruneLoweredAt == 0) { + std::erase_if(loweredNodes, [](LoweredNode const& entry) { return entry.scope.expired(); }); + } + loweredNodes.push_back(LoweredNode{.node = &node, .scope = ctx.scope, .bindings = ctx.bindings}); + } + // Only a switch reads the gap of the list around it; every other kind's children are held by a holder that sets + // their gap, so none sees its grandparent's. + if (ctx.listGap != 0 && node.kind != "switch") { + LowerCtx plain = ctx; + plain.listGap = 0; + return lowerKind(node, plain, elementFor(*ctx.scope, node)); + } + return lowerKind(node, ctx, elementFor(*ctx.scope, node)); +} + +Prop ScreenCore::roleProp(LowerCtx const& ctx, ExprPtr const& expr) { + if (!expr || expr->kind == ExprKind::Literal) { + return bindProp(ctx, expr, TextRole::Normal, roleOf); + } + return slotProp([this, scope = ctx.scope, bindings = ctx.bindings, expr] { + Value const value = evalIn(*scope, bindings.get(), expr); + std::optional const role = roleNamed(textOf(value, scope->formatting())); + if (!role) { + report(expr->path, "role is " + canonicalJson(value) + "; " + std::string{kRoleNames}); + } + return role.value_or(TextRole::Normal); + }); +} + +Prop ScreenCore::surfaceOf(DocNode const& node, LowerCtx const& ctx) { + ExprPtr const expr = node.prop("surface"); + auto nameOf = [this, path = pointerAppend(node.path, "surface")](Value const& value) -> std::string { + if (std::string const* const name = value.asString()) { + return *name; + } + if (!value.isNull()) { + report(path, "a surface is the name of one; " + canonicalJson(value) + " is not a string"); + } + return {}; + }; + if (!expr || expr->kind == ExprKind::Literal) { + return expr ? Prop{nameOf(expr->literal)} : Prop{std::string{}}; + } + return slotProp([scope = ctx.scope, bindings = ctx.bindings, expr, nameOf = std::move(nameOf)] { + return nameOf(evalIn(*scope, bindings.get(), expr)); + }); +} + +KeyValueItem ScreenCore::keyValueItemOf(Value const& item, std::string const& path, RtScope const& scope) { + FormatContext const& format = scope.formatting(); + Value const* const label = item.field("label"); + Value const* const value = item.field("value"); + KeyValueItem out{.label = label == nullptr ? std::string{} : textOf(*label, format), + .value = value == nullptr ? std::string{} : textOf(*value, format)}; + if (Value const* const spans = item.field("spans")) { + bool dropped = false; + bool badTone = false; + out.spans = spansOf(*spans, format, dropped, &badTone); + if (dropped) { + report(path, kSpansReason); + } + if (badTone) { + report(path, kSpanToneReason); + } + } + if (Value const* const tone = item.field("tone")) { + std::optional const named = toneNamed(*tone); + if (!named) { + report(path, "an item's tone is " + canonicalJson(*tone) + "; " + std::string{kToneNames}); + } + out.tone = named.value_or(Tone::Neutral); + } + return out; +} + +// A group needs no widget of its own: it lowers to kinds every backend has, so the view tree and the contract do not +// change. Its description is a line read in order after its children, since `Common` carries no accessible +// description. +Node ScreenCore::lowerGroup(DocNode const& node, LowerCtx const& ctx, ElementState* element, + std::vector children) { + Text legend{.text = bindProp(ctx, node.prop("label"), std::string{}, stringOf), + .role = TextRole::Label}; + legend.field.required = bindProp(ctx, node.prop("required"), false, boolOf); + std::vector column; + column.reserve(children.size() + 3); + column.push_back(ui::text(std::move(legend))); + std::ranges::move(children, std::back_inserter(column)); + if (ExprPtr const description = node.prop("description")) { + Text line{.text = bindProp(ctx, description, std::string{}, stringOf), .role = TextRole::Muted}; + line.common.visible = slotProp([scope = ctx.scope, bindings = ctx.bindings, description] { + return !textOf(evalIn(*scope, bindings.get(), description), scope->formatting()).empty(); + }); + column.push_back(ui::text(std::move(line))); + } + // The shown errors, one line each: a check that targets the group shows its message here. + auto shown = [this, element, scope = ctx.scope, bindings = ctx.bindings, errors = node.prop("errors")] { + return stringsOf(element != nullptr ? elementValue(*element, "shownErrors") + : evalIn(*scope, bindings.get(), errors)); + }; + Text messages{.text = slotProp([shown] { + std::string joined; + for (std::string const& message : shown()) { + joined += (joined.empty() ? "" : "\n") + message; + } + return joined; + }), + .role = TextRole::Error}; + messages.common.visible = slotProp([shown] { return !shown().empty(); }); + column.push_back(ui::text(std::move(messages))); + Column spec{.children = std::move(column), + .gap = static_cast(intOf(node.prop("gap") ? once(ctx, node.prop("gap")) : Value{}, 0))}; + commonOf(node, ctx, element, spec.common); + if (spec.common.a11y.role.empty()) { + spec.common.a11y.role = "group"; + } + bool const named = std::ranges::any_of(node.partList("a11y"), + [](DocNodePtr const& a11y) { return a11y->prop("name") != nullptr; }); + if (!named) { + spec.common.a11y.name = bindProp(ctx, node.prop("label"), std::string{}, stringOf); + } + return ui::column(std::move(spec)); +} + +Prop> ScreenCore::spansProp(LowerCtx const& ctx, ExprPtr const& expr) { + return slotProp>([this, scope = ctx.scope, bindings = ctx.bindings, expr] { + bool dropped = false; + bool badTone = false; + std::vector spans = + spansOf(evalIn(*scope, bindings.get(), expr), scope->formatting(), dropped, &badTone); + if (dropped) { + report(expr->path, kSpansReason); + } + if (badTone) { + report(expr->path, kSpanToneReason); + } + return spans; + }); +} + +// The size request: `sizing` (the width, or both dimensions), `alignSelf`, and the bounds. +void ScreenCore::layoutOf(DocNode const& node, LowerCtx const& ctx, LayoutHints& layout) { + if (ExprPtr const sizing = node.prop("sizing")) { + // The width, or both dimensions from a `{width, height}` record, one left out being content. The loader + // refuses a literal of another form; a computed one that is none is reported and lowers to content. + Value const value = once(ctx, sizing); + Value const* const width = value.field("width"); + Value const* const height = value.field("height"); + bool const record = width != nullptr || height != nullptr; + bool const valid = record ? (width == nullptr || isSizing(*width)) && (height == nullptr || isSizing(*height)) + : isSizing(value); + if (!valid) { + report(sizing->path, "sizing is " + canonicalJson(value) + + "; a sizing is \"content\", {\"fixed\": n}, {\"stretch\": w}, {\"percent\": n} " + "with n from 1 to 100, or a record of width and height of them"); + } else if (record) { + layout.width = width != nullptr ? sizingOf(*width) : Sizing::content(); + layout.height = height != nullptr ? sizingOf(*height) : Sizing::content(); + if (layout.height.kind == Sizing::Kind::Percent) { + report(sizing->path, std::string{kPercentPlaces}); + layout.height = Sizing::content(); + } + } else { + layout.width = sizingOf(value); + } + } + if (std::string_view const placed = node.name("alignSelf"); !placed.empty()) { + layout.alignSelf = alignOf(placed); + } + layout.bleed = node.flag("bleed"); + // Literal integers, checked at load. + for (auto const& [key, bound] : + {std::pair{"minWidth", &LayoutHints::minWidth}, std::pair{"maxWidth", &LayoutHints::maxWidth}, + std::pair{"minHeight", &LayoutHints::minHeight}, std::pair{"maxHeight", &LayoutHints::maxHeight}}) { + if (ExprPtr const expr = node.prop(key); expr != nullptr && expr->literal.asInt() != nullptr) { + layout.*bound = static_cast(*expr->literal.asInt()); + } + } +} +namespace { + +/// @brief Where a declaration is lowered, as a focus key reads it. +struct FocusPlace { + /// @brief The focus key of the component use it is lowered for, and `>`; empty outside a component. + std::string prefix; + /// @brief The keys of the rows that enclose it, outermost first. + std::vector rows; +}; + +/// @brief Where @p scope is: the row keys of its chain and the component use it is lowered for. +/// @param scope The scope. +/// @return It. +[[nodiscard]] FocusPlace focusPlace(RtScope const& scope) { + FocusPlace place; + for (RtScope const* current = &scope; current != nullptr; current = current->parent.get()) { + if (current->row != nullptr) { + place.rows.push_back(current->rowKey); + } + if (current->parent == nullptr) { + place.prefix = current->usePrefix; + } + } + std::ranges::reverse(place.rows); + return place; +} + +/// @brief A focus key: a declaration's pointer under its component use's prefix, with one key per enclosing row. +/// @param place Where the declaration is lowered. +/// @param path The declaring node's JSON Pointer. +/// @return The key, unique per declaration, row and component use. +[[nodiscard]] std::string focusKey(FocusPlace const& place, std::string_view path) { + std::string key = place.prefix; + key += path; + for (std::string const& row : place.rows) { + key += '@'; + key += row; + } + return key; +} + +/// @brief The focus key of the element @p path declares, lowered in @p scope. +/// @param path The declaring node's JSON Pointer. +/// @param scope The scope it is lowered in. +/// @return The key. +[[nodiscard]] std::string focusKeyOf(std::string_view path, RtScope const& scope) { + return focusKey(focusPlace(scope), path); +} +} // namespace + +void ScreenCore::commonOf(DocNode const& node, LowerCtx const& ctx, ElementState* element, Common& common) { + static_cast(element); + common.visible = bindProp(ctx, node.prop("visible"), true, boolOf); + common.enabled = bindProp(ctx, node.prop("enabled"), true, boolOf); + common.tooltip = bindProp(ctx, node.prop("tooltip"), std::string{}, stringOf); + layoutOf(node, ctx, common.layout); + common.testId = std::string{node.name("testId")}; + if (!node.id.empty()) { + common.focusId = focusKeyOf(node.path, *ctx.scope); + } + common.surface = surfaceOf(node, ctx); + if (ExprPtr const autofocus = node.prop("autofocus")) { + common.autofocus = boolOf(once(ctx, autofocus), ctx.scope->formatting()); + } + for (DocNodePtr const& a11y : node.partList("a11y")) { + common.a11y.name = bindProp(ctx, a11y->prop("name"), std::string{}, stringOf); + common.a11y.role = std::string{a11y->name("role")}; + } + for (DocNodePtr const& drag : node.partList("drag")) { + ExprPtr const payload = drag->prop("payload"); + common.dragKey = slotProp>( + [scope = ctx.scope, bindings = ctx.bindings, payload]() -> std::optional { + Value const value = evalIn(*scope, bindings.get(), payload); + return value.isNull() ? std::nullopt : std::optional{keyOf(value)}; + }); + } + for (DocNodePtr const& drop : node.partList("drop")) { + ExprPtr const accepts = drop->prop("accepts"); + common.accepts = [this, scope = ctx.scope, bindings = ctx.bindings, accepts](Key const& key) { + if (!accepts) { + return true; + } + Value const accepted = runtime().untracked([&] { return evalIn(*scope, bindings.get(), accepts); }); + if (ValueList const* const items = accepted.asList()) { + return std::ranges::any_of(*items, [&](Value const& item) { return keyOf(item) == key; }); + } + return accepted.isNull() || keyOf(accepted) == key; + }; + common.onDrop = [this, ctx, commands = drop->event("onDrop")](Key const& key) { + runEvent(commands, ctx, valueOfKey(key)); + }; + } + for (auto const& [chord, commands] : node.keys) { + common.keys.push_back( + KeyBinding{.chord = chord, .onPress = [this, ctx, list = &commands] { runEvent(list, ctx, Value{}); }}); + } +} + +void ScreenCore::fieldOf(DocNode const& node, LowerCtx const& ctx, ElementState* element, FieldState& field) { + field.readonly = bindProp(ctx, node.prop("readonly"), false, boolOf); + field.required = bindProp(ctx, node.prop("required"), false, boolOf); + field.stale = bindProp(ctx, node.prop("stale"), false, boolOf); + if (element != nullptr) { + field.errors = slotProp>( + [this, scope = ctx.scope, element] { return stringsOf(elementValue(*element, "shownErrors")); }); + } else if (ExprPtr const errors = node.prop("errors")) { + field.errors = slotProp>([scope = ctx.scope, bindings = ctx.bindings, errors] { + return stringsOf(evalIn(*scope, bindings.get(), errors)); + }); + } + // A tone evaluates the value and is not an error: it changes the field's look and nothing of `valid`. + if (node.prop("description")) { + field.description = bindProp(ctx, node.prop("description"), std::string{}, stringOf); + } + if (node.prop("labelHint")) { + field.labelHint = bindProp(ctx, node.prop("labelHint"), std::string{}, stringOf); + } + if (ExprPtr const tone = node.prop("tone")) { + field.tone = slotProp([this, scope = ctx.scope, bindings = ctx.bindings, tone] { + Value const value = evalIn(*scope, bindings.get(), tone); + std::optional const named = toneNamed(value); + if (!named) { + report(tone->path, "tone is " + canonicalJson(value) + "; " + std::string{kToneNames}); + } + return named.value_or(Tone::Neutral); + }); + } +} + +MenuItem ScreenCore::menuItemOf(DocNode const& part, LowerCtx const& ctx) { + MenuItem item; + if (part.flag("separator")) { + item.separator = true; + return item; + } + item.label = bindProp(ctx, part.prop("label"), std::string{}, stringOf); + item.description = bindProp(ctx, part.prop("description"), std::string{}, stringOf); + item.visible = bindProp(ctx, part.prop("visible"), true, boolOf); + if (Commands const* const commands = part.event("onClick")) { + item.onSelect = [this, ctx, commands] { runEvent(commands, ctx, Value{}); }; + } + if (ExprPtr const icon = part.prop("icon")) { + item.icon = textOf(once(ctx, icon), ctx.scope->formatting()); + } + item.keys = std::string{part.name("keys")}; + if (ExprPtr const checked = part.prop("checked")) { + item.checked = slotProp>( + [scope = ctx.scope, bindings = ctx.bindings, checked]() -> std::optional { + Value const value = evalIn(*scope, bindings.get(), checked); + bool const* const flag = value.asBool(); + return flag == nullptr ? std::nullopt : std::optional{*flag}; + }); + } + item.enabled = bindProp(ctx, part.prop("enabled"), true, boolOf); + return item; +} + +// NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. +std::vector ScreenCore::menuItems(std::span parts, LowerCtx const& ctx) { + std::vector items; + for (DocNodePtr const& part : parts) { + MenuItem item = menuItemOf(*part, ctx); + if (!item.separator) { + item.items = menuItems(part->partList("items"), ctx); + } + items.push_back(std::move(item)); + } + return items; +} + +// NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. +std::vector ScreenCore::lowerHeadMenu(std::span parts, LowerCtx const& ctx) { + std::vector models; + models.reserve(parts.size()); + for (DocNodePtr const& part : parts) { + models.push_back(HeadMenuModel{.id = part->id, + .path = part->path, + .item = menuItemOf(*part, ctx), + .items = lowerHeadMenu(part->partList("items"), ctx)}); + } + return models; +} + +std::vector ScreenCore::lowerHeadTools(std::span parts, LowerCtx const& ctx) { + static constexpr int kSearchWidth = 30; + std::vector models; + models.reserve(parts.size()); + for (DocNodePtr const& part : parts) { + bool const search = part->name("kind") == "search"; + HeadToolModel model{ + .id = part->id, + .path = part->path, + .kind = search ? HeadToolKind::Search : HeadToolKind::Select, + .label = bindProp(ctx, part->prop("label"), std::string{}, stringOf), + .value = bindProp(ctx, part->prop("value"), std::string{}, stringOf), + .placeholder = bindProp(ctx, part->prop("placeholder"), std::string{}, stringOf), + .options = {}, + .selected = {}, + .width = search ? kSearchWidth : 0, + .enabled = bindProp(ctx, part->prop("enabled"), true, boolOf), + .visible = bindProp(ctx, part->prop("visible"), true, boolOf), + .edit = {}, + .submit = {}}; + if (ExprPtr const width = part->prop("width")) { + if (std::int64_t const* const units = width->literal.asInt()) { + model.width = static_cast(*units); + } + } + if (!search) { + model.options = slotProp>( + [scope = ctx.scope, bindings = ctx.bindings, options = part->prop("options")] { + return selectOptions(evalIn(*scope, bindings.get(), options), scope->formatting()); + }); + model.selected = slotProp>([scope = ctx.scope, bindings = ctx.bindings, + selected = part->prop("selected")]() -> std::optional { + Value const value = selected ? evalIn(*scope, bindings.get(), selected) : Value{}; + return value.isNull() ? std::nullopt : std::optional{keyOf(value)}; + }); + } + Commands const* const edited = part->event(search ? "onChange" : "onChoose"); + model.edit = [this, ctx, edited](Value event) { runEvent(edited, ctx, std::move(event)); }; + if (search) { + model.submit = [this, ctx, onSubmit = part->event("onSubmit")](Value event) { + runEvent(onSubmit, ctx, std::move(event)); + }; + } + models.push_back(std::move(model)); + } + return models; +} + +ActionModels ScreenCore::lowerActionParts(std::span parts, LowerCtx const& ctx) { + ActionModels models; + models.reserve(parts.size()); + for (DocNodePtr const& part : parts) { + ActionModel model{.id = part->id, + .path = part->path, + .label = bindProp(ctx, part->prop("label"), std::string{}, stringOf), + .icon = bindProp(ctx, part->prop("icon"), std::string{}, stringOf), + .iconOnly = bindProp(ctx, part->prop("iconOnly"), false, boolOf), + .emphasis = ButtonEmphasis::Normal, + .enabled = bindProp(ctx, part->prop("enabled"), true, boolOf), + .visible = bindProp(ctx, part->prop("visible"), true, boolOf), + .run = {}}; + model.emphasis = emphasisNamed(part->name("emphasis")).value_or(ButtonEmphasis::Normal); + if (Commands const* const commands = part->event("onClick")) { + model.run = [this, ctx, commands] { runEvent(commands, ctx, Value{}); }; + } + models.push_back(std::move(model)); + } + return models; +} + +Node ScreenCore::actionBarOf(ActionModels actions) { + ActionBar bar; + for (ActionModel& action : actions) { + Button button{.label = action.label, + .emphasis = action.emphasis, + .onClick = std::move(action.run), + .common = {}, + .icon = action.icon.evaluate()}; + if (action.iconOnly.isBound() || action.iconOnly.constant()) { + // The label is the button's name and tooltip; the caption is empty while the icon stands alone. + button.label = Prop{[label = action.label, iconOnly = action.iconOnly] { + return iconOnly.evaluate() ? std::string{} : label.evaluate(); + }}; + button.common.a11y.name = action.label; + button.common.tooltip = action.label; + } + button.common.visible = std::move(action.visible); + button.common.enabled = std::move(action.enabled); + button.common.testId = "action_" + action.id; + bar.children.push_back(ui::button(std::move(button))); + } + return ui::actionBar(std::move(bar)); +} + +std::vector ScreenCore::lowerBadgeParts(std::span parts, LowerCtx const& ctx) { + std::vector badges; + badges.reserve(parts.size()); + for (DocNodePtr const& part : parts) { + badges.push_back(BadgeModel{.text = bindProp(ctx, part->prop("text"), std::string{}, stringOf), + .tone = bindProp(ctx, part->prop("tone"), Tone::Neutral, toneOf), + .icon = bindProp(ctx, part->prop("icon"), std::string{}, stringOf), + .visible = bindProp(ctx, part->prop("visible"), true, boolOf)}); + } + return badges; +} + +// The readers every kind's lowering shares, each bound to the node being lowered. +class ScreenCore::KindKit { +public: + KindKit(ScreenCore& core, DocNode const& node, LowerCtx const& ctx, ElementState* element) + : _core{core}, _node{node}, _ctx{ctx}, _element{element}, _format{ctx.scope->formatting()} {} + + // The children under @p key, each lowered with @p gap as the gap of the list around it. + [[nodiscard]] std::vector children(std::string_view key, int gap = 0) const { + LowerCtx listCtx = _ctx; + listCtx.listGap = gap; + std::vector out; + for (DocNodePtr const& child : _node.nodes(key)) { + out.push_back(_core.lower(*child, listCtx)); + } + return out; + } + + // The children under @p key as one node: none is empty, several share a holder that sets @p gap. + [[nodiscard]] Node child(std::string_view key, int gap = 0) const { + auto const nodes = _node.nodes(key); + return nodes.empty() ? Node{} : _core.lowerAll(nodes, _ctx, gap); + } + + [[nodiscard]] std::int64_t onceInt(std::string_view key, std::int64_t fallback) const { + ExprPtr const expr = _node.prop(key); + return expr ? intOf(_core.once(_ctx, expr), fallback) : fallback; + } + + [[nodiscard]] bool onceBool(std::string_view key, bool fallback) const { + ExprPtr const expr = _node.prop(key); + return expr ? boolOf(_core.once(_ctx, expr), _format) : fallback; + } + + // A stack's padding: one step, or the loader-checked constant list of the vertical and the horizontal step. A + // computed padding that yields a list is not a step: it is reported once and taken as 0. + [[nodiscard]] Padding stackPadding() const { + ExprPtr const expr = _node.prop("padding"); + if (!expr) { + return {}; + } + Value const value = _core.once(_ctx, expr); + if (ValueList const* const steps = value.asList()) { + if (expr->kind == ExprKind::Literal && steps->size() == 2) { + return Padding{static_cast(intOf(steps->at(0), 0)), static_cast(intOf(steps->at(1), 0))}; + } + _core.report(_node.path + "/padding", "a computed `padding` is one spacing step, not a list; taken as 0"); + return {}; + } + return Padding{static_cast(intOf(value, 0))}; + } + + [[nodiscard]] std::string onceText(std::string_view key) const { + ExprPtr const expr = _node.prop(key); + return expr ? textOf(_core.once(_ctx, expr), _format) : std::string{}; + } + + [[nodiscard]] Prop textProp(std::string_view key) const { + return _core.bindProp(_ctx, _node.prop(key), std::string{}, stringOf); + } + + // A field shows no caption of its own, so its label is what names it to assistive technology. An `a11y` part + // that gives a name was written for that purpose and wins; one that gives only a role leaves the label. + void nameByLabel(Common& common) const { + bool const named = std::ranges::any_of(_node.partList("a11y"), + [](DocNodePtr const& a11y) { return a11y->prop("name") != nullptr; }); + if (_node.prop("label") && !named) { + common.a11y.name = textProp("label"); + } + } + + // A standalone input draws its label as a caption only when the document asks for it (`showLabel`). + template + void captionOf(Spec& spec) const { + if (_node.prop("label")) { + spec.label = textProp("label"); + } + spec.showLabel = _node.flag("showLabel"); + } + + [[nodiscard]] Action action(std::string_view key) const { + Commands const* const commands = _node.event(key); + if (commands == nullptr) { + return {}; + } + return [core = &_core, ctx = _ctx, commands] { core->runEvent(commands, ctx, Value{}); }; + } + + [[nodiscard]] ActionButton actionPart() const { + ActionButton button; + for (DocNodePtr const& part : _node.partList("action")) { + button.label = _core.bindProp(_ctx, part->prop("label"), std::string{}, stringOf); + if (Commands const* const commands = part->event("onClick")) { + button.onClick = [core = &_core, ctx = _ctx, commands] { core->runEvent(commands, ctx, Value{}); }; + } + } + return button; + } + + // A reader of the element's value under @p name. + [[nodiscard]] auto read(std::string_view name) const { + return [element = _element, core = &_core, name = std::string{name}] { + return core->elementValue(*element, name); + }; + } + +private: + // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members): the kit lives inside one lowering call, in + // which all four outlive it. + ScreenCore& _core; + DocNode const& _node; + LowerCtx const& _ctx; + ElementState* _element; + FormatContext const& _format; + // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members) +}; + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of ui/1. +std::optional ScreenCore::lowerWidget(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + std::string_view const kind = node.kind; + FormatContext const& format = ctx.scope->formatting(); + KindKit const kit{*this, node, ctx, element}; + if (kind == "text") { + Text spec{.role = roleProp(ctx, node.prop("role"))}; + // A text with spans shows them, so its `text`, an older client's fallback, is not lowered. + if (ExprPtr const spans = node.prop("spans")) { + spec.spans = spansProp(ctx, spans); + } else { + spec.text = kit.textProp("text"); + } + if (!node.name("align").empty()) { + spec.align = textAlignNamed(node.name("align")); + } + fieldOf(node, ctx, element, spec.field); + commonOf(node, ctx, element, spec.common); + return ui::text(std::move(spec)); + } + if (kind == "button") { + Button spec{.label = kit.textProp("label")}; + spec.icon = kit.onceText("icon"); + spec.emphasis = emphasisNamed(node.name("emphasis")).value_or(ButtonEmphasis::Normal); + if (node.name("style") == "item") { + spec.style = ButtonStyle::Item; + } + spec.shape = shapeNamed(node.name("shape")).value_or(ControlShape::Default); + spec.size = sizeNamed(node.name("size")).value_or(ButtonSize::Normal); + spec.mono = node.flag("mono"); + spec.weight = weightNamed(node.name("weight")).value_or(0); + if (node.prop("selected")) { + spec.selected = bindProp(ctx, node.prop("selected"), false, boolOf); + // An entry's content, drawn in place of its label: one node as it is, several in a column. + if (std::vector content = kit.children("children"); content.size() == 1) { + spec.child = std::move(content.front()); + } else if (!content.empty()) { + spec.child = ui::column(Column{.children = std::move(content)}); + } + } + Commands const* const onClick = node.event("onClick"); + Commands const* const onActivate = node.event("onActivate"); + if (onClick != nullptr || onActivate != nullptr) { + spec.onClick = [this, ctx, onClick, onActivate] { + runEvent(onClick, ctx, Value{}); + runEvent(onActivate, ctx, Value{}); + }; + } + commonOf(node, ctx, element, spec.common); + return ui::button(std::move(spec)); + } + if (kind == "textInput") { + std::string const commitOn = node.name("commitOn").empty() ? "change" : std::string{node.name("commitOn")}; + auto commit = [this, ctx, element, commitOn, onChange = node.event("onChange")](std::string const& when, + std::string const& text) { + if (commitOn != when) { + return; + } + if (element->bound == nullptr) { + session.noteWrite(); + element->committed.set(Value{text}); + } + runEvent(onChange, ctx, Value{text}); + }; + TextInput spec; + spec.value = + slotProp([this, element] { return textOf(element->draft.get(), session.formatting()); }); + spec.onChange = [this, element, commit](std::string text) { + session.asUser([&] { + session.noteWrite(); + element->draft.set(Value{text}); + element->edited.set(true); + }); + commit("change", text); + }; + spec.onCommit = [this, ctx, element, commit, onCommit = node.event("onCommit")](std::string const& text) { + element->touched.set(true); + commit("blur", text); + runEvent(onCommit, ctx, Value{text}); + }; + // Only a field that does something on Enter submits: one without `onSubmit` that does not commit on Enter + // lets Enter go on to its ancestors' chords, a dialog's `default` among them. + if (Commands const* const onSubmit = node.event("onSubmit"); onSubmit != nullptr || commitOn == "enter") { + spec.onSubmit = [this, ctx, commit, onSubmit](std::string const& text) { + commit("enter", text); + runEvent(onSubmit, ctx, Value{text}); + }; + } + spec.placeholder = kit.textProp("placeholder"); + std::string const mode = kit.onceText("mode"); + spec.mode = TextInputMode::SingleLine; + if (mode == "multiline") { + spec.mode = TextInputMode::Multiline; + } else if (mode == "password") { + spec.mode = TextInputMode::Password; + } + // A multiline input shows no unit and no icon; a computed mode that turns out multiline is reported and + // its unit and icon left out, so the mount never meets them there. The loader refuses a literal one. + for (std::string_view const key : {std::string_view{"unit"}, std::string_view{"icon"}, + std::string_view{"prefix"}, std::string_view{"decimals"}}) { + if (ExprPtr const given = node.prop(key); given != nullptr && spec.mode == TextInputMode::Multiline) { + report(given->path, "a multiline input shows no " + std::string{key}); + } + } + spec.mono = node.flag("mono"); + if (spec.mode != TextInputMode::Multiline) { + spec.emphasis = node.name("emphasis") == "prominent" ? InputEmphasis::Prominent : InputEmphasis::Normal; + spec.icon = kit.onceText("icon"); + spec.align = alignOf(node.name("align")); + if (spec.align == Align::Stretch) { + spec.align = Align::Start; + } + if (node.prop("unit")) { + spec.unit = kit.textProp("unit"); + } + if (node.prop("prefix")) { + spec.prefix = kit.textProp("prefix"); + } + if (ExprPtr const places = node.prop("decimals")) { + spec.decimals = bindProp(ctx, places, -1, placesOf); + } + } + fieldOf(node, ctx, element, spec.field); + commonOf(node, ctx, element, spec.common); + kit.nameByLabel(spec.common); + kit.captionOf(spec); + return ui::textInput(std::move(spec)); + } + if (kind == "checkbox") { + Checkbox spec{.label = kit.textProp("label"), .checked = slotProp([read = kit.read("checked")] { + Value const value = read(); + bool const* const flag = value.asBool(); + return flag != nullptr && *flag; + })}; + spec.onToggle = [this, ctx, element, onToggle = node.event("onToggle"), + onChange = node.event("onChange")](bool checked) { + // A toggle is a check box's commit, so it touches the box. + session.asUser([&] { + if (element->bound == nullptr) { + session.noteWrite(); + element->draft.set(checked); + } + element->touched.set(true); + }); + runEvent(onToggle, ctx, Value{checked}); + runEvent(onChange, ctx, Value{checked}); + }; + fieldOf(node, ctx, element, spec.field); + commonOf(node, ctx, element, spec.common); + return ui::checkbox(std::move(spec)); + } + if (kind == "select") { + Select spec; + spec.options = slotProp>( + [scope = ctx.scope, element] { return selectOptions(element->rows->get(), scope->formatting()); }); + spec.selected = slotProp>([read = kit.read("selected")]() -> std::optional { + Value const selected = read(); + return selected.isNull() ? std::nullopt : std::optional{keyOf(selected)}; + }); + spec.onSelect = [this, ctx, element, onChoose = node.event("onChoose"), + onChange = node.event("onChange")](Key const& key) { + Value const chosen = valueOfKey(key); + // A choice is a select's commit, so it touches the select. + session.asUser([&] { + if (element->bound == nullptr) { + session.noteWrite(); + element->draft.set(chosen); + } + element->touched.set(true); + }); + runEvent(onChoose, ctx, chosen); + runEvent(onChange, ctx, chosen); + }; + // A computed style of no known name is reported once and drawn as a dropdown; the loader refuses a constant + // one. + if (ExprPtr const style = node.prop("style")) { + std::string const name = textOf(once(ctx, style), ctx.scope->formatting()); + if (name == "radio") { + spec.style = SelectStyle::Radio; + } else if (name == "segmented") { + spec.style = SelectStyle::Segmented; + } else if (name != "dropdown") { + report(style->path, "style is `" + name + "`; a select's style is dropdown, radio or segmented"); + } + } + fieldOf(node, ctx, element, spec.field); + commonOf(node, ctx, element, spec.common); + kit.nameByLabel(spec.common); + kit.captionOf(spec); + return ui::select(std::move(spec)); + } + if (kind == "slider") { + Slider spec; + spec.value = slotProp([read = kit.read("value"), element] { + return intOf(element->bound != nullptr ? read() : element->draft.get(), 0); + }); + spec.minimum = kit.onceInt("min", 0); + spec.maximum = kit.onceInt("max", 100); + spec.step = kit.onceInt("step", 1); + spec.onChange = [this, ctx, element, onChange = node.event("onChange")](std::int64_t value) { + session.asUser([&] { + session.noteWrite(); + element->draft.set(value); + element->edited.set(true); + if (element->bound == nullptr) { + element->committed.set(value); + } + }); + runEvent(onChange, ctx, Value{value}); + }; + spec.onCommit = [this, ctx, element, onCommit = node.event("onCommit")](std::int64_t value) { + element->touched.set(true); + runEvent(onCommit, ctx, Value{value}); + }; + fieldOf(node, ctx, element, spec.field); + commonOf(node, ctx, element, spec.common); + kit.nameByLabel(spec.common); + return ui::slider(std::move(spec)); + } + if (kind == "dateTimeInput") { + DateTimeInput spec; + DateMode const mode = kit.onceText("mode") == "date" ? DateMode::Date : DateMode::DateTime; + std::optional heldAtLoad; + if (auto const found = _doc->dateValueKinds.find(&node); found != _doc->dateValueKinds.end()) { + heldAtLoad = found->second; + } + std::string const valuePath = pointerAppend(node.path, "value"); + std::int32_t const offsetMinutes = format.utcOffsetMinutes; + spec.value = slotProp>([this, element, offsetMinutes, + valuePath]() -> std::optional { + DateReading const reading = dateInstantOf(element->draft.get(), offsetMinutes); + if (!reading.readable) { + report(valuePath, "`dateTimeInput` shows a timestamp or an ISO-8601 date or date-time string"); + } + return reading.instant ? std::optional{time::Timestamp{*reading.instant}} : std::nullopt; + }); + spec.onChange = [this, ctx, element, heldAtLoad, mode, offsetMinutes, onChange = node.event("onChange"), + onCommit = node.event("onCommit")](std::optional value) { + bool asString = element->bound != nullptr && element->bound->get().asString() != nullptr; + if (heldAtLoad) { + asString = *heldAtLoad == TypeKind::String; + } + std::optional const instant = value ? value->value : std::nullopt; + Value entered; + if (!asString) { + if (instant) { + entered = Value{*instant}; + } + } else if (!instant) { + entered = Value{std::string{}}; + } else if (mode == DateMode::Date) { + entered = Value{dateTextOf(*instant, offsetMinutes)}; + } else { + entered = Value{instant->toIso8601()}; + } + element->touched.set(true); + session.asUser([&] { + session.noteWrite(); + element->draft.set(entered); + element->edited.set(true); + if (element->bound == nullptr) { + element->committed.set(entered); + } + }); + runEvent(onChange, ctx, entered); + runEvent(onCommit, ctx, entered); + }; + spec.mode = mode; + spec.offsetMinutes = offsetMinutes; + // Tracked: a locale switch changes the pattern the screen's dates are written in, and the input follows. + spec.pattern = slotProp([this, mode] { + FormatContext const& now = session.formatting(); + return mode == DateMode::Date ? now.datePattern : now.dateTimePattern; + }); + fieldOf(node, ctx, element, spec.field); + commonOf(node, ctx, element, spec.common); + kit.nameByLabel(spec.common); + kit.captionOf(spec); + return ui::dateTimeInput(std::move(spec)); + } + if (kind == "filePicker") { + FilePicker spec; + spec.path = + slotProp([this, element] { return textOf(element->draft.get(), session.formatting()); }); + spec.onPicked = [this, ctx, element, onPick = node.event("onPick")](std::string path) { + session.asUser([&] { + session.noteWrite(); + element->draft.set(Value{path}); + element->committed.set(Value{path}); + }); + runEvent(onPick, ctx, Value{path}); + }; + spec.mode = kit.onceText("mode") == "save" ? FilePickerMode::Save : FilePickerMode::Open; + fieldOf(node, ctx, element, spec.field); + commonOf(node, ctx, element, spec.common); + kit.nameByLabel(spec.common); + return ui::filePicker(std::move(spec)); + } + if (kind == "menu") { + Menu spec{.items = menuItems(node.partList("items"), ctx)}; + if (node.name("style") == "button") { + spec.style = MenuStyle::Button; + spec.label = kit.textProp("label"); + spec.icon = kit.onceText("icon"); + if (node.name("emphasis") == "primary") { + spec.emphasis = ButtonEmphasis::Primary; + } else if (node.name("emphasis") == "danger") { + spec.emphasis = ButtonEmphasis::Danger; + } else if (node.name("emphasis") == "ghost") { + spec.emphasis = ButtonEmphasis::Ghost; + } + } + commonOf(node, ctx, element, spec.common); + return ui::menu(std::move(spec)); + } + return std::nullopt; +} + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of ui/1. +std::optional ScreenCore::lowerDisplay(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + std::string_view const kind = node.kind; + KindKit const kit{*this, node, ctx, element}; + if (kind == "banner") { + Banner spec{.tone = bindProp(ctx, node.prop("tone"), Tone::Info, toneOf)}; + if (ExprPtr const spans = node.prop("spans")) { + spec.spans = spansProp(ctx, spans); + } else { + spec.text = kit.textProp("text"); + } + spec.action = kit.actionPart(); + spec.dismissible = kit.onceBool("dismissible", false); + spec.onDismiss = kit.action("onDismiss"); + spec.actionStyle = bannerActionStyleNamed(node.name("actionStyle")).value_or(BannerActionStyle::Ghost); + spec.actionStretch = node.flag("actionStretch"); + commonOf(node, ctx, element, spec.common); + return ui::banner(std::move(spec)); + } + if (kind == "badge") { + Badge spec{.tone = bindProp(ctx, node.prop("tone"), Tone::Neutral, toneOf), + .text = kit.textProp("text")}; + spec.icon = kit.onceText("icon"); + std::string_view const style = node.name("style"); + spec.style = BadgeStyle::Filled; + if (style == "outline") { + spec.style = BadgeStyle::Outline; + } else if (style == "quiet") { + spec.style = BadgeStyle::Quiet; + } + spec.shape = shapeNamed(node.name("shape")).value_or(ControlShape::Default); + spec.mono = node.flag("mono"); + if (Commands const* const onRemove = node.event("onRemove")) { + spec.onRemove = [this, ctx, onRemove] { runEvent(onRemove, ctx, Value{}); }; + spec.removeLabel = kit.textProp("removeLabel"); + } + commonOf(node, ctx, element, spec.common); + return ui::badge(std::move(spec)); + } + if (kind == "progress") { + Progress spec; + spec.value = slotProp>( + [scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("value")]() -> std::optional { + Value const value = evalIn(*scope, bindings.get(), expr); + if (std::int64_t const* const number = value.asInt()) { + return static_cast(*number); + } + if (Decimal const* const number = value.asDecimal()) { + return realOf(number->value); + } + return std::nullopt; + }); + spec.label = kit.textProp("label"); + commonOf(node, ctx, element, spec.common); + return ui::progress(std::move(spec)); + } + if (kind == "steps") { + Steps spec; + spec.items = + slotProp>([scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("items")] { + std::vector steps; + Value const items = evalIn(*scope, bindings.get(), expr); + if (ValueList const* const list = items.asList()) { + for (Value const& item : *list) { + Value const* const label = item.field("label"); + Value const* const state = item.field("state"); + Value const* const detail = item.field("detail"); + std::string const name = state == nullptr ? std::string{} : textOf(*state, {}); + steps.push_back( + Step{.label = label == nullptr ? std::string{} : textOf(*label, scope->formatting()), + .state = stepStateOf(name), + .detail = detail == nullptr ? std::string{} : textOf(*detail, scope->formatting())}); + } + } + return steps; + }); + spec.current = slotProp>( + [scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("current")]() -> std::optional { + std::int64_t const index = intOf(evalIn(*scope, bindings.get(), expr), -1); + return index < 0 ? std::nullopt : std::optional{static_cast(index)}; + }); + spec.labelled = bindProp(ctx, node.prop("labelled"), true, boolOf); + commonOf(node, ctx, element, spec.common); + return ui::steps(std::move(spec)); + } + if (kind == "chart") { + return lowerChart(node, ctx, element); + } + if (kind == "keyValue") { + KeyValue spec; + spec.captions = node.name("fieldLayout") == "stacked" ? CaptionPlacement::Above : CaptionPlacement::Beside; + // The loader has checked `captionWidth` is a literal integer. + if (ExprPtr const width = node.prop("captionWidth")) { + spec.captionWidth = static_cast(*width->literal.asInt()); + } + spec.items = slotProp>( + [this, scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("items")] { + std::vector out; + Value const items = evalIn(*scope, bindings.get(), expr); + if (ValueList const* const list = items.asList()) { + for (Value const& item : *list) { + out.push_back(keyValueItemOf(item, expr->path, *scope)); + } + } + return out; + }); + commonOf(node, ctx, element, spec.common); + return ui::keyValue(std::move(spec)); + } + if (kind == "emptyState") { + EmptyState spec{.title = kit.textProp("title"), .text = kit.textProp("text")}; + spec.icon = kit.onceText("icon"); + spec.action = kit.actionPart(); + commonOf(node, ctx, element, spec.common); + return ui::emptyState(std::move(spec)); + } + return std::nullopt; +} + +Node ScreenCore::lowerStack(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + std::string_view const kind = node.kind; + KindKit const kit{*this, node, ctx, element}; + int const gap = static_cast(kit.onceInt("gap", 0)); + if (std::string const arrangement = arrangedBy(node.id); !arrangement.empty()) { + return lowerArranged(node, ctx, element, arrangement, kind == "column" ? Axis::Vertical : Axis::Horizontal, + gap); + } + if (kind == "column") { + Column spec{.children = kit.children("children", gap), + .gap = gap, + .align = alignOf(node.name("align")), + .justify = justifyOf(node.name("justify")), + .divided = node.flag("divided"), + .padding = kit.stackPadding()}; + if (node.prop("selected")) { + spec.selected = bindProp(ctx, node.prop("selected"), false, boolOf); + } + commonOf(node, ctx, element, spec.common); + return ui::column(std::move(spec)); + } + Row spec{.children = kit.children("children"), + .gap = gap, + .align = alignOf(node.name("align")), + .justify = justifyOf(node.name("justify")), + .wrap = node.flag("wrap"), + .divided = node.flag("divided"), + .padding = kit.stackPadding()}; + if (node.prop("selected")) { + spec.selected = bindProp(ctx, node.prop("selected"), false, boolOf); + } + commonOf(node, ctx, element, spec.common); + return ui::row(std::move(spec)); +} + +Node ScreenCore::lowerGrid(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + KindKit const kit{*this, node, ctx, element}; + Grid spec{.columns = static_cast(kit.onceInt("columns", 1)), + .gap = static_cast(kit.onceInt("gap", 0)), + .align = alignOf(node.name("align")), + .minColumnWidth = static_cast(kit.onceInt("minColumnWidth", 0))}; + for (DocNodePtr const& track : node.partList("tracks")) { + ExprPtr const width = track->prop("width"); + spec.tracks.push_back(GridTrack{.width = width ? sizingOf(once(ctx, width)) : Sizing::stretch(), + .align = cellPlaceNamed(track->name("align")).value_or(Align::Start)}); + } + for (DocNodePtr const& cell : node.nodes("children")) { + ExprPtr const span = cell->prop("span"); + spec.cells.push_back( + GridCell{.node = lower(*cell, ctx), .span = static_cast(span ? intOf(once(ctx, span), 1) : 1)}); + } + commonOf(node, ctx, element, spec.common); + return ui::grid(std::move(spec)); +} + +Node ScreenCore::lowerPanel(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + KindKit const kit{*this, node, ctx, element}; + Panel spec{.title = kit.textProp("title"), .padding = static_cast(kit.onceInt("padding", 0))}; + spec.header = kit.child("header"); + spec.child = kit.child("children", static_cast(kit.onceInt("gap", kPanelGap))); + spec.collapsible = kit.onceBool("collapsible", false); + spec.collapsed = bindProp(ctx, node.prop("collapsed"), false, boolOf); + if (Commands const* const commands = node.event("onToggle")) { + spec.onToggle = [this, ctx, commands](bool collapsed) { runEvent(commands, ctx, Value{collapsed}); }; + } + commonOf(node, ctx, element, spec.common); + return ui::panel(std::move(spec)); +} + +Node ScreenCore::lowerSplitter(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + KindKit const kit{*this, node, ctx, element}; + ExprPtr const orientation = node.prop("orientation"); + Splitter spec{.children = kit.children("children"), + .orientation = orientation && axisOf(once(ctx, orientation)) == Axis::Vertical ? Axis::Vertical + : Axis::Horizontal}; + // No `onResize`: a user's drag stays the splitter's own, and the document's sizes are where it starts. + if (ExprPtr const sizes = node.prop("sizes")) { + spec.sizes = bindProp>( + ctx, sizes, {}, [this, path = sizes->path](Value const& value, FormatContext const& /*format*/) { + std::optional> parsed = splitterSizesOf(value); + if (!parsed) { + report(path, "sizes is " + canonicalJson(value) + "; sizes is a list of numbers, one per pane"); + } + return std::move(parsed).value_or(std::vector{}); + }); + } + commonOf(node, ctx, element, spec.common); + // A literal `sizes` that matches the panes places them, so a pane's own width is not used. + if (ExprPtr const sizes = node.prop("sizes"); sizes && sizes->kind == ExprKind::Literal) { + std::optional> const given = splitterSizesOf(sizes->literal); + if (given && given->size() == spec.children.size()) { + for (std::size_t at = 0; at < spec.children.size(); ++at) { + // A stretch pane asks only to fill, which `sizes` leaves it to do; a fixed or percent pane names a + // size. + Sizing::Kind const kind = layoutHintsOf(spec.children.at(at)).width.kind; + if (spec.orientation == Axis::Horizontal && + (kind == Sizing::Kind::Fixed || kind == Sizing::Kind::Percent)) { + report(sizes->path, "this splitter's `sizes` places its panes; pane " + std::to_string(at) + + "'s sizing is not used"); + } + } + } + } + return ui::splitter(std::move(spec)); +} + +void ScreenCore::reportActionBarGaps(DocNode const& bar, LowerCtx const& ctx) { + for (DocNodePtr const& child : bar.nodes("children")) { + if (child->kind != "forEach" || child->prop("gap") == nullptr) { + continue; + } + ExprPtr const axis = child->prop("axis"); + if (axis != nullptr && axis->kind != ExprKind::Literal && axisOf(once(ctx, axis)) == Axis::Horizontal) { + report(child->path + "/gap", kActionBarGapRefusal); + } + } +} + +Node ScreenCore::lowerCollapsible(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + KindKit const kit{*this, node, ctx, element}; + Collapsible spec{.title = kit.textProp("title"), .open = bindProp(ctx, node.prop("open"), true, boolOf)}; + if (Commands const* const commands = node.event("onToggle")) { + spec.onToggle = [this, ctx, commands](bool open) { runEvent(commands, ctx, Value{open}); }; + } + spec.header = kit.child("header"); + spec.child = kit.child("children", static_cast(kit.onceInt("gap", kPanelGap))); + commonOf(node, ctx, element, spec.common); + return ui::collapsible(std::move(spec)); +} + +Node ScreenCore::lowerDropZone(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + KindKit const kit{*this, node, ctx, element}; + DropZone spec; + spec.accept = stringsOf(node.prop("accept") ? once(ctx, node.prop("accept")) : Value{}); + spec.multiple = kit.onceBool("multiple", false); + if (Commands const* const commands = node.event("onDrop")) { + spec.onDrop = [this, ctx, commands](std::vector const& paths) { + runEvent(commands, ctx, listOfStrings(paths)); + }; + } + spec.child = kit.child("children"); + commonOf(node, ctx, element, spec.common); + return ui::dropZone(std::move(spec)); +} + +Node ScreenCore::lowerPage(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + KindKit const kit{*this, node, ctx, element}; + Page spec; + spec.geometry = pageGeometryOf(node); + std::optional const outer = std::exchange(pageBeingLowered, spec.geometry); + spec.children = kit.children("children"); + pageBeingLowered = outer; + commonOf(node, ctx, element, spec.common); + return ui::page(std::move(spec)); +} + +Node ScreenCore::lowerPageRegion(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + if (!pageBeingLowered) { + report(node.path, "a page region belongs in a page"); + return ui::text(Text{.text = std::string{}, .role = TextRole::Muted}); + } + KindKit const kit{*this, node, ctx, element}; + PageRegion spec; + spec.geometry = regionGeometryOf(node, *pageBeingLowered); + std::optional const outer = std::exchange(pageBeingLowered, std::nullopt); + spec.children = kit.children("children"); + pageBeingLowered = outer; + commonOf(node, ctx, element, spec.common); + return ui::pageRegion(std::move(spec)); +} + +Node ScreenCore::lowerLocaleScope(DocNode const& node, LowerCtx const& ctx) { + auto holder = std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); + holder->transparent = true; + ExprPtr const locale = node.prop("locale"); + holder->localeFormat = &holder->nodes.computed([this, scope = ctx.scope, bindings = ctx.bindings, + locale]() -> std::shared_ptr { + Value const value = evalIn(*scope, bindings.get(), locale); + std::string const* const tag = value.asString(); + if (tag == nullptr && !value.isNull()) { + report(locale->path, "the locale is " + canonicalJson(value) + "; a locale is a BCP 47 tag, a string"); + } + if (tag == nullptr || tag->empty()) { + return session.sharedFormatting(); + } + if (session.firstUnlistedLocale(*tag)) { + report(locale->path, "no formatting facts for locale `" + *tag + "`; numbers, money and dates use en's"); + } + return session.scopedFormatting(*tag); + }); + // The children are mounted again whenever the tag changes: a value a node reads once, as it is lowered (a + // table's column labels, a `once` property, a literal), is written in the facts at that moment, and only a new + // lowering writes it in the new ones. The key is the tag as the scope resolves it; a tag that is not known yet + // is the key `""`, apart from every tag. + std::vector content; + for (DocNodePtr const& child : node.nodes("children")) { + content.push_back(child.get()); + } + LayoutHints const hints = holderHints(content, nullptr, ctx); + Switch spec; + spec.selector = slotProp([scope = ctx.scope, bindings = ctx.bindings, locale] { + Value const value = evalIn(*scope, bindings.get(), locale); + std::string const* const tag = value.asString(); + return Key{tag == nullptr ? std::string{} : *tag}; + }); + spec.fallback = lazy( + [this, ctx, holder, content, path = node.path]() -> Node { + auto inner = std::make_shared(*this, holder, nullptr, holder->nodes.depth() + 2); + inner->transparent = true; + LowerCtx const innerCtx{.scope = inner, .bindings = ctx.bindings, .boundary = ctx.boundary, .listGap = 0}; + std::vector children; + children.reserve(content.size()); + for (DocNode const* const child : content) { + children.push_back(lower(*child, innerCtx)); + } + fillHolder(children, path); + return holding(std::move(children), inner, {}, 0); + }, + hints); + commonOf(node, ctx, nullptr, spec.common); + return ui::switchOf(std::move(spec)); +} + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of ui/1. +Node ScreenCore::lowerKind(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + std::string_view const kind = node.kind; + KindKit const kit{*this, node, ctx, element}; + if (std::optional widget = lowerWidget(node, ctx, element)) { + return std::move(*widget); + } + if (kind == "group") { + return lowerGroup(node, ctx, element, kit.children("children")); + } + if (kind == "column" || kind == "row") { + return lowerStack(node, ctx, element); + } + if (kind == "grid") { + return lowerGrid(node, ctx, element); + } + if (kind == "spacer") { + Spacer spec; + commonOf(node, ctx, element, spec.common); + return ui::spacer(std::move(spec)); + } + if (kind == "panel") { + return lowerPanel(node, ctx, element); + } + if (kind == "scroll") { + ExprPtr const axis = node.prop("axis"); + Scroll spec{.child = kit.child("children"), .axis = axis ? axisOf(once(ctx, axis)) : Axis::Vertical}; + commonOf(node, ctx, element, spec.common); + return ui::scroll(std::move(spec)); + } + if (kind == "switch") { + return lowerSwitch(node, ctx); + } + if (kind == "tabs") { + return lowerTabs(node, ctx, element); + } + if (kind == "dialog" || kind == "drawer") { + return lowerDialog(node, ctx, element); + } + if (kind == "busy") { + Busy spec{.active = bindProp(ctx, node.prop("active"), false, boolOf), .label = kit.textProp("label")}; + commonOf(node, ctx, element, spec.common); + return ui::busy(std::move(spec)); + } + if (kind == "forEach" || kind == "table") { + return lowerRows(node, ctx, element); + } + if (std::optional display = lowerDisplay(node, ctx, element)) { + return std::move(*display); + } + if (kind == "splitter") { + return lowerSplitter(node, ctx, element); + } + if (kind == "collapsible") { + return lowerCollapsible(node, ctx, element); + } + if (kind == "dropZone") { + return lowerDropZone(node, ctx, element); + } + if (kind == "actionBar") { + KindKit const bar{*this, node, ctx, element}; + ActionBar spec{.children = bar.children("children"), + .align = alignOf(node.name("align")), + .justify = justifyOf(node.name("justify")), + .wrap = node.flag("wrap")}; + reportActionBarGaps(node, ctx); + commonOf(node, ctx, element, spec.common); + return ui::actionBar(std::move(spec)); + } + if (kind == "page") { + return lowerPage(node, ctx, element); + } + if (kind == "pageRegion") { + return lowerPageRegion(node, ctx, element); + } + if (kind == "localeScope") { + return lowerLocaleScope(node, ctx); + } + if (kind == "boundary") { + return lowerBoundary(node, ctx); + } + if (kind == "custom") { + return lowerCustom(node, ctx); + } + if (kind == "customize") { + return lowerCustomize(node, ctx); + } + if (kind == "form") { + return lowerForm(node, ctx, element); + } + if (kind == "collection" || kind == "wizard") { + return lowerComposite(node, ctx, element); + } + report(node.path, "`" + node.kind + "` is a node kind this interpreter does not lower"); + return ui::text(Text{.text = std::string{node.kind}, .role = TextRole::Muted}); +} +namespace { + +/// @brief A document field overlay's expressions, evaluated once, as the engine's overlay. +/// @param scope The scope the form is declared in. +/// @param part The `fields` entry. +/// @param format How values read as text and numbers. +/// @return The overlay. +[[nodiscard]] forms::FieldOverlay overlayOf(RtScope const& scope, DocNode const& part, FormatContext const& format) { + auto const read = [&](std::string_view key) -> std::optional { + ExprPtr const expr = part.prop(key); + if (!expr) { + return std::nullopt; + } + return scope.core.runtime().untracked([&] { return evalIn(scope, nullptr, expr); }); + }; + auto const text = [&](std::string_view key) -> std::optional { + auto const value = read(key); + return value.has_value() && !value->isNull() ? std::optional{textOf(*value, format)} + : std::nullopt; + }; + auto const flag = [&](std::string_view key) { + auto const value = read(key); + bool const* const set = value.has_value() ? value->asBool() : nullptr; + return set != nullptr && *set; + }; + forms::FieldOverlay overlay{.omit = flag("omit"), .hidden = flag("hidden")}; + overlay.label = text("label"); + overlay.unit = text("unit"); + overlay.widget = text("widget"); + if (auto const decimals = read("decimals"); + decimals.has_value() && decimals->asInt() != nullptr && *decimals->asInt() >= 0) { + overlay.decimals = static_cast(std::min(*decimals->asInt(), 18)); + } + if (auto const blankAs = text("blankAs")) { + overlay.blankAs = *blankAs == "empty" ? forms::BlankAs::Empty : forms::BlankAs::Omit; + } + return overlay; +} + +/// @brief A lowering context whose scope is held weakly: what an Effect the scope itself owns may keep, so the scope +/// does not keep itself alive. +struct DetachedLower { + /// @brief The scope, weakly. + std::weak_ptr scope; + /// @brief The names bound there. + std::shared_ptr bindings; + /// @brief The innermost boundary. + std::shared_ptr boundary; +}; + +/// @brief Detaches a lowering context's scope. +/// @param ctx The context. +/// @return The context, its scope held weakly. +[[nodiscard]] DetachedLower detachedLower(LowerCtx const& ctx) { + return DetachedLower{.scope = ctx.scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; +} + +/// @brief Puts a detached context's scope back. +/// @param held The detached context. +/// @return The context; its scope is null once the scope is gone. +[[nodiscard]] LowerCtx attached(DetachedLower const& held) { + return LowerCtx{.scope = held.scope.lock(), .bindings = held.bindings, .boundary = held.boundary}; +} +} // namespace + +// Builds the form's session when its element is declared, so its values can be read before the form is drawn. +void ScreenCore::wireForm(ElementState& element) { + DocNode const& node = *element.node; + RtScope& scope = *element.scope; + std::string const action{node.name("action")}; + Catalog const& catalog = session.options().catalog; + std::optional const schema = catalog.schema ? catalog.schema(action) : std::nullopt; + if (!schema.has_value()) { + report(node.path, "no schema for `" + action + "`: the catalog has none for a `form` to build from"); + return; + } + NameRef const* const alias = scope.find(node.name("model")); + if (alias == nullptr || alias->model == nullptr) { + report(node.path, "`" + std::string{node.name("model")} + "` is not a model alias"); + return; + } + forms::FieldOverlays overlays; + // `fields` is one record part holding a `field` part per overlaid member. + for (DocNodePtr const& record : node.partList("fields")) { + for (DocNodePtr const& part : record->partList("fields")) { + forms::FieldOverlay overlay = overlayOf(scope, *part, session.formatting()); + // A computed `decimals` is carried by the effect below alone: baking the value read now would make it + // the fallback when the expression later gives no places, where the schema's places belong. + if (ExprPtr const places = part->prop("decimals"); places && places->kind != ExprKind::Literal) { + overlay.decimals.reset(); + } + overlays.insert_or_assign(part->id, std::move(overlay)); + } + } + auto model = forms::FormModel::fromSchema(action, *schema, overlays); + if (!model) { + report(node.path, + "the form of `" + action + "` does not build: " + model.error().path + ": " + model.error().message); + return; + } + if (node.name("submit") == "explicit") { + model = model->withSubmitMode(forms::SubmitMode::Explicit); + } else if (node.name("submit") == "auto") { + model = model->withSubmitMode(forms::SubmitMode::Automatic); + } + element.form = std::make_unique(runtime(), *std::move(model), aliasSubmits(alias->model), + aliasCalls(alias->model), engineOptions()); + // An overlay's `decimals` follows its expression: the field keeps the draft as typed and checks it again against + // the places the expression gives now. + for (DocNodePtr const& record : node.partList("fields")) { + for (DocNodePtr const& part : record->partList("fields")) { + ExprPtr const places = part->prop("decimals"); + if (!places) { + continue; + } + forms::FieldState* state = nullptr; + try { + state = &element.form->field(part->id); + } catch (std::out_of_range const&) { + continue; // The overlay names a field the form does not have (an omitted one). + } + scope.nodes.effect([this, &scope, places, state] { + int const now = placesOf(evalIn(scope, nullptr, places), session.formatting()); + runtime().untracked([&] { + state->places().set(now >= 0 ? std::optional{static_cast(now)} + : std::nullopt); + }); + }); + } + } + if (ExprPtr const prefill = node.prop("prefill")) { + // A prefill follows its expression. A value of the record being edited (the first value, or one under the + // same `key`) keeps the fields the user changed; another record, a new `key`, or any later value of a form + // without one, loads every field. + forms::FormSession* const form = element.form.get(); + struct Followed { + bool loaded = false; + Value key; + }; + auto const followed = std::make_shared(); + scope.nodes.effect([this, &scope, prefill, key = node.prop("key"), form, followed] { + Value const value = evalIn(scope, nullptr, prefill); + if (value.isNull()) { + return; + } + runtime().untracked([&] { + Value const current = key ? evalIn(scope, nullptr, key) : Value{}; + bool const same = !followed->loaded || (key && current == followed->key); + followed->loaded = true; + followed->key = current; + std::string const json = glz::write_json(valueToJson(value)).value_or(std::string{}); + if (same) { + form->refill(json); + } else { + form->prefill(json); + } + }); + }); + } +} + +Node ScreenCore::lowerForm(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + forms::FormSession* const form = element == nullptr ? nullptr : element->form.get(); + if (form == nullptr) { + return ui::text(Text{.text = std::string{node.name("action")}, .role = TextRole::Muted}); + } + // The form's events, each run once per change of the count it watches. + auto const watch = [this, &ctx](Commands const* commands, auto count, auto payload) { + if (commands == nullptr || commands->empty()) { + return; + } + auto const seen = std::make_shared(runtime().untracked(count)); + ctx.scope->nodes.effect([this, held = detachedLower(ctx), commands, count, payload, seen] { + std::uint64_t const now = count(); + if (now == *seen) { + return; + } + *seen = now; + runtime().untracked([&] { runEvent(commands, attached(held), payload()); }); + }); + }; + watch( + node.event("onSubmit"), [form] { return form->submitAttempts(); }, + [form] { + std::optional const body = form->body(); + return body.has_value() ? jsonTextValue(*body) : Value{}; + }); + watch( + node.event("onSuccess"), [form] { return form->successCount(); }, + [form] { + std::optional const& reply = form->lastReply(); + return reply.has_value() ? jsonTextValue(*reply) : Value{}; + }); + if (Commands const* const onError = node.event("onError"); onError != nullptr && !onError->empty()) { + // Each failure is a new exception: run once per failure, with its text. + auto const seen = + std::make_shared(runtime().untracked([form] { return form->lastError(); })); + ctx.scope->nodes.effect([this, held = detachedLower(ctx), onError, form, seen] { + std::exception_ptr const error = form->lastError(); + if (error == nullptr || error == *seen) { + return; + } + *seen = error; + runtime().untracked([&] { runEvent(onError, attached(held), Value{failureText(error)}); }); + }); + } + forms::FormViewOptions options{.showTitle = false}; + presentForm(node, ctx, options); + options.title = bindProp(ctx, node.prop("title"), std::string{}, stringOf); + // A field whose overlay names a component is drawn by it; only top-level fields take one, as every overlay. + for (DocNodePtr const& record : node.partList("fields")) { + for (DocNodePtr const& overlay : record->partList("fields")) { + if (!overlay->name("component").empty()) { + options.overrides.byField(overlay->id, + [this, ctx, field = overlay.get()](forms::FieldView const& view) { + return fieldComponent(view, *field, ctx); + }); + } + } + } + Column column{.children = {forms::formView(*form, std::move(options))}}; + commonOf(node, ctx, element, column.common); + return ui::column(std::move(column)); +} + +[[nodiscard]] std::expected changeWire(std::string const& payload, + std::string_view type) { + std::string_view text{payload}; + if (type == "string") { + if (text.starts_with("s:")) { + text.remove_prefix(2); + } + // Parentheses: braces would pick the initializer-list constructor and make a one-element array. + return forms::detail::engine::Json(std::string{text}); + } + if (text.starts_with("i:")) { + text.remove_prefix(2); + } + std::optional json = forms::detail::engine::parseJson(text); + if (!json) { + return std::unexpected(std::string{"it is not JSON"}); + } + bool const fits = type == "json" || json->is_null() || (type == "bool" && json->is_boolean()) || + ((type == "int" || type == "number") && json->is_number()) || + (type == "exact" && (json->is_number() || json->is_string())); + if (!fits) { + bool const vowel = type == "int" || type == "exact"; + return std::unexpected("it is not " + std::string{vowel ? "an " : "a "} + std::string{type}); + } + return *std::move(json); +} +namespace { + +/// @brief What a form fills of a field component's props: the field's value, errors, read-only and required state, +/// and label, each a tracked read of the field. +/// @param prop The prop's name. +/// @param state The field. +/// @return The read, or empty for a prop the form does not fill. +[[nodiscard]] std::function formFilled(std::string const& prop, forms::FieldState* state) { + if (prop == "value") { + return [state] { + forms::Encoding const& encoding = state->encoded().get(); + if (!encoding.has_value() || !encoding->has_value()) { + return Value{}; + } + return (*encoding)->value.isNull() ? jsonTextValue((*encoding)->json) : (*encoding)->value; + }; + } + if (prop == "errors") { + return [state] { + std::optional const& error = state->error().get(); + return error.has_value() ? Value{ValueList{Value{error->message}}} : Value{ValueList{}}; + }; + } + if (prop == "readonly") { + return [state] { return Value{state->readonly().get()}; }; + } + if (prop == "required") { + return [state] { return Value{state->required().get()}; }; + } + if (prop == "label") { + return [state] { return Value{state->label()}; }; + } + return {}; +} +} // namespace + +// NOLINTNEXTLINE(bugprone-easily-swappable-parameters): a prop's name, then its declared type. +CustomProp ScreenCore::componentProp(std::string const& prop, std::string const& type, std::function read) { + if (type == "bool") { + return CustomProp{.name = prop, .value = slotProp([this, read = std::move(read)] { + return boolOf(read(), session.formatting()); + })}; + } + if (type == "number") { + return CustomProp{.name = prop, + .value = slotProp([read = std::move(read)] { return componentNumber(read()); })}; + } + return CustomProp{.name = prop, .value = slotProp([this, read = std::move(read), type] { + return componentText(read(), type, session.formatting()); + })}; +} + +void ScreenCore::changeField(forms::FieldState& state, forms::FieldSpec const& spec, std::string const& path, + std::string_view valueType, std::string const& payload) { + auto wire = changeWire(payload, valueType); + // A base64 member holds a file's bytes, which a document moves inline only under the session's cap. + if (std::size_t const cap = session.options().maxInlineFileBytes; + wire && spec.bytes && wire->is_string() && base64Size(wire->get_string()) > cap) { + report(path, "field " + spec.name + ": " + std::to_string(base64Size(wire->get_string())) + + " bytes is over the " + std::to_string(cap) + " inline cap"); + return; + } + if (wire) { + if (auto edited = state.edit(*wire); !edited) { + wire = std::unexpected(edited.error()); + } + } + if (!wire) { + report(path, "field " + spec.name + ": the component's change does not decode: " + wire.error()); + } +} + +Node ScreenCore::fieldComponent(forms::FieldView const& view, DocNode const& overlay, LowerCtx const& ctx) { + std::string const name{overlay.name("component")}; + // A loaded document's field component is declared, with a `value` prop and a `change` event. + Component const& component = _doc->components.at(name); + forms::FieldState* const state = &view.state(); + Custom spec{.name = name, + .fallback = view.defaultControl(), + .props = {}, + .minVersion = + static_cast(std::clamp(component.version, 0, std::numeric_limits::max())), + .onEvent = {}}; + for (auto const& [prop, type] : component.props) { + if (prop == "value" && type == "json") { + // The wire JSON itself, so an object's or a collection's every digit reaches the component. + spec.props.push_back(CustomProp{.name = prop, .value = slotProp([state] { + forms::Encoding const& encoding = state->encoded().get(); + return encoding.has_value() && encoding->has_value() + ? (*encoding)->json + : std::string{"null"}; + })}); + continue; + } + std::function read = formFilled(prop, state); + if (!read) { + ExprPtr given; + for (DocNodePtr const& record : overlay.partList("props")) { + if (ExprPtr const expr = record->prop(prop)) { + given = expr; + } + } + read = [scope = ctx.scope, bindings = ctx.bindings, given] { + return given ? evalIn(*scope, bindings.get(), given) : Value{}; + }; + } + spec.props.push_back(componentProp(prop, type, std::move(read))); + } + spec.onEvent = [this, state, path = overlay.path, fieldSpec = &view.spec(), + valueType = component.props.at("value")](std::string const& event, std::string const& payload) { + if (event == "change") { + changeField(*state, *fieldSpec, path, valueType, payload); + } + }; + return ui::custom(std::move(spec)); +} + +// Every call goes through the alias's channel, bound for its current instance when the call is made. +forms::Submitter ScreenCore::aliasCalls(ModelAlias* alias) { + return [this, alias](std::string_view actionId, std::string const& body) -> async::Completion { + std::shared_ptr const channel = channelOf(*alias, *this); + if (channel == nullptr) { + auto [failed, promise] = async::Completion::makeSettleable(&runtime().owner()); + promise.reject(std::make_exception_ptr(std::runtime_error{"the node's model alias is not bound"})); + return std::move(failed); + } + return channel->execute(std::string{actionId}, body, CallOptions{}); + }; +} + +// The calls of a form, collection or wizard: a success other than of @p read, the collection's own query, tells the +// session, which applies the action's effects, as a mutation's success does. +forms::Submitter ScreenCore::aliasSubmits(ModelAlias* alias, std::string read) { + return [this, alias, call = aliasCalls(alias), read = std::move(read)]( + std::string_view actionId, std::string body) -> async::Completion { + async::Completion completion = call(actionId, std::move(body)); + if (actionId != read) { + completion.then([this, alive = std::weak_ptr{_alive}, alias, typeId = alias->decl->type, + action = std::string{actionId}](std::string const& reply) { + if (alive.expired()) { + return; + } + auto json = parseJson(reply); + auto value = json ? valueFromJson(*json) : std::unexpected(json.error()); + std::string const token = runtime().untracked([&] { return alias->token->get(); }); + session.actionSucceeded(typeId, action, value ? *value : Value{}, ReplyUse::Applied, token); + }); + } + return completion; + }; +} + +// The session's locale, translations, display zone and date patterns, as every form the engine builds here reads them. +forms::FormSessionOptions ScreenCore::engineOptions() const { + FormatContext const& format = session.formatting(); + forms::FormSessionOptions options{}; + options.locale = withoutGrouping(format.numeric); + options.bcp47 = format.locale; + options.translations = format.translations; + options.displayOffsetMinutes = format.utcOffsetMinutes; + options.datePattern = format.datePattern; + options.dateTimePattern = format.dateTimePattern; + return options; +} + +// Builds a collection's or wizard's session when its element is declared. The node's `action` is the collection's +// query or the wizard's first step; the catalog answers the document for it, and every call (the query, the actions, +// every step's submission) goes through the node's model alias. +void ScreenCore::wireComposite(ElementState& element) { + DocNode const& node = *element.node; + RtScope const& scope = *element.scope; + bool const collection = node.kind == "collection"; + std::string const action{node.name("action")}; + Catalog const& catalog = session.options().catalog; + auto const& lookup = collection ? catalog.view : catalog.wizard; + std::optional const document = lookup ? lookup(action) : std::nullopt; + if (!document.has_value()) { + report(node.path, std::string{"no "} + (collection ? "view" : "wizard") + " document for `" + action + + "`: the catalog has none for a `" + node.kind + "` to build from"); + return; + } + NameRef const* const alias = scope.find(node.name("model")); + if (alias == nullptr || alias->model == nullptr) { + report(node.path, "`" + std::string{node.name("model")} + "` is not a model alias"); + return; + } + forms::SchemaLookup const schemas = catalog.schema ? forms::SchemaLookup{catalog.schema} : forms::SchemaLookup{}; + forms::Submitter const call = aliasCalls(alias->model); + if (collection) { + auto model = forms::CollectionModel::fromSchema(*document); + if (!model) { + report(node.path, "the collection of `" + action + "` does not build: " + model.error().path + ": " + + model.error().message); + return; + } + if (model->query() != action) { + report(node.path, "the view document of `" + action + "` lists `" + std::string{model->query()} + "`"); + return; + } + std::string query{model->query()}; + element.collection = std::make_unique(runtime(), *std::move(model), schemas, + aliasSubmits(alias->model, std::move(query)), + call, engineOptions()); + return; + } + // The wizard's id, the stem of its translation keys, is the action it starts with. + auto model = forms::WizardModel::fromSchema(action, *document); + if (!model) { + report(node.path, + "the wizard of `" + action + "` does not build: " + model.error().path + ": " + model.error().message); + return; + } + if (model->steps().front().action != action) { + report(node.path, + "the wizard document of `" + action + "` starts with `" + model->steps().front().action + "`"); + return; + } + try { + element.wizard = std::make_unique(runtime(), *std::move(model), schemas, + aliasSubmits(alias->model), call, engineOptions()); + } catch (std::invalid_argument const& error) { + report(node.path, error.what()); + } +} + +// The presentation keys a form, a collection and a wizard share, but the title: the label of the explicit-mode button +// and the status line naming it, bound in the node's scope; whether the status line shows, the grid's columns and the +// field layout and the inline caption column's width, as read at load. +void ScreenCore::presentForm(DocNode const& node, LowerCtx const& ctx, forms::FormViewOptions& options) { + if (ExprPtr const label = node.prop("submitLabel")) { + options.submitLabel = bindProp(ctx, label, std::string{}, stringOf); + } + if (auto const shown = node.flags.find("showStatus"); shown != node.flags.end()) { + options.showStatus = shown->second; + } + if (ExprPtr const columns = node.prop("columns"); columns != nullptr && columns->literal.asInt() != nullptr) { + options.gridColumns = static_cast(*columns->literal.asInt()); + options.flatGridColumns = options.gridColumns; + } + if (node.name("fieldLayout") == "inline") { + options.fieldLayout = forms::FieldLayout::Inline; + } + // The loader has checked `captionWidth` is a literal integer. + if (ExprPtr const width = node.prop("captionWidth")) { + options.inlineLabelWidth = static_cast(*width->literal.asInt()); + } +} + +Node ScreenCore::lowerComposite(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + // The editor's and the steps' titles are the dialog's and the header's; the forms do not repeat them. A `title` + // replaces the view's own heading. + forms::FormViewOptions form{}; + form.showTitle = false; + presentForm(node, ctx, form); + Prop title = bindProp(ctx, node.prop("title"), std::string{}, stringOf); + Node view; + if (element != nullptr && element->collection != nullptr) { + forms::CollectionViewOptions options{}; + options.form = std::move(form); + options.title = std::move(title); + view = forms::collectionView(*element->collection, std::move(options)); + } else if (element != nullptr && element->wizard != nullptr) { + forms::WizardViewOptions options{}; + options.form = std::move(form); + options.title = std::move(title); + view = forms::wizardView(*element->wizard, options); + } else { + return ui::text(Text{.text = std::string{node.name("action")}, .role = TextRole::Muted}); + } + Column column{.children = {std::move(view)}}; + commonOf(node, ctx, element, column.common); + return ui::column(std::move(column)); +} + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): an overlay's scope, content, actions and keys are one lowering. +// NOLINTNEXTLINE(readability-function-cognitive-complexity): an overlay's scope, content, actions and keys are one lowering. +Node ScreenCore::lowerDialog(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + Prop open = node.prop("open") ? bindProp(ctx, node.prop("open"), false, boolOf) + : slotProp([element] { return element->open.get(); }); + std::vector bodyContent; + for (DocNodePtr const& child : node.nodes("children")) { + bodyContent.push_back(child.get()); + } + int const bodyGap = + node.prop("gap") ? static_cast(intOf(once(ctx, node.prop("gap")), kDialogGap)) : kDialogGap; + LayoutHints const bodyHints = holderHints(bodyContent, node.scope ? &*node.scope : nullptr, ctx); + Node body = lazy( + [this, ctx, &node, element, bodyGap]() -> Node { + auto inner = std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); + inner->owner = element; + addPending(1); + inner->submitted = &element->submitted; + inner->showErrors = std::string{node.name("showErrors")}; + std::vector content; + for (DocNodePtr const& child : node.nodes("children")) { + content.push_back(child.get()); + } + std::vector lists; + for (std::string_view const key : {"default", "cancel"}) { + if (Commands const* const commands = node.event(key)) { + lists.push_back(commands); + } + } + for (DocNodePtr const& action : node.partList("actions")) { + if (Commands const* const commands = action->event("onClick")) { + lists.push_back(commands); + } + } + declare(*inner, node.scope ? &*node.scope : nullptr, content, lists); + element->inner.set(inner.get()); + LowerCtx const innerCtx{ + .scope = inner, .bindings = ctx.bindings, .boundary = ctx.boundary, .listGap = bodyGap}; + std::vector children; + children.reserve(content.size()); + for (DocNode const* const child : content) { + children.push_back(lower(*child, innerCtx)); + } + // The overlay's actions end its scoped content, so they bind in its scope; the mount puts them in its + // footer. + if (ActionModels actions = lowerActionParts(node.partList("actions"), innerCtx); !actions.empty()) { + children.push_back(actionBarOf(std::move(actions))); + } + std::vector keys; + if (Commands const* const commands = node.event("default")) { + keys.push_back(KeyBinding{.chord = "Enter", .onPress = [this, innerCtx, commands] { + runEvent(commands, innerCtx, Value{}); + }}); + } + if (Commands const* const commands = node.event("cancel")) { + keys.push_back(KeyBinding{ + .chord = "Esc", .onPress = [this, innerCtx, commands] { runEvent(commands, innerCtx, Value{}); }}); + } + fillHolder(children, node.path); + return holding(std::move(children), inner, std::move(keys), bodyGap); + }, + bodyHints); + Action onDismiss = [this, ctx, element, commands = node.event("onDismiss")] { + session.asUser([&] { + session.noteWrite(); + element->open.set(false); + }); + runEvent(commands, ctx, Value{}); + }; + if (node.kind == "drawer") { + ExprPtr const side = node.prop("side"); + Drawer spec{ + .open = std::move(open), + .title = bindProp(ctx, node.prop("title"), std::string{}, stringOf), + .description = bindProp(ctx, node.prop("description"), std::string{}, stringOf), + .child = std::move(body), + .onDismiss = std::move(onDismiss), + .side = side && textOf(once(ctx, side), ctx.scope->formatting()) == "start" ? Side::Start : Side::End}; + if (ExprPtr const spans = node.prop("descriptionSpans")) { + spec.descriptionSpans = spansProp(ctx, spans); + } + commonOf(node, ctx, element, spec.common); + return ui::drawer(std::move(spec)); + } + Dialog spec{.open = std::move(open), + .title = bindProp(ctx, node.prop("title"), std::string{}, stringOf), + .description = bindProp(ctx, node.prop("description"), std::string{}, stringOf), + .child = std::move(body), + .onDismiss = std::move(onDismiss), + .common = {}, + .sheet = bindProp(ctx, node.prop("sheet"), false, boolOf), + .dismissLabel = bindProp(ctx, node.prop("dismissLabel"), std::string{"Close"}, stringOf)}; + if (ExprPtr const spans = node.prop("descriptionSpans")) { + spec.descriptionSpans = spansProp(ctx, spans); + } + commonOf(node, ctx, element, spec.common); + return ui::dialog(std::move(spec)); +} + +Node ScreenCore::lowerSwitch(DocNode const& node, LowerCtx const& ctx) { + std::vector whens; + Switch spec; + std::int64_t index = 0; + for (DocNodePtr const& part : node.partList("cases")) { + whens.push_back(part->prop("when")); + DocNode const* const casePart = part.get(); + std::vector caseContent; + for (DocNodePtr const& child : casePart->nodes("children")) { + caseContent.push_back(child.get()); + } + LayoutHints const caseHints = holderHints(caseContent, casePart->scope ? &*casePart->scope : nullptr, ctx); + spec.cases.push_back(SwitchCase{ + .key = Key{index++}, + .node = lazy( + [this, ctx, casePart, caseGap = ctx.listGap]() -> Node { + auto inner = std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); + std::vector content; + for (DocNodePtr const& child : casePart->nodes("children")) { + content.push_back(child.get()); + } + declare(*inner, casePart->scope ? &*casePart->scope : nullptr, content, {}); + LowerCtx const innerCtx{ + .scope = inner, .bindings = ctx.bindings, .boundary = ctx.boundary, .listGap = caseGap}; + std::vector children; + children.reserve(content.size()); + for (DocNode const* const child : content) { + children.push_back(lower(*child, innerCtx)); + } + fillHolder(children, casePart->path); + return holding(std::move(children), inner, {}, caseGap); + }, + caseHints)}); + } + spec.selector = slotProp( + [scope = ctx.scope, bindings = ctx.bindings, selected = node.prop("on"), whens = std::move(whens)] { + Value const value = evalIn(*scope, bindings.get(), selected); + for (std::size_t at = 0; at < whens.size(); ++at) { + if (evalIn(*scope, bindings.get(), whens.at(at)) == value) { + return Key{static_cast(at)}; + } + } + return Key{std::int64_t{-1}}; + }); + auto const fallback = node.nodes("default"); + spec.fallback = fallback.empty() ? Node{} : lowerAll(fallback, ctx, ctx.listGap); + commonOf(node, ctx, nullptr, spec.common); + return ui::switchOf(std::move(spec)); +} + +// The tab a bound `selected` names. A value that names no tab shows the first, and is reported once. +Prop ScreenCore::controlledTabSelection(DocNode const& node, LowerCtx const& ctx, ExprPtr const& selected, + std::shared_ptr> const& ids) { + auto const unknownReported = std::make_shared(false); + return Prop{[this, scope = ctx.scope, bindings = ctx.bindings, selected, ids, unknownReported, + path = pointerAppend(node.path, "selected")]() -> std::size_t { + Value const value = evalIn(*scope, bindings.get(), selected); + std::string const* const named = value.asString(); + auto const found = named == nullptr ? ids->end() : std::ranges::find(*ids, *named); + if (found != ids->end()) { + return static_cast(std::distance(ids->begin(), found)); + } + if (!*unknownReported) { + *unknownReported = true; + report(path, canonicalJson(value) + " names no tab; the first is shown"); + } + return 0; + }}; +} + +// A document names tabs by id; the view tree by index, so the ids map to indices once. A bound `selected` is the +// controlled index: a pick runs `onChoose` and the page follows `selected` alone. Without it the node keeps the +// user's pick itself, as a bound index too, whose page follows the pick: a constant would move only the highlight. +Node ScreenCore::lowerTabs(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + Tabs spec; + auto ids = std::make_shared>(); + for (DocNodePtr const& tab : node.partList("tabs")) { + auto const nodes = tab->nodes("children"); + ids->push_back(tab->id); + spec.tabs.push_back(Tab{.label = bindProp(ctx, tab->prop("label"), std::string{}, stringOf), + .node = nodes.empty() ? Node{} : lowerAll(nodes, ctx)}); + } + spec.moreLabel = bindProp(ctx, node.prop("moreLabel"), std::string{"More"}, stringOf); + if (ExprPtr const inset = node.prop("inset")) { + spec.inset = static_cast(intOf(once(ctx, inset), 0)); + } + if (ExprPtr const pageInset = node.prop("pageInset")) { + spec.pageInset = static_cast(intOf(once(ctx, pageInset), 0)); + } + spec.stripSurface = std::string{node.name("stripSurface")}; + ExprPtr const selected = node.prop("selected"); + Commands const* const onChoose = node.event("onChoose"); + bool const controlled = selected && (selected->kind != ExprKind::Literal || !selected->literal.isNull()); + auto const picked = std::make_shared>(runtime(), std::size_t{0}); + spec.selected = controlled ? controlledTabSelection(node, ctx, selected, ids) + : Prop{[picked] { return picked->get(); }}; + spec.onSelect = [this, ctx, onChoose, ids, picked, controlled, element](std::size_t index) { + if (!controlled) { + picked->set(index); + if (element != nullptr && index < ids->size()) { + element->draft.set(Value{ids->at(index)}); + } + } + if (onChoose != nullptr && index < ids->size()) { + runEvent(onChoose, ctx, Value{ids->at(index)}); + } + }; + commonOf(node, ctx, element, spec.common); + return ui::tabs(std::move(spec)); +} + +// Focuses the declaration the command's target resolved to: of several candidates (cases of one switch), the one +// that is mounted. Each candidate is keyed by the command's own enclosing row keys, as many as enclose the +// candidate; with `row`, the innermost of them is the row's key instead. +bool ScreenCore::focusTarget(Command const& command, RtScope const& scope, Bindings const* bindings) { + if (!focusElement) { + return false; + } + auto const found = _doc->focusTargets.find(command.path); + if (found == _doc->focusTargets.end()) { + return focusElement(command.target); + } + FocusPlace const place = focusPlace(scope); + std::optional row; + if (found->second.row) { + Value const value = evalIn(scope, bindings, command.extra); + if (value.isNull()) { + return false; + } + row = canonicalJson(valueOfKey(keyOf(value))); + } + for (FocusCandidate const& candidate : found->second.candidates) { + std::size_t const kept = row ? candidate.rows - 1 : candidate.rows; + if (candidate.rows == 0 && row) { + continue; + } + if (kept > place.rows.size()) { + continue; + } + FocusPlace candidatePlace{ + .prefix = place.prefix, + .rows = {place.rows.begin(), std::next(place.rows.begin(), static_cast(kept))}}; + if (row) { + candidatePlace.rows.push_back(*row); + } + if (focusElement(focusKey(candidatePlace, candidate.path))) { + return true; + } + } + return false; +} + +std::shared_ptr ScreenCore::rowScope(DocNode const& node, LowerCtx const& ctx, + reactive::Signal const& row, + std::vector const& content, std::string key) { + auto scope = std::make_shared(*this, ctx.scope, &row, ctx.scope->nodes.depth() + 2); + scope->rowKey = std::move(key); + declare(*scope, node.scope ? &*node.scope : nullptr, content, {}); + return scope; +} + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): a list of rows and a table. +Node ScreenCore::lowerRows(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + ExprPtr const rowsExpr = node.prop("rows"); + if (!rowsExpr) { + report(node.path, "a model-backed `table` needs the table engine, which this interpreter does not lower yet"); + return ui::text(Text{.text = std::string{"table"}, .role = TextRole::Muted}); + } + std::function()> rows = [scope = ctx.scope, bindings = ctx.bindings, rowsExpr] { + Value const value = evalIn(*scope, bindings.get(), rowsExpr); + ValueList const* const items = value.asList(); + return items == nullptr ? std::vector{} : std::vector{items->begin(), items->end()}; + }; + auto keyFn = [scope = ctx.scope, bindings = ctx.bindings, keyExpr = node.prop("key")](Value const& row) -> Key { + if (Value const* const heading = row.field(kGroupHeadingField); heading != nullptr && heading->asString()) { + return Key{*heading->asString()}; + } + if (!keyExpr) { + Value const rowKey = rowId(row); + return keyOf(rowKey.isNull() ? row : rowKey); + } + ScopeEnv const env{*scope, bindings.get(), &row}; + return keyOf(evaluate(*keyExpr, env)); + }; + if (node.kind == "forEach") { + std::vector content; + for (DocNodePtr const& child : node.nodes("children")) { + content.push_back(child.get()); + } + auto rowView = [this, ctx, &node, content, keyFn](reactive::Signal const& row) -> Node { + std::string key = runtime().untracked([&] { return canonicalJson(valueOfKey(keyFn(row.peek()))); }); + auto scope = rowScope(node, ctx, row, content, std::move(key)); + LowerCtx const rowCtx{.scope = scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; + std::vector children; + children.reserve(content.size()); + for (DocNode const* const child : content) { + children.push_back(lower(*child, rowCtx)); + } + return holding(std::move(children), scope); + }; + ExprPtr const axis = node.prop("axis"); + ExprPtr const gap = node.prop("gap"); + Common common; + commonOf(node, ctx, element, common); + Axis const along = axis ? axisOf(once(ctx, axis)) : Axis::Vertical; + bool wrap = node.flag("wrap"); + if (wrap && along != Axis::Horizontal) { + // Only a computed axis gets here: the loader refuses a literal one that is not horizontal. + report(node.path + "/wrap", + "`wrap` fills lines along a row; this `forEach`'s `axis` is not \"horizontal\""); + wrap = false; + } + bool divided = node.flag("divided"); + if (divided && along != Axis::Vertical) { + report(node.path + "/divided", + "`divided` draws rules between rows of a column; this `forEach`'s `axis` is \"horizontal\""); + divided = false; + } + return ui::forEach(std::move(rows), std::move(keyFn), std::move(rowView), along, + gap ? static_cast(intOf(once(ctx, gap), 0)) : 0, common, wrap, divided); + } + // The table's rows, sorted: the element's own view, which its element values read too, unless names bound + // where the table is lowered (a component's `props`) reach its rows, which the element cannot see. + reactive::Computed const* view = element == nullptr ? nullptr : element->view; + if (view != nullptr && ctx.bindings != nullptr && !ctx.bindings->empty()) { + view = &ctx.scope->nodes.computed( + [this, element, bindings = ctx.bindings] { return tableView(*element, bindings.get()); }); + } + if (view != nullptr) { + // The page's rows, each group's heading entry before the first of its rows the page holds, so a group split + // across pages gets its heading on both. + rows = [view] { + TableView const& shown = view->get(); + std::vector entries; + entries.reserve(shown.last - shown.first); + for (std::size_t index = shown.first; index < shown.last; ++index) { + if (!shown.runOf.empty() && + (index == shown.first || shown.runOf.at(index) != shown.runOf.at(index - 1))) { + entries.push_back(shown.runs.at(shown.runOf.at(index))); + } + entries.push_back(shown.rows.at(index)); + } + return entries; + }; + } + std::vector columns; + std::vector cells; + std::vector fields; + // One entry per column, in the same order as `cells`/`fields`. Captured by `cellsOf` below (not `columns` + // itself, which is moved into `ui::table(...)` further down and so cannot be read from inside a lambda + // that outlives this function) so the default-cell closure can apply each column's role to its generated cell. + std::vector roles; + FormatContext const& format = ctx.scope->formatting(); + // The table's `valign` is the default of every column that gives none; the loader checked both names. + Align const tableValign = cellPlaceNamed(node.name("valign")).value_or(Align::Center); + if (ExprPtr const derived = node.prop("columns")) { + Value const list = once(ctx, derived); + // A computed place that names none is reported once for the table, whichever column and key it was. + bool placeReported = false; + auto const placeOf = [&](Value const& item, std::string_view key, Align fallback) { + Value const* const given = item.field(key); + if (given == nullptr || given->isNull()) { + return fallback; + } + std::string const* const name = given->asString(); + std::optional const placed = name == nullptr ? std::nullopt : cellPlaceNamed(*name); + if (!placed && !placeReported) { + placeReported = true; + report(derived->path, "a column's `" + std::string{key} + "` is " + canonicalJson(*given) + + "; a cell's place is start, center or end"); + } + return placed.value_or(fallback); + }; + if (ValueList const* const items = list.asList()) { + for (Value const& item : *items) { + Value const* const field = item.field("id"); + Value const* const label = item.field("label"); + fields.push_back(field == nullptr ? std::string{} : textOf(*field, format)); + columns.push_back( + TableColumn{.label = textOf(label != nullptr ? *label : Value{fields.back()}, format), + .align = placeOf(item, "align", Align::Start), + .valign = placeOf(item, "valign", tableValign)}); + cells.push_back(nullptr); + roles.push_back(TextRole::Normal); + } + } + } + // A part's column index, which a header click reports, counts the derived columns before it. + std::size_t const derivedCount = columns.size(); + for (DocNodePtr const& part : node.partList("columns")) { + ExprPtr const label = part->prop("label"); + ExprPtr const width = part->prop("width"); + ExprPtr const role = part->prop("role"); + TextRole columnRole = TextRole::Normal; + if (role) { + // Read once, with the rest of the column; a value that names no role is reported, as a text's is. + Value const value = once(ctx, role); + std::optional const named = roleNamed(textOf(value, format)); + if (!named) { + report(role->path, "role is " + canonicalJson(value) + "; " + std::string{kRoleNames}); + } + columnRole = named.value_or(TextRole::Normal); + } + bool const shrink = part->flag("shrink"); + Sizing const sized = width ? sizingOf(once(ctx, width)) : Sizing::content(); + if (shrink && sized.kind != Sizing::Kind::Stretch) { + report(part->path + "/shrink", + "`shrink` lets a stretch column go narrower than its header; this column's width does not stretch"); + } + columns.push_back(TableColumn{.label = label ? textOf(once(ctx, label), format) : std::string{}, + .width = sized, + .role = columnRole, + .align = cellPlaceNamed(part->name("align")).value_or(Align::Start), + .valign = cellPlaceNamed(part->name("valign")).value_or(tableValign), + .sortable = part->flag("sortable"), + .wrap = part->flag("wrap", true), + .shrink = shrink && sized.kind == Sizing::Kind::Stretch}); + cells.push_back(part.get()); + fields.emplace_back(part->id); + roles.push_back(columnRole); + } + auto registry = std::make_shared, std::less<>>>(); + // A value that names no tone is reported once for the table, whichever row and value it was. + auto toneReported = std::make_shared(false); + // Likewise for a `rowSpans` value that is no list of spans. + auto spansReported = std::make_shared(false); + auto cellsOf = [this, ctx, &node, cells, fields, roles, registry, keyFn, toneReported, + spansReported](reactive::Signal const& row) { + if (row.peek().field(kGroupHeadingField) != nullptr) { + return headingRow(node, ctx, row, + runtime().untracked([&] { return canonicalJson(valueOfKey(keyFn(row.peek()))); })); + } + std::vector content; + for (DocNode const* const column : cells) { + if (column != nullptr) { + for (DocNodePtr const& cell : column->nodes("cell")) { + content.push_back(cell.get()); + } + } + } + std::string key = runtime().untracked([&] { return canonicalJson(valueOfKey(keyFn(row.peek()))); }); + auto scope = rowScope(node, ctx, row, content, key); + (*registry)[std::move(key)] = scope; + LowerCtx const rowCtx{.scope = scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; + std::vector out; + for (std::size_t index = 0; index < cells.size(); ++index) { + DocNode const* const column = cells.at(index); + auto const nodes = column == nullptr ? std::span{} : column->nodes("cell"); + if (!nodes.empty()) { + out.push_back(lowerAll(nodes, rowCtx)); + continue; + } + out.push_back( + ui::text(Text{.text = slotProp([scope = rowCtx.scope, &row, field = fields.at(index)] { + Value const* const value = row.get().field(field); + return value == nullptr ? std::string{} : textOf(*value, scope->formatting()); + }), + .role = roles.at(index)})); + } + if (!out.empty()) { + // The row's first cell owns the row's scope, which lives as long as the row's node: a cell is placed by + // its column, so the scope is not held by a wrapping container, which the column would place instead. + auto owner = std::make_shared> const>(out.front(), scope); + out.front() = Node{owner, owner->first.get()}; + } + TableRowView rowView{.cells = std::move(out), .tone = std::nullopt}; + // The row's name, in its own scope: what its select box and assistive technology read. + if (ExprPtr const labelExpr = node.prop("rowLabel")) { + rowView.label = bindProp(rowCtx, labelExpr, std::string{}, stringOf); + } + if (ExprPtr const toneExpr = node.prop("rowTone")) { + rowView.tone = slotProp>( + [this, scope, bindings = ctx.bindings, toneExpr, toneReported]() -> std::optional { + return rowToneOf(evalIn(*scope, bindings.get(), toneExpr), toneExpr->path, *toneReported); + }); + } + if (ExprPtr const spansExpr = node.prop("rowSpans")) { + rowView.spans = slotProp>([this, scope, bindings = ctx.bindings, spansExpr, + spansReported, fields] { + return rowSpansOf(evalIn(*scope, bindings.get(), spansExpr), fields, spansExpr->path, *spansReported); + }); + } + return rowView; + }; + TableOptions options; + options.showHeader = node.flag("showHeader", true); + options.selectColumn = node.flag("selectColumn"); + if (ExprPtr const selectAll = node.prop("selectAllLabel")) { + options.selectAllLabel = bindProp(ctx, selectAll, std::string{}, stringOf); + } + if (ExprPtr const threshold = node.prop("virtualizeThreshold")) { + options.virtualize.threshold = + static_cast(std::max(0, intOf(once(ctx, threshold), 2000))); + } + if (ExprPtr const overscan = node.prop("virtualizeOverscan")) { + options.virtualize.overscan = + static_cast(std::max(0, intOf(once(ctx, overscan), 10))); + } + std::string const mode = + node.prop("selectionMode") ? textOf(once(ctx, node.prop("selectionMode")), format) : std::string{}; + options.selectionMode = SelectionMode::None; + if (mode == "single") { + options.selectionMode = SelectionMode::Single; + } else if (mode == "multiple") { + options.selectionMode = SelectionMode::Multiple; + } + // The selection the table shows: the bound `selection`, or the table's own. A slot even for a literal list, so + // a bound selection is fixed until the document writes it, and a user's change the document leaves unwritten + // snaps back. A bound value that is neither a list nor `null` is reported once. + auto selectionReported = std::make_shared(false); + options.selection = slotProp>([this, element, selectionReported, path = node.path] { + std::vector keys; + if (element->bound != nullptr) { + Value const bound = element->bound->get(); + if (!bound.isNull() && bound.asList() == nullptr && !*selectionReported) { + *selectionReported = true; + report(pointerAppend(path, "selection"), + "selection is " + canonicalJson(bound) + "; a table's selection is a list of keys"); + } + } + Value const selection = tableSelection(*element); + if (ValueList const* const items = selection.asList()) { + for (Value const& item : *items) { + keys.push_back(keyOf(item)); + } + } + return keys; + }); + // A user's change: the table's own selection takes it when no key binds one, then `onSelectionChange` runs with + // `event` the new selection, in the table's scope, in the same batch. The backend holds one page: a `Replace` + // is the whole new selection, and an `Extend` keeps the selected keys of the rows on other pages, before the + // reported ones. A key whose row `rows` no longer has drops on any user change. + options.onSelectionChange = [this, ctx, element, view, keyFn, commands = node.event("onSelectionChange")]( + std::vector const& keys, SelectionChange change) { + ValueList items; + if (change == SelectionChange::Extend && view != nullptr) { + items = runtime().untracked([&] { return selectedOffPage(view->get(), tableSelection(*element), keyFn); }); + } + // A heading is never selected. A virtualized backend knows the keys of rows it has not realized but not + // which of them are headings, so its Ctrl+A or range can name one. + for (Key const& key : keys) { + if (std::string const* const text = std::get_if(&key); + text != nullptr && text->starts_with("\x1Fgroup:")) { + continue; + } + items.push_back(valueOfKey(key)); + } + Value const selected{std::move(items)}; + runtime().batch([&] { + if (element->bound == nullptr) { + session.asUser([&] { + session.noteWrite(); + element->selection.set(selected); + }); + } + runEvent(commands, ctx, selected); + }); + }; + // The header marks the sort's first key; a sort that names no sortable column marks none. + auto const columnIndex = [&node, derivedCount](std::string_view columnId) -> std::optional { + auto const parts = node.partList("columns"); + auto const found = + std::ranges::find_if(parts, [columnId](DocNodePtr const& part) { return part->id == columnId; }); + if (found == parts.end()) { + return std::nullopt; + } + return derivedCount + static_cast(std::distance(parts.begin(), found)); + }; + options.sort = slotProp>([element, &node, columnIndex]() -> std::optional { + std::optional> const keys = sortKeysOf(node, tableSort(*element)); + if (!keys || keys->empty()) { + return std::nullopt; + } + std::optional const index = columnIndex(keys->front().column->id); + if (!index) { + return std::nullopt; + } + return TableSort{.column = *index, + .direction = keys->front().descending ? SortDirection::Descending : SortDirection::Ascending}; + }); + // A header click makes its column the single key: descending when it already is the first key ascending, + // ascending otherwise. The table's own sort takes it when no key binds one, then `onSortChange` runs with + // `event` the new sort. + options.onSort = [this, ctx, element, &node, derivedCount, + commands = node.event("onSortChange")](std::size_t index) { + auto const parts = node.partList("columns"); + if (index < derivedCount || index - derivedCount >= parts.size() || + !parts.subspan(index - derivedCount).front()->flag("sortable")) { + return; + } + std::string const& columnId = parts.subspan(index - derivedCount).front()->id; + Value const current = runtime().untracked([&] { return tableSort(*element); }); + std::optional> const keys = sortKeysOf(node, current); + bool const descending = + keys && !keys->empty() && keys->front().column->id == columnId && !keys->front().descending; + ValueRecord key; + key.insert_or_assign("column", Value{columnId}); + key.insert_or_assign("direction", Value{std::string{descending ? "desc" : "asc"}}); + Value const next{ValueList{Value{std::move(key)}}}; + runtime().batch([&] { + if (element->sortBound == nullptr) { + session.asUser([&] { + session.noteWrite(); + element->sort.set(next); + }); + } + runEvent(commands, ctx, next); + }); + }; + options.onActivate = [this, ctx, element, registry, commands = node.event("onActivate")](Key const& key) { + Value const activated = valueOfKey(key); + session.asUser([&] { + session.noteWrite(); + element->activeKey.set(activated); + }); + auto const found = registry->find(canonicalJson(activated)); + std::shared_ptr const scope = found == registry->end() ? nullptr : found->second.lock(); + LowerCtx const rowCtx{.scope = scope ? scope : ctx.scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; + runEvent(commands, rowCtx, activated); + }; + commonOf(node, ctx, element, options.common); + std::span const empty = node.nodes("empty"); + if (empty.empty()) { + return ui::table(std::move(columns), std::move(rows), std::move(keyFn), std::move(cellsOf), + std::move(options)); + } + // With `empty`, a column holds the table and the content shown in its place while `rows` is an empty list; a + // `null` (a query not answered yet) shows the table. The column is placed as the table would be: it takes the + // node's visibility and layout, and every other common property stays on the table, so its test id and the + // element id `focus` finds name the table. + auto const listed = [scope = ctx.scope, bindings = ctx.bindings, rowsExpr] { + ValueList const* const items = evalIn(*scope, bindings.get(), rowsExpr).asList(); + return items == nullptr || !items->empty(); + }; + Column wrapper; + wrapper.common.visible = std::move(options.common.visible); + wrapper.common.layout = options.common.layout; + options.common.visible = slotProp(listed); + Column content{.children = {lowerAll(empty, ctx)}}; + content.common.visible = slotProp([listed] { return !listed(); }); + wrapper.children.push_back(ui::table(std::move(columns), std::move(rows), std::move(keyFn), + std::move(cellsOf), std::move(options))); + wrapper.children.push_back(ui::column(std::move(content))); + return ui::column(std::move(wrapper)); +} + +TableRowView ScreenCore::headingRow(DocNode const& node, LowerCtx const& ctx, reactive::Signal const& row, + std::string key) { + auto const heading = node.partList("group").front()->nodes("heading"); + std::vector content; + content.reserve(heading.size()); + for (DocNodePtr const& child : heading) { + content.push_back(child.get()); + } + auto scope = rowScope(node, ctx, row, content, std::move(key)); + LowerCtx const rowCtx{.scope = scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; + // The cell owns the heading's scope, for as long as the row's node lives, as a data row's first cell does. + auto owner = std::make_shared> const>(lowerAll(heading, rowCtx), scope); + return TableRowView{.cells = {Node{owner, owner->first.get()}}, .tone = std::nullopt, .heading = true}; +} + +Node ScreenCore::lowerChart(DocNode const& node, LowerCtx const& ctx, ElementState* element) { + Chart spec; + spec.data = slotProp( + [this, &node, scope = ctx.scope, bindings = ctx.bindings] { return chartData(node, *scope, bindings.get()); }); + commonOf(node, ctx, element, spec.common); + return ui::chart(std::move(spec)); +} + +std::optional ScreenCore::chartMagnitude(Value const& value, std::string const& path, + std::optional& unit) { + std::optional const number = numeric(value); + if (!number) { + report(path, "a chart value is a number or a quantity; this one is left out"); + return std::nullopt; + } + std::string const own = number->unit != nullptr ? *number->unit : std::string{}; + if (!unit) { + unit = own; + return number->value; + } + if (*unit == own) { + return number->value; + } + std::optional converted; + if (!own.empty() && !unit->empty()) { + converted = convertUnit(number->value, own, *unit, session.formatting().units); + } + if (!converted) { + report(path, "a chart value does not convert to the unit of the chart's first value; it is left out"); + } + return converted; +} + +std::optional ScreenCore::chartToneOf(Value const& value, std::string const& path) { + static constexpr std::array, 5> kTones = {{ + {"neutral", Tone::Neutral}, + {"info", Tone::Info}, + {"ok", Tone::Ok}, + {"warn", Tone::Warn}, + {"err", Tone::Err}, + }}; + if (value.isNull()) { + return std::nullopt; + } + if (std::string const* const text = value.asString()) { + for (auto const& [name, tone] : kTones) { + if (name == *text) { + return tone; + } + } + } + report(path, "a chart tone is neutral, info, ok, warn or err; this one marks nothing"); + return std::nullopt; +} + +std::optional ScreenCore::chartPosition(Value const& value, std::string const& path, + detail::ChartAxisKinds& kinds) { + if (value.isNull()) { + return std::nullopt; + } + if (std::optional const number = numeric(value)) { + kinds.numbers = true; + return number->value; + } + if (std::optional const instant = + dateInstantOf(value, session.formatting().utcOffsetMinutes).instant) { + kinds.instants = true; + return math::Rational{instant->value.time_since_epoch().count(), math::DecimalPlaces{0}}; + } + report(path, "a chart's `x` is a number, a date or an instant; this point is left out"); + return std::nullopt; +} + +std::vector ScreenCore::chartPoints(DocNode const& series, RtScope const& scope, + Bindings const* bindings, std::optional& unit, + detail::ChartAxisKinds& kinds) { + // A chart is a picture of a few hundred values; a larger set is a table's. + static constexpr std::size_t kMaxPoints = 1000; + FormatContext const& format = scope.formatting(); + ExprPtr const pointsExpr = series.prop("points"); + Value const listed = evalIn(scope, bindings, pointsExpr); + ValueList const* const list = listed.asList(); + if (list == nullptr) { + // `null` is a query still loading, and draws as empty without a word. + if (!listed.isNull()) { + report(pointsExpr->path, "`points` is a list; the series draws as empty"); + } + return {}; + } + std::size_t const first = list->size() > kMaxPoints ? list->size() - kMaxPoints : 0; + if (first > 0) { + report(pointsExpr->path, "a series draws its last 1000 points"); + } + ExprPtr const yExpr = series.prop("y"); + ExprPtr const xExpr = series.prop("x"); + ExprPtr const labelExpr = series.prop("xLabel"); + ExprPtr const toneExpr = series.prop("tone"); + ExprPtr const noteExpr = series.prop("note"); + std::vector points; + for (std::size_t index = first; index < list->size(); ++index) { + ScopeEnv const env{scope, bindings, &list->at(index)}; + detail::ChartRawPoint point{.index = index}; + if (xExpr) { + point.x = chartPosition(evaluate(*xExpr, env), xExpr->path, kinds); + if (!point.x) { + continue; + } + } + Value const value = evaluate(*yExpr, env); + if (!value.isNull()) { + point.y = chartMagnitude(value, yExpr->path, unit); + if (!point.y) { + continue; + } + } + point.xLabel = labelExpr ? textOf(evaluate(*labelExpr, env), format) : std::string{}; + point.note = noteExpr ? textOf(evaluate(*noteExpr, env), format) : std::string{}; + point.tone = toneExpr ? chartToneOf(evaluate(*toneExpr, env), toneExpr->path) : std::nullopt; + points.push_back(std::move(point)); + } + return points; +} +namespace { + +/// @brief A chart's exact value at @p places, as the active locale writes it. +/// @param value The value. +/// @param places The places, at most 18. +/// @param format The formatting facts. +/// @return The text; the exact JSON when the rounded value does not fit. +[[nodiscard]] std::string chartNumberText(math::Rational const& value, std::uint32_t places, + FormatContext const& format) { + std::optional rounded = + math::checkedRoundToDecimalPlaces(value, math::DecimalPlaces{places}, math::RoundingMode::HalfEven); + if (!rounded) { + return textOf(Value{Decimal{value}}, format); + } + rounded->decimalPlaces = math::DecimalPlaces{places}; + return textOf(Value{Decimal{*rounded}}, format); +} + +/// @brief A reference line's stroke by its document name. +/// @param name `solid`, `dashed`, `dotted`, or empty for solid; the loader refuses any other. +/// @return The stroke. +[[nodiscard]] ChartLineStyle chartLineStyle(std::string_view name) { + if (name == "dashed") { + return ChartLineStyle::Dashed; + } + return name == "dotted" ? ChartLineStyle::Dotted : ChartLineStyle::Solid; +} + +/// @brief Where a point sits along a value axis that a document may have fixed, and on which side it is clipped. +/// @param value The point's value. +/// @param range The axis. +/// @return The value drawn, the axis end for a value outside, and the side it lies beyond. +[[nodiscard]] std::pair chartClipped(math::Rational const& value, ChartRange const& range) { + if (value < range.low) { + return {range.low, ChartClip::Below}; + } + if (value > range.high) { + return {range.high, ChartClip::Above}; + } + return {value, ChartClip::None}; +} +} // namespace + +std::vector ScreenCore::chartLines(DocNode const& node, RtScope const& scope, + Bindings const* bindings, std::optional& unit) { + FormatContext const& format = scope.formatting(); + std::vector lines; + for (DocNodePtr const& part : node.partList("lines")) { + ExprPtr const valueExpr = part->prop("value"); + Value const value = evalIn(scope, bindings, valueExpr); + std::optional const magnitude = + value.isNull() ? std::nullopt : chartMagnitude(value, valueExpr->path, unit); + if (!magnitude) { + continue; + } + detail::ChartRawLine line{.value = *magnitude, .label = std::nullopt}; + if (ExprPtr const label = part->prop("label")) { + line.label = textOf(evalIn(scope, bindings, label), format); + } + if (ExprPtr const tone = part->prop("tone")) { + line.tone = chartToneOf(evalIn(scope, bindings, tone), tone->path).value_or(Tone::Neutral); + } + line.style = detail::chartLineStyle(part->name("style")); + lines.push_back(std::move(line)); + } + return lines; +} + +ChartRange ScreenCore::chartFixedRange(DocNode const& node, RtScope const& scope, Bindings const* bindings, + std::optional& unit, ChartRange const& range) { + ChartRange fixed = range; + for (auto const& [key, end] : {std::pair{"yMin", &fixed.low}, std::pair{"yMax", &fixed.high}}) { + if (ExprPtr const expr = node.prop(key)) { + Value const value = evalIn(scope, bindings, expr); + if (!value.isNull()) { + *end = chartMagnitude(value, expr->path, unit).value_or(*end); + } + } + } + if (fixed.high > fixed.low) { + return fixed; + } + report(pointerAppend(node.path, "yMin"), "`yMin` is not below `yMax`; the chart takes its range from its values"); + return range; +} + +void ScreenCore::chartSeries(ChartData& data, DocNode const& node, RtScope const& scope, Bindings const* bindings, + std::vector>& series, bool positioned, + ChartRange const& range) const { + auto const positionOf = [positioned](detail::ChartRawPoint const& point) { + return positioned && point.x ? *point.x + : math::Rational{static_cast(point.index), math::DecimalPlaces{0}}; + }; + std::vector positions; + for (auto const& points : series) { + std::ranges::transform(points, std::back_inserter(positions), positionOf); + } + // The room one position gives its bars: the least distance between two of their positions, gaps included, so a + // bar never grows over the label of an empty position between two. + std::vector barPositions; + { + std::size_t seriesIndex = 0; + for (DocNodePtr const& part : node.partList("series")) { + if (part->name("style") == "bars") { + std::ranges::transform(series.at(seriesIndex), std::back_inserter(barPositions), positionOf); + } + ++seriesIndex; + } + } + std::ranges::sort(barPositions); + std::optional slot; + for (std::size_t next = 1; next < barPositions.size(); ++next) { + auto const distance = math::checkedSub(barPositions.at(next), barPositions.at(next - 1)); + if (distance && distance->numerator > 0 && (!slot || *distance < *slot)) { + slot = *distance; + } + } + if (!barPositions.empty()) { + data.barSlot = realOf(slot.value_or(math::Rational{1, math::DecimalPlaces{0}})); + } + // A bar is centred on its position and half a slot wide each side, so the axis holds that much beyond the + // outermost position. + if (!barPositions.empty() && !positions.empty()) { + math::Rational const half = math::checkedDiv(slot.value_or(math::Rational{1, math::DecimalPlaces{0}}), + math::Rational{2, math::DecimalPlaces{0}}) + .value_or(math::Rational{0, math::DecimalPlaces{0}}); + auto const [lowest, highest] = std::ranges::minmax(positions); + auto const below = math::checkedSub(lowest, half); + auto const above = math::checkedAdd(highest, half); + if (below && above) { + positions.push_back(*below); + positions.push_back(*above); + } + } + if (std::optional const across = chartRange(positions, 0)) { + data.xMin = realOf(across->low); + data.xMax = realOf(across->high); + } + std::size_t index = 0; + for (DocNodePtr const& part : node.partList("series")) { + ChartSeries drawn; + if (part->name("style") == "bars") { + drawn.style = ChartStyle::Bars; + } + if (ExprPtr const label = part->prop("label")) { + drawn.label = textOf(evalIn(scope, bindings, label), scope.formatting()); + } + drawn.joined = drawn.style == ChartStyle::Line && (!part->flags.contains("joined") || part->flag("joined")); + for (detail::ChartRawPoint& point : series.at(index)) { + ChartPoint out{.x = realOf(positionOf(point)), + .y = std::nullopt, + .clip = ChartClip::None, + .xLabel = std::move(point.xLabel), + .tone = point.tone, + .note = std::move(point.note)}; + if (point.y) { + auto const [shown, clip] = detail::chartClipped(*point.y, range); + out.y = realOf(shown); + out.clip = clip; + } + drawn.points.push_back(std::move(out)); + } + data.series.push_back(std::move(drawn)); + ++index; + } +} + +ChartData ScreenCore::chartData(DocNode const& node, RtScope const& scope, Bindings const* bindings) { + FormatContext const& format = scope.formatting(); + ChartData data; + data.summary = textOf(evalIn(scope, bindings, node.prop("summary")), format); + if (ExprPtr const label = node.prop("yLabel")) { + data.yLabel = textOf(evalIn(scope, bindings, label), format); + } + std::optional unit; + detail::ChartAxisKinds kinds; + std::vector> series; + for (DocNodePtr const& part : node.partList("series")) { + series.push_back(chartPoints(*part, scope, bindings, unit, kinds)); + } + std::vector const lines = chartLines(node, scope, bindings, unit); + // The values the axis must hold, and the places they are shown at. + std::vector values; + for (auto const& points : series) { + for (detail::ChartRawPoint const& point : points) { + if (point.y) { + values.push_back(*point.y); + } + } + } + std::ranges::transform(lines, std::back_inserter(values), &detail::ChartRawLine::value); + // A bar grows from 0, so the axis holds 0; the baseline's side is padded only when something lies beyond it, so + // that the baseline is the plot's edge when nothing does. + std::vector axisValues = values; + ChartPadding padding; + bool barsHaveValues = false; + { + std::size_t seriesIndex = 0; + for (DocNodePtr const& part : node.partList("series")) { + barsHaveValues = + barsHaveValues || (part->name("style") == "bars" && + std::ranges::any_of(series.at(seriesIndex), [](detail::ChartRawPoint const& point) { + return point.y.has_value(); + })); + ++seriesIndex; + } + } + if (barsHaveValues) { + axisValues.push_back(math::Rational{0, math::DecimalPlaces{0}}); + padding.low = std::ranges::any_of(values, [](math::Rational const& value) { return value.numerator < 0; }); + padding.high = std::ranges::any_of(values, [](math::Rational const& value) { return value.numerator > 0; }); + } + std::uint32_t widest = 0; + for (math::Rational const& value : values) { + widest = std::max(widest, value.decimalPlaces.value); + } + ExprPtr const placesExpr = node.prop("yPlaces"); + std::int64_t const* const fixedPlaces = placesExpr ? placesExpr->literal.asInt() : nullptr; + std::uint32_t const places = fixedPlaces != nullptr ? static_cast(*fixedPlaces) : widest; + std::optional const computed = chartRange(axisValues, places, padding); + if (!computed) { + report(node.path, "the chart's values overflow its arithmetic; it draws nothing"); + return data; + } + ChartRange const range = chartFixedRange(node, scope, bindings, unit, *computed); + data.yMin = realOf(range.low); + data.yMax = realOf(range.high); + // Three or more lines are the scale a reader reads the chart against; fewer leave the values without one. + std::optional const ticks = lines.size() < 3 ? chartTicks(range) : std::nullopt; + if (ticks) { + std::uint32_t const tickPlaces = std::max(places, ticks->places); + for (math::Rational const& tick : ticks->values) { + data.yTicks.push_back( + ChartTick{.value = realOf(tick), .text = detail::chartNumberText(tick, tickPlaces, format)}); + } + } + for (detail::ChartRawLine const& line : lines) { + data.lines.push_back( + ChartLine{.value = realOf(line.value), + .label = line.label.value_or(detail::chartNumberText(line.value, places, format)), + .tone = line.tone, + .style = line.style}); + } + if (kinds.numbers && kinds.instants) { + report(pointerAppend(node.path, "series"), + "a chart's `x` values are all numbers or all dates and instants; the points are spaced by index"); + } + chartSeries(data, node, scope, bindings, series, kinds.numbers != kinds.instants, range); + return data; +} + +std::optional ScreenCore::rowToneOf(Value const& value, std::string const& path, bool& noted) { + if (value.isNull()) { + return std::nullopt; + } + if (std::optional const tone = toneNamed(value)) { + return tone; + } + if (!noted) { + noted = true; + report(path, "rowTone is " + canonicalJson(value) + "; a tone is neutral, info, ok, warn or err"); + } + return std::nullopt; +} + +std::vector ScreenCore::rowSpansOf(Value const& value, std::vector const& columns, + std::string const& path, bool& noted) { + std::vector spans; + if (value.isNull()) { + return spans; + } + ValueList const* const items = value.asList(); + bool bad = items == nullptr; + for (Value const& item : items != nullptr ? *items : ValueList{}) { + Value const* const column = item.field("column"); + Value const* const rows = item.field("rows"); + std::string const* const id = column != nullptr ? column->asString() : nullptr; + std::int64_t const* const count = rows != nullptr ? rows->asInt() : nullptr; + auto const found = id != nullptr ? std::ranges::find(columns, *id) : columns.end(); + if (found == columns.end() || count == nullptr || *count < 1) { + bad = true; + continue; + } + spans.push_back(RowSpan{.column = static_cast(found - columns.begin()), + .rows = static_cast(*count)}); + } + if (bad && !noted) { + noted = true; + report(path, + "rowSpans is " + canonicalJson(value) + "; a span is {column: a column's id, rows: an integer from 1}"); + } + return spans; +} + +void ScreenCore::ownQueriesOf(ExprPtr const& expr, RtScope const& scope, BoundaryRuntime& boundary, + std::set>& seen) { + if (!expr) { + return; + } + bool const control = expr->kind == ExprKind::Query || expr->kind == ExprKind::Pending || + expr->kind == ExprKind::Error || expr->kind == ExprKind::ErrorKind || + expr->kind == ExprKind::Refusal; + if (control || expr->kind == ExprKind::Ref) { + NameRef const* const found = scope.find(expr->name); + if (found != nullptr && found->category == NameCategory::Query && seen.insert(expr->name).second) { + boundary.queries.push_back(found->query); + } + if (expr->kind == ExprKind::Ref && found != nullptr && found->category == NameCategory::Let && + seen.insert("let:" + expr->name).second) { + ownQueriesOf(found->letExpr, scope, boundary, seen); + } + } + for (ExprPtr const& arg : expr->args) { + ownQueriesOf(arg, scope, boundary, seen); + } + for (auto const& [name, field] : expr->fields) { + static_cast(name); + ownQueriesOf(field, scope, boundary, seen); + } +} + +void ScreenCore::ownQueries(DocNode const& node, RtScope const& scope, BoundaryRuntime& boundary, + std::set>& seen) { + if (node.kind == "boundary") { + return; + } + for (auto const& [key, expr] : node.props) { + static_cast(key); + ownQueriesOf(expr, scope, boundary, seen); + } + for (auto const& [key, nodes] : node.children) { + static_cast(key); + for (DocNodePtr const& child : nodes) { + ownQueries(*child, scope, boundary, seen); + } + } + for (auto const& [key, parts] : node.parts) { + static_cast(key); + for (DocNodePtr const& part : parts) { + ownQueries(*part, scope, boundary, seen); + } + } +} + +Node ScreenCore::lowerBoundary(DocNode const& node, LowerCtx const& ctx) { + auto boundary = std::make_shared(); + std::set> seen; + for (DocNodePtr const& child : node.nodes("children")) { + ownQueries(*child, *ctx.scope, *boundary, seen); + } + auto bindings = std::make_shared(*ctx.bindings); + bindings->push_back(Binding{.name = "boundary", .read = [boundary] { + for (QueryRuntime const* const query : boundary->queries) { + Value const error = query->error(); + if (!error.isNull() && query->value().isNull()) { + return Value{ValueRecord{{"error", error}}}; + } + } + return Value{ValueRecord{{"error", Value{}}}}; + }}); + LowerCtx const errorCtx{.scope = ctx.scope, .bindings = bindings, .boundary = boundary}; + LowerCtx const childCtx{.scope = ctx.scope, .bindings = ctx.bindings, .boundary = boundary}; + auto group = [this](std::span nodes, LowerCtx const& where) -> Node { + return nodes.empty() ? ui::spacer() : lowerAll(nodes, where); + }; + Switch spec; + spec.cases.push_back(SwitchCase{.key = Key{std::int64_t{0}}, .node = group(node.nodes("loading"), childCtx)}); + spec.cases.push_back(SwitchCase{.key = Key{std::int64_t{1}}, .node = group(node.nodes("error"), errorCtx)}); + spec.cases.push_back(SwitchCase{.key = Key{std::int64_t{2}}, .node = group(node.nodes("children"), childCtx)}); + spec.selector = slotProp([boundary] { + bool loading = false; + for (QueryRuntime const* const query : boundary->queries) { + if (!query->settled()) { + loading = true; + } else if (query->value().isNull() && !query->error().isNull()) { + return Key{std::int64_t{1}}; + } + } + return Key{std::int64_t{loading ? 0 : 2}}; + }); + commonOf(node, ctx, nullptr, spec.common); + return ui::switchOf(std::move(spec)); +} + +Node ScreenCore::lowerCustom(DocNode const& node, LowerCtx const& ctx) { + std::string const name{node.name("name")}; + // A loaded document's custom node names a declared component, and every component has a fallback. + Component const& component = _doc->components.at(name); + std::vector> props; + for (DocNodePtr const& record : node.partList("props")) { + for (auto const& [key, expr] : record->props) { + props.emplace_back(key, expr); + } + } + auto bindings = std::make_shared(); + bindings->push_back( + Binding{.name = "props", .read = [scope = ctx.scope, outer = ctx.bindings, props = std::move(props)] { + ValueRecord record; + for (auto const& [key, expr] : props) { + record.insert_or_assign(key, evalIn(*scope, outer.get(), expr)); + } + return Value{std::move(record)}; + }}); + auto scope = std::make_shared(*this, nullptr, nullptr, ctx.scope->nodes.depth() + 1); + scope->formatSource = ctx.scope; + scope->usePrefix = focusKeyOf(node.path, *ctx.scope) + ">"; + DocNode const& fallback = *component.fallback; + declare(*scope, nullptr, {&fallback}, {}); + Node lowered = lower(fallback, LowerCtx{.scope = scope, .bindings = bindings, .boundary = nullptr}); + Custom spec{.name = name, + .fallback = std::move(lowered), + .props = {}, + .minVersion = + static_cast(std::clamp(component.version, 0, std::numeric_limits::max())), + .onEvent = {}}; + // Every declared prop is given, a missing one as its type's empty value: a component lacking one is refused. + for (auto const& [prop, type] : component.props) { + ExprPtr expr; + for (DocNodePtr const& record : node.partList("props")) { + if (ExprPtr const given = record->prop(prop)) { + expr = given; + } + } + if (type == "bool") { + spec.props.push_back(CustomProp{.name = prop, .value = bindProp(ctx, expr, false, boolOf)}); + } else if (type == "number") { + spec.props.push_back(CustomProp{ + .name = prop, .value = bindProp(ctx, expr, 0.0, [](Value const& value, FormatContext const&) { + return componentNumber(value); + })}); + } else { + spec.props.push_back( + CustomProp{.name = prop, + .value = bindProp(ctx, expr, std::string{}, + [type](Value const& value, FormatContext const& format) { + return componentText(value, type, format); + })}); + } + } + spec.onEvent = [this, ctx, site = &node, declared = &component](std::string const& event, + std::string const& payload) { + Commands const* const commands = site->event("on." + event); + if (commands == nullptr) { + return; + } + auto const type = declared->events.find(event); + runEvent(commands, ctx, componentPayload(payload, type == declared->events.end() ? nullptr : &type->second)); + }; + return ui::custom(std::move(spec)); +} +namespace { + +/// @brief One child of an arranged container, as the user's choice places it. +struct ArrangedChild { + /// @brief The child's id. + std::string id; + /// @brief Whether the choice hides it. + bool hidden = false; +}; + +/// @brief A container's children in the order a stored `arrange` choice gives, each marked shown or hidden. +/// +/// A child the choice does not name keeps its declared place after the named ones, shown, and an entry that names no +/// child, names one twice or is not a `{"id", "hidden"}` record is skipped, so a new document version survives an old +/// choice (spec 5 §12b). A choice that is not a list leaves the declared order. Only `"hidden": true` hides. +/// @param stored The point's current choice. +/// @param declared The container's children, in document order. +/// @return Every child, in order. +[[nodiscard]] std::vector arrangedChildren(Value const& stored, + std::span declared) { + auto const isDeclared = [declared](std::string const& childId) { + return std::ranges::find(declared, childId, &DocNode::id) != declared.end(); + }; + std::vector out; + std::set> placed; + if (ValueList const* const entries = stored.asList()) { + for (Value const& entry : *entries) { + Value const* const named = entry.field("id"); + std::string const* const name = named == nullptr ? nullptr : named->asString(); + if (name == nullptr || !isDeclared(*name) || !placed.insert(*name).second) { + continue; + } + Value const* const hidden = entry.field("hidden"); + bool const* const flag = hidden == nullptr ? nullptr : hidden->asBool(); + out.push_back(ArrangedChild{.id = *name, .hidden = flag != nullptr && *flag}); + } + } + for (DocNode const* const child : declared) { + if (!placed.contains(child->id)) { + out.push_back(ArrangedChild{.id = child->id}); + } + } + return out; +} + +/// @brief The ids of the children an `arrange` choice shows, in its order (`arrangedChildren`, without the hidden). +/// @param stored The point's current choice. +/// @param declared The container's children, in document order. +/// @return The ids to show, in order. +[[nodiscard]] std::vector arrangedOrder(Value const& stored, std::span declared) { + std::vector order; + for (ArrangedChild const& child : arrangedChildren(stored, declared)) { + if (!child.hidden) { + order.emplace_back(child.id); + } + } + return order; +} + +/// @brief An arrangement as the choice an `arrange` point stores. +/// @param children Every child, in order. +/// @return `[{"id", "hidden"}, …]`. +[[nodiscard]] Value arrangementValue(std::vector const& children) { + ValueList entries; + entries.reserve(children.size()); + for (ArrangedChild const& child : children) { + entries.emplace_back(ValueRecord{{"id", Value{child.id}}, {"hidden", Value{child.hidden}}}); + } + return Value{std::move(entries)}; +} + +/// @brief The element of a document tree with @p elementId. +/// @param node The subtree. +/// @param elementId The element's id. +/// @return The element, or `nullptr` when the subtree has none with that id. +// NOLINTNEXTLINE(misc-no-recursion): one level per level of the document tree. +[[nodiscard]] DocNode const* elementNode(DocNode const& node, std::string_view elementId) { + if (node.id == elementId) { + return &node; + } + for (auto const* const groups : {&node.children, &node.parts}) { + for (auto const& [slot, nodes] : *groups) { + static_cast(slot); + for (DocNodePtr const& child : nodes) { + if (DocNode const* const found = elementNode(*child, elementId)) { + return found; + } + } + } + } + return nullptr; +} +} // namespace + +std::string ScreenCore::arrangedBy(std::string const& elementId) const { + if (elementId.empty()) { + return {}; + } + for (auto const& [name, point] : _doc->customize) { + if (point.kind == "arrange" && point.of == elementId) { + return name; + } + } + return {}; +} + +// A keyed list over the children's ids rather than a stack, so a new choice moves the shown widgets, keeping their +// state and focus, and mounts or unmounts only what it shows or hides. A child is lowered in the container's own +// scope: arranging changes where it is, not what it reads. +Node ScreenCore::lowerArranged(DocNode const& node, LowerCtx const& ctx, ElementState* element, + std::string const& point, Axis axis, int gap) { + std::vector declared; + for (DocNodePtr const& child : node.nodes("children")) { + declared.push_back(child.get()); + } + auto order = [this, point, declared] { return arrangedOrder(prefs.get().at(point), declared); }; + auto key = [](Value const& childId) { return keyOf(childId); }; + LowerCtx childCtx = ctx; + childCtx.listGap = axis == Axis::Vertical ? gap : 0; + auto view = [this, childCtx, declared](reactive::Signal const& row) -> Node { + // The order lists only declared ids, so the lookup always finds the child. + auto const found = std::ranges::find(declared, textOf(row.peek(), session.formatting()), &DocNode::id); + return lower(**found, childCtx); + }; + ForEach spec{ + .model = std::make_shared const>(std::move(order), std::move(key), std::move(view)), + .axis = axis, + .gap = gap}; + commonOf(node, ctx, element, spec.common); + return makeNode(std::move(spec)); +} + +// One row per child of the arranged container, hidden ones included: a checkbox shows or hides it, and two buttons +// move it a place. Each edit stores the whole arrangement, so the stored list always names every child. +Node ScreenCore::lowerArrangeEditor(DocNode const& node, LowerCtx const& ctx, std::string const& point, + CustomizePoint const& spec, std::function const& choose) { + // The loader checked that `of` names a column or row of this screen. + DocNode const* const container = elementNode(*_doc->view, spec.of); + std::vector declared; + for (DocNodePtr const& child : container->nodes("children")) { + declared.push_back(child.get()); + } + auto const current = [this, point, declared] { return arrangedChildren(prefs.get().at(point), declared); }; + auto const place = [current](std::string const& childId) { + auto const children = current(); + return static_cast(std::ranges::find(children, childId, &ArrangedChild::id) - children.begin()); + }; + // Applies an edit to the arrangement as it stands, read untracked: the edit is a transition, not a binding. + auto const edit = [this, current, choose](std::string const& childId, auto const& change) { + auto children = runtime().untracked(current); + auto const found = std::ranges::find(children, childId, &ArrangedChild::id); + change(children, static_cast(found - children.begin())); + choose(arrangementValue(children)); + }; + auto rows = [current] { + std::vector ids; + for (ArrangedChild const& child : current()) { + ids.emplace_back(child.id); + } + return ids; + }; + auto key = [](Value const& childId) { return keyOf(childId); }; + auto view = [this, current, place, edit](reactive::Signal const& row) -> Node { + std::string const childId = textOf(row.peek(), session.formatting()); + Checkbox shown{.label = childId}; + shown.checked = slotProp([current, childId] { + auto const children = current(); + return !std::ranges::find(children, childId, &ArrangedChild::id)->hidden; + }); + shown.onToggle = [edit, childId](bool checked) { + edit(childId, [checked](std::vector& children, std::size_t index) { + children.at(index).hidden = !checked; + }); + }; + Button moveUp{.label = std::string{"\xE2\x86\x91"}}; + moveUp.onClick = [edit, childId] { + // Clamped rather than refused: at the edge the child swaps with itself, which stores the same order. + edit(childId, [](std::vector& children, std::size_t index) { + std::swap(children.at(index), children.at(std::max(index, std::size_t{1}) - 1)); + }); + }; + moveUp.common.enabled = slotProp([place, childId] { return place(childId) > 0; }); + moveUp.common.a11y.name = "Move " + childId + " up"; + moveUp.common.testId = "arrange-up-" + childId; + Button moveDown{.label = std::string{"\xE2\x86\x93"}}; + moveDown.onClick = [edit, childId] { + edit(childId, [](std::vector& children, std::size_t index) { + std::swap(children.at(index), children.at(std::min(index + 1, children.size() - 1))); + }); + }; + moveDown.common.enabled = + slotProp([current, place, childId] { return place(childId) + 1 < current().size(); }); + moveDown.common.a11y.name = "Move " + childId + " down"; + moveDown.common.testId = "arrange-down-" + childId; + shown.common.testId = "arrange-shown-" + childId; + return ui::row(Row{.children = {ui::checkbox(std::move(shown)), ui::button(std::move(moveUp)), + ui::button(std::move(moveDown))}, + .gap = 1}); + }; + ForEach editor{.model = + std::make_shared const>(std::move(rows), std::move(key), std::move(view))}; + commonOf(node, ctx, nullptr, editor.common); + return makeNode(std::move(editor)); +} + +Node ScreenCore::lowerCustomize(DocNode const& node, LowerCtx const& ctx) { + std::string const point{node.name("point")}; + // A loaded document's customize node names a declared point, and every point has a choice in `prefs`. + CustomizePoint const& spec = _doc->customize.at(point); + auto choose = [this, point](Value value) { + session.asUser([&] { + ValueRecord next = prefs.peek(); + next.insert_or_assign(point, value); + prefs.set(std::move(next)); + }); + if (host != nullptr) { + host->preferenceChanged(_doc->id, point, value); + } + }; + if (spec.kind == "arrange") { + return lowerArrangeEditor(node, ctx, point, spec, choose); + } + if (spec.kind == "choice") { + Select select; + std::vector options; + options.reserve(spec.options.size()); + for (std::string const& option : spec.options) { + options.push_back(SelectOption{.key = Key{option}, .label = option}); + } + select.options = std::move(options); + select.selected = slotProp>([this, point]() -> std::optional { + Value const& chosen = prefs.get().at(point); + return chosen.isNull() ? std::nullopt : std::optional{keyOf(chosen)}; + }); + select.onSelect = [choose](Key const& key) { choose(valueOfKey(key)); }; + commonOf(node, ctx, nullptr, select.common); + return ui::select(std::move(select)); + } + if (spec.kind == "value" && (spec.type.kind == TypeKind::String || spec.type.isAny())) { + TextInput input; + input.value = + slotProp([this, point] { return textOf(prefs.get().at(point), session.formatting()); }); + input.onChange = [choose](std::string text) { choose(Value{std::move(text)}); }; + commonOf(node, ctx, nullptr, input.common); + return ui::textInput(std::move(input)); + } + Text placeholder{.text = point, .role = TextRole::Muted}; + commonOf(node, ctx, nullptr, placeholder.common); + return ui::text(std::move(placeholder)); +} +// NOLINTEND(misc-no-recursion) + +} // namespace detail + +std::vector Screen::headSpans(ExprPtr const& expr) const { + if (expr == nullptr) { + return {}; + } + bool dropped = false; + bool badTone = false; + std::vector spans = + detail::spansOf(detail::evalIn(*_scope, nullptr, expr), _scope->formatting(), dropped, &badTone); + if (dropped) { + _core->report(expr->path, detail::kSpansReason); + } + if (badTone) { + _core->report(expr->path, detail::kSpanToneReason); + } + return spans; +} + +DocNode const* Screen::shownRoot() const { + DocNode const* node = _core->doc().view.get(); + while (node != nullptr && node->kind == "switch") { + Value const value = detail::evalIn(*_scope, nullptr, node->prop("on")); + std::span shown = node->nodes("default"); + for (DocNodePtr const& part : node->partList("cases")) { + if (!(detail::evalIn(*_scope, nullptr, part->prop("when")) == value)) { + continue; + } + if (part->scope.has_value() && detail::declaresNames(*part->scope)) { + return nullptr; + } + shown = part->nodes("children"); + break; + } + node = shown.size() == 1 ? shown.front().get() : nullptr; + } + return node; +} + +bool Screen::pageEdge() const { + DocNode const* const node = shownRoot(); + return node != nullptr && node->flag("pageEdge"); +} + +bool Screen::headJoined() const { + DocNode const* const node = shownRoot(); + return node != nullptr && node->flag("headJoined"); +} + +LeadPlacement Screen::leadPlacement() const { + ExprPtr const& placement = _core->doc().leadPlacement; + if (placement == nullptr) { + return LeadPlacement::Below; + } + Value const value = detail::evalIn(*_scope, nullptr, placement); + if (std::string const* const name = value.asString()) { + if (*name == "inline") { + return LeadPlacement::Inline; + } + if (*name == "end") { + return LeadPlacement::End; + } + if (*name == "below") { + return LeadPlacement::Below; + } + } + if (!value.isNull()) { + _core->report(placement->path, "`leadPlacement` is `below`, `inline` or `end`"); + } + return LeadPlacement::Below; +} + +TextRole Screen::titleRole() const { + ExprPtr const& role = _core->doc().titleRole; + if (role == nullptr) { + return TextRole::Heading; + } + Value const value = detail::evalIn(*_scope, nullptr, role); + if (std::string const* const name = value.asString()) { + if (*name == "headline") { + return TextRole::Headline; + } + if (*name == "heading") { + return TextRole::Heading; + } + } + if (!value.isNull()) { + _core->report(role->path, "`titleRole` is `heading` or `headline`"); + } + return TextRole::Heading; +} + +std::string Screen::headSurface() const { + Value const value = detail::evalIn(*_scope, nullptr, _core->doc().headSurface); + std::string const* const name = value.asString(); + return name == nullptr ? std::string{} : *name; +} + +std::string Screen::pageSurface() const { + Value const value = detail::evalIn(*_scope, nullptr, _core->doc().pageSurface); + std::string const* const name = value.asString(); + return name == nullptr ? std::string{} : *name; +} + +std::vector Screen::subtitleSpans() const { return headSpans(_core->doc().subtitleSpans); } + +std::vector Screen::titleSpans() const { return headSpans(_core->doc().titleSpans); } + +std::vector Screen::eyebrowSpans() const { return headSpans(_core->doc().eyebrowSpans); } + +BorrowedModel Screen::lend(std::string_view alias) const { + detail::NameRef const* const found = _scope->find(alias); + if (found == nullptr || found->category != detail::NameCategory::Model) { + return {}; + } + detail::ModelAlias& model = *found->model; + return BorrowedModel{.channel = detail::channelOf(model, *_core), + .token = _core->runtime().untracked([&] { return model.token->get(); })}; +} + +std::expected, Refusal> Interpreter::mount(std::shared_ptr doc, + ValueRecord const& params, IViewBackend& backend, + MountOptions const& options) { + auto refuse = [&](std::string path, std::string reason) { + return std::unexpected(Refusal{.document = doc->id, .path = std::move(path), .reason = std::move(reason)}); + }; + if (!doc->view) { + return refuse("", "the document has no view"); + } + ValueRecord given; + for (auto const& [name, type] : doc->params) { + auto const found = params.find(name); + Value value = found == params.end() ? Value{} : found->second; + if (!type.admits(value)) { + return refuse(pointerAppend("/params", name), value.isNull() + ? "param `" + name + "` is missing" + : "param `" + name + "` is not a " + type.name()); + } + given.insert_or_assign(name, std::move(value)); + } + for (ModelDecl const& model : doc->scope.models) { + if (model.instance == InstanceMode::Borrowed && !options.borrowed.contains(model.name)) { + return refuse(model.path, "alias `" + model.name + "` borrows a model its opener did not lend"); + } + } + reactive::Runtime& runtime = _session->runtime(); + std::unique_ptr screen{new Screen{}}; + screen->_core = std::make_unique(doc, *_session, *_dispatcher, _options, options); + detail::ScreenCore& core = *screen->_core; + if (options.keepStateOf != nullptr) { + core.keptStates = options.keepStateOf->ownState(); + } + screen->_scope = std::make_shared(core, nullptr, nullptr, options.depth); + core.rootScope = screen->_scope; + detail::RtScope& scope = *screen->_scope; + scope.submitted = &core.submitted; + scope.showErrors = doc->showErrors; + for (auto const& [name, value] : given) { + detail::NameRef ref; + ref.category = detail::NameCategory::Param; + ref.param = value; + scope.names.insert_or_assign(name, std::move(ref)); + } + std::vector lists; + for (auto const& [key, commands] : doc->lifecycle) { + static_cast(key); + lists.push_back(&commands); + } + for (auto const& [chord, commands] : doc->keys) { + static_cast(chord); + lists.push_back(&commands); + } + detail::headCommandLists(*doc, lists); + Node root = runtime.untracked([&] { + core.declare(scope, &doc->scope, {doc->view.get()}, lists); + detail::LowerCtx const ctx{ + .scope = screen->_scope, .bindings = std::make_shared(), .boundary = nullptr}; + Node lowered = core.lower(*doc->view, ctx); + screen->_headStatus = core.lowerBadgeParts(doc->status, ctx); + screen->_headActions = core.lowerActionParts(doc->actions, ctx); + screen->_headMenu = core.lowerHeadMenu(doc->menu, ctx); + screen->_headTools = core.lowerHeadTools(doc->tools, ctx); + if (!doc->keys.empty()) { + std::vector keys; + for (auto const& [chord, commands] : doc->keys) { + keys.push_back(KeyBinding{ + .chord = chord, .onPress = [&core, ctx, list = &commands] { core.runEvent(list, ctx, Value{}); }}); + } + Column column{.children = {std::move(lowered)}}; + column.common.keys = std::move(keys); + lowered = ui::column(std::move(column)); + } + return lowered; + }); + screen->_mounted.emplace(runtime, backend, std::move(root), options.parent, options.depth + 1); + screen->_core->focusElement = [mounted = &*screen->_mounted](std::string_view element) { + return mounted->focus(element); + }; + screen->runLifecycle("onMount"); + return screen; +} + +std::expected, Refusal> Interpreter::mountApp(std::shared_ptr doc) { + if (doc->id != "app") { + return std::unexpected( + Refusal{.document = doc->id, .path = "/id", .reason = "the app document's id is `app`"}); + } + if (_session->appScope() != nullptr) { + return std::unexpected( + Refusal{.document = doc->id, .path = {}, .reason = "an app document is already mounted on the session"}); + } + std::unique_ptr root{new AppRoot{}}; + root->_core = std::make_unique(doc, *_session, *_dispatcher, _options, MountOptions{}); + detail::ScreenCore& core = *root->_core; + root->_scope = std::make_shared(core, nullptr, nullptr, 0); + core.rootScope = root->_scope; + std::vector lists; + for (auto const& [key, commands] : doc->lifecycle) { + static_cast(key); + lists.push_back(&commands); + } + _session->runtime().untracked([&] { + core.declare(*root->_scope, &doc->scope, {}, lists); + detail::LowerCtx const ctx{ + .scope = root->_scope, .bindings = std::make_shared(), .boundary = nullptr}; + std::vector badges = core.lowerBadgeParts(doc->navigation, ctx); + for (std::size_t index = 0; index < badges.size(); ++index) { + root->_navigation.push_back( + AppRoot::PlacedBadge{.screen = std::string{doc->navigation.at(index)->name("screen")}, + .badge = std::move(badges.at(index))}); + } + }); + root->_navigationBadges = std::make_unique>>( + _session->runtime(), [placed = &root->_navigation] { + std::vector shown; + for (AppRoot::PlacedBadge const& entry : *placed) { + if (entry.badge.visible.evaluate()) { + shown.push_back(NavigationBadge{.screen = entry.screen, + .text = entry.badge.text.evaluate(), + .tone = entry.badge.tone.evaluate()}); + } + } + return shown; + }); + // The app document's date patterns are the application's: every screen of the bundle shows and reads dates so. + if (!doc->datePattern.empty() || !doc->dateTimePattern.empty()) { + _session->setDatePatterns(doc->datePattern, doc->dateTimePattern); + } + _session->setAppScope(root->_scope.get()); + if (auto const found = doc->lifecycle.find("onMount"); found != doc->lifecycle.end()) { + root->runCommands(found->second); + } + return root; +} + +} // namespace morph::ui diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 7bdc8d7d7..ca7e77715 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -205,6 +205,7 @@ add_executable(morph_tests test_ui_structure.cpp test_ui_foreach.cpp test_ui_table.cpp + bench_interpreter.cpp bench_mount.cpp test_ui_frontend.cpp test_ui_conformance.cpp diff --git a/tests/bench_interpreter.cpp b/tests/bench_interpreter.cpp new file mode 100644 index 000000000..720542895 --- /dev/null +++ b/tests/bench_interpreter.cpp @@ -0,0 +1,66 @@ +// SPDX-License-Identifier: Apache-2.0 +// +// Interpreter measurements: mounting a ui/1 document with a table, and re-running its reactive graph after a +// state change. Hidden, so ctest never runs it; run it by tag on a Release build: +// +// morph_tests "[.benchmark][interpreter]" + +#include +#include +#include +#include +#include + +#include "ui_interpreter_support.hpp" + +namespace ui = morph::ui; +using ui::testing::Harness; + +namespace { + +/// A document with a state-driven table of `rows` rows, a few computed texts and a button that bumps a counter every +/// text reads. +std::string benchDocument(std::size_t rows) { + std::string items; + for (std::size_t i = 0; i < rows; ++i) { + items += std::format(R"({}{{ "id": {}, "name": "row-{}", "qty": {} }})", i == 0 ? "" : ",", i, i, i % 17); + } + return std::format(R"({{ + "vocab": "ui/1", "id": "bench", + "state": {{ "count": {{ "init": 0 }}, "items": {{ "init": {{ "lit": [{}] }} }} }}, + "view": {{ "kind": "column", "children": [ + {{ "kind": "button", "testId": "bump", "label": "bump", + "onClick": {{ "set": "count", "value": {{ "fn": "add", "args": [ {{ "ref": "count" }}, 1 ] }} }} }}, + {{ "kind": "text", "testId": "shown", "text": {{ "fn": "format", "args": [ "{{0}} clicks", {{ "ref": "count" }} ] }} }}, + {{ "kind": "table", "rows": {{ "ref": "items" }}, + "columns": [ {{ "id": "id", "label": "Id" }}, {{ "id": "name", "label": "Name" }}, {{ "id": "qty", "label": "Qty" }} ] }} ] }} }})", + items); +} + +} // namespace + +TEST_CASE("interpreter bench: mount a document with a table", "[.benchmark][interpreter]") { + std::string const doc = benchDocument(200); + BENCHMARK("mount, 200 rows") { + Harness h; + auto screen = h.mount(doc); + return h.backend.all("Table").size(); + }; +} + +TEST_CASE("interpreter bench: update state read by a mounted screen", "[.benchmark][interpreter]") { + std::string const doc = benchDocument(200); + Harness h; + auto screen = h.mount(doc); + int const bump = h.byTestId("Button", "bump"); + // Guards the measurement: a click that changed nothing would time an empty path. + REQUIRE(h.text("shown") == "0 clicks"); + h.backend.click(bump); + h.settle(); + REQUIRE(h.text("shown") == "1 clicks"); + BENCHMARK("click and settle") { + h.backend.click(bump); + h.settle(); + return h.backend.all("Text").size(); + }; +} From ed76d28599c81cf24f6b156dceb40bc315cac707 Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 00:10:56 +0100 Subject: [PATCH 05/38] Prune interpreter.hpp's includes, and clear clang-tidy on the moved code Includes. The compiled bodies carry the includes only they need: the bridge, the forms engine, the wire envelope, the message and locale tables, the chart scale and the backend's mount layer. The header forward-declares what its declarations take by reference or pointer (bridge::Bridge, bridge::BindSharing, the wire bodies, the forms sessions, ChartRange, Mounted). ElementState's constructor and destructor move out of line, because it owns forms sessions, and its copy and move are deleted. BridgeDispatcher::Channel is defined in the .cpp. Screen::_mounted becomes a unique_ptr, so the header needs Mounted only declared. kMaxInlineFileBytes is spelled as its value, and the .cpp asserts it equals the wire envelope formula it came from. host.hpp, preference_sync.hpp, ui_interpreter_support.hpp, test_push_cache.cpp and test_ui_interpreter_commands.cpp relied on interpreter.hpp for an include and now name it. preference_sync.hpp only failed the standalone interface-header-set check, which is not part of the default build. check_install_export.sh's consumer also calls an interpreter function (detail::base64Size), so an archive without interpreter.cpp fails to link. clang-tidy. Moving a body makes every line of it lintable, so the .cpp gets the const-correctness, trailing-comma, redundant lambda parameter list and string-view-conversion fixes, NOLINT reasons where a body implements an interface (the InterpreterHost defaults, the recursive menu walks, the two long element builders), and ScreenCore::chartSeries becomes static. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- include/morph/ui/host.hpp | 1 + include/morph/ui/interpreter.hpp | 142 ++-- include/morph/ui/preference_sync.hpp | 1 + scripts/check_install_export.sh | 4 + src/ui/interpreter.cpp | 1058 +++++++++++++++--------- tests/test_push_cache.cpp | 1 + tests/test_ui_interpreter_commands.cpp | 1 + tests/ui_interpreter_support.hpp | 1 + 8 files changed, 756 insertions(+), 453 deletions(-) diff --git a/include/morph/ui/host.hpp b/include/morph/ui/host.hpp index bf549b01b..75abc6b06 100644 --- a/include/morph/ui/host.hpp +++ b/include/morph/ui/host.hpp @@ -17,6 +17,7 @@ #include #include +#include "../core/bridge.hpp" #include "../core/executor.hpp" #include "../reactive/runtime.hpp" #include "../reactive/signal.hpp" diff --git a/include/morph/ui/interpreter.hpp b/include/morph/ui/interpreter.hpp index 86d5a010d..61ae56277 100644 --- a/include/morph/ui/interpreter.hpp +++ b/include/morph/ui/interpreter.hpp @@ -14,7 +14,18 @@ #include #include #include +#include #include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include #include #include #include @@ -26,32 +37,6 @@ #include #include -#include "../core/backend.hpp" -#include "../core/bridge.hpp" -#include "../core/completion.hpp" -#include "../core/wire.hpp" -#include "../forms/engine/collection.hpp" -#include "../forms/engine/collection_view.hpp" -#include "../forms/engine/field_model.hpp" -#include "../forms/engine/form_session.hpp" -#include "../forms/engine/form_view.hpp" -#include "../forms/engine/wizard.hpp" -#include "../forms/engine/wizard_view.hpp" -#include "../reactive/runtime.hpp" -#include "../reactive/scheduler.hpp" -#include "../reactive/scope.hpp" -#include "../reactive/signal.hpp" -#include "../ui/backend.hpp" -#include "chart_scale.hpp" -#include "dev_tools.hpp" -#include "document.hpp" -#include "expression.hpp" -#include "locale_table.hpp" -#include "message.hpp" -#include "mount.hpp" -#include "value.hpp" -#include "view.hpp" - /// @file /// @brief The UI document interpreter: `Interpreter::mount` turns a loaded `Document` into reactive state and a view /// tree, mounts it through `Mounted` on any `IViewBackend`, and runs its queries, mutations, relations and @@ -59,8 +44,42 @@ /// scripted fake in a test); what only the application can do goes through an `InterpreterHost`; what /// screens share — the query cache, the principal's permissions, the formatting facts — is a `Session`. +namespace morph { + +namespace bridge { +class Bridge; +enum class BindSharing : std::uint8_t; +} // namespace bridge + +namespace wire { +struct ChangesBody; +struct EventBody; +struct InstanceTopic; +struct WatchBody; +} // namespace wire + +namespace effects { +struct RecordChange; +} // namespace effects + +namespace forms { +class CollectionSession; +class FieldState; +class FieldView; +class FormSession; +class WizardSession; +struct FieldSpec; +struct FormSessionOptions; +struct FormViewOptions; +} // namespace forms + +} // namespace morph + namespace morph::ui { +class Mounted; +struct ChartRange; + // --------------------------------------------------------------------------------------------------------------- // Dispatch // --------------------------------------------------------------------------------------------------------------- @@ -156,27 +175,7 @@ class MORPH_API BridgeDispatcher final : public Dispatcher { std::string const& instanceKey) override; private: - class Channel final : public ModelChannel { - public: - // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the type id, then the key, as `bind` takes them. - Channel(bridge::Bridge& bridge, exec::IExecutor* cbExec, Evaluator evaluator, std::string const& typeId, - bridge::BindSharing sharing, std::string const& instanceKey) - : _cbExec{cbExec}, - _evaluator{std::move(evaluator)}, - _typeId{typeId}, - _handler{bridge, cbExec, typeId, sharing, instanceKey} {} - - [[nodiscard]] async::Completion execute(std::string const& actionId, std::string const& bodyJson, - CallOptions options) override; - - [[nodiscard]] ChannelFacts facts() const override; - - private: - exec::IExecutor* _cbExec; - Evaluator _evaluator; - std::string _typeId; - bridge::RawHandler _handler; - }; + class Channel; bridge::Bridge* _bridge; exec::IExecutor* _cbExec; @@ -228,8 +227,8 @@ struct InlineFile { inline constexpr std::size_t kDefaultInlineFileBytes = std::size_t{1024} * 1024; /// @brief The largest inline cap a session takes: base64 grows bytes by 4/3, and 64 KiB of an envelope are left for -/// the rest of the body, so the encoded file still fits `wire::kMaxEnvelopeBytes`. -inline constexpr std::size_t kMaxInlineFileBytes = (wire::kMaxEnvelopeBytes - (std::size_t{64} * 1024)) * 3 / 4; +/// the rest of the body, so the encoded file still fits `wire::kMaxEnvelopeBytes` (8 MiB). +inline constexpr std::size_t kMaxInlineFileBytes = ((std::size_t{8} * 1024 * 1024) - (std::size_t{64} * 1024)) * 3 / 4; /// @brief What the application answers for the commands a document cannot carry out alone (spec 6). Every default /// answers "not supported", which the interpreter reports as a diagnostic. @@ -428,7 +427,7 @@ enum class PatchMiss : std::uint8_t { /// @param key The row's id. /// @param with The new content, merged over the row. /// @return The new value, or why it is unchanged. -// NOLINTBEGIN(bugprone-easily-swappable-parameters): a list, a key and a row are distinct roles of one type. +// NOLINTNEXTLINE(bugprone-easily-swappable-parameters): a list, a key and a row are distinct roles of one type. [[nodiscard]] MORPH_API std::expected patchRows(Value const& value, std::string_view listMember, Value const& key, Value const& with); @@ -1141,22 +1140,17 @@ struct TableView { }; /// @brief An element's live values (spec 5 §6). -struct ElementState { +struct MORPH_API ElementState { /// @brief The element's state before any user action. /// @param runtime The runtime. - explicit ElementState(reactive::Runtime& runtime) - : draft{runtime}, - committed{runtime}, - edited{runtime, false}, - touched{runtime, false}, - focused{runtime, false}, - open{runtime, false}, - submitted{runtime, false}, - selection{runtime, Value{ValueList{}}}, - sort{runtime, Value{ValueList{}}}, - activeKey{runtime}, - checksVersion{runtime, 0}, - inner{runtime, nullptr} {} + explicit ElementState(reactive::Runtime& runtime); + + /// @brief Destroys the element's state, and the sessions it owns. + ~ElementState(); + ElementState(ElementState const&) = delete; + ElementState& operator=(ElementState const&) = delete; + ElementState(ElementState&&) = delete; + ElementState& operator=(ElementState&&) = delete; /// @brief The node. DocNode const* node = nullptr; @@ -2042,6 +2036,10 @@ class MORPH_API ScreenCore { /// @return The value, or nothing for a state that starts from its init. [[nodiscard]] std::optional keptState(RtScope const& scope, StateDecl const& decl) const; + /// @brief What a form session submits through; the same type as `forms::Submitter`. + using FormSubmitter = + std::function(std::string_view actionType, std::string bodyJson)>; + private: void wireElement(ElementState& element); void wireErrors(ElementState& element); @@ -2131,9 +2129,9 @@ class MORPH_API ScreenCore { ChartRange chartFixedRange(DocNode const& node, RtScope const& scope, Bindings const* bindings, std::optional& unit, ChartRange const& range); /// The drawn series: each point at its own `x` when @p positioned, else at its index, clipped to @p range. - void chartSeries(ChartData& data, DocNode const& node, RtScope const& scope, Bindings const* bindings, - std::vector>& series, bool positioned, - ChartRange const& range) const; + static void chartSeries(ChartData& data, DocNode const& node, RtScope const& scope, Bindings const* bindings, + std::vector>& series, bool positioned, + ChartRange const& range); /// A form field's control drawn by the host component its overlay names, with the built-in control as the /// fallback. Node fieldComponent(forms::FieldView const& view, DocNode const& overlay, LowerCtx const& ctx); @@ -2151,8 +2149,8 @@ class MORPH_API ScreenCore { CustomizePoint const& spec, std::function const& choose); void wireForm(ElementState& element); Node lowerForm(DocNode const& node, LowerCtx const& ctx, ElementState* element); - [[nodiscard]] forms::Submitter aliasCalls(ModelAlias* alias); - [[nodiscard]] forms::Submitter aliasSubmits(ModelAlias* alias, std::string read = {}); + [[nodiscard]] FormSubmitter aliasCalls(ModelAlias* alias); + [[nodiscard]] FormSubmitter aliasSubmits(ModelAlias* alias, std::string read = {}); [[nodiscard]] forms::FormSessionOptions engineOptions() const; void wireComposite(ElementState& element); Node lowerComposite(DocNode const& node, LowerCtx const& ctx, ElementState* element); @@ -2609,7 +2607,7 @@ class MORPH_API Screen { std::unique_ptr _core; std::shared_ptr _scope; - std::optional _mounted; + std::unique_ptr _mounted; // The head's parts, bound in the screen scope. std::vector _headStatus; detail::ActionModels _headActions; @@ -2834,8 +2832,8 @@ namespace detail { /// @param payload The payload, as the backend reports it. /// @param type The `value` prop's type. /// @return The wire value, or why the payload is not one. -[[nodiscard]] MORPH_API std::expected changeWire(std::string const& payload, - std::string_view type); +[[nodiscard]] MORPH_API std::expected changeWire(std::string const& payload, + std::string_view type); } // namespace detail diff --git a/include/morph/ui/preference_sync.hpp b/include/morph/ui/preference_sync.hpp index 8436487ca..5d317f00f 100644 --- a/include/morph/ui/preference_sync.hpp +++ b/include/morph/ui/preference_sync.hpp @@ -11,6 +11,7 @@ #include #include +#include "../core/bridge.hpp" #include "../core/callback_scope.hpp" #include "../core/completion.hpp" #include "document.hpp" diff --git a/scripts/check_install_export.sh b/scripts/check_install_export.sh index b08aff015..31fcb59a5 100755 --- a/scripts/check_install_export.sh +++ b/scripts/check_install_export.sh @@ -274,6 +274,10 @@ int main() { if (morph::ui::routeOfFragment(morph::ui::fragmentOf("orders/42")) != "orders/42") { return 1; } + // A call into the interpreter's compiled half. + if (morph::ui::detail::base64Size("AQID") != 3) { + return 1; + } std::printf("morph %d.%d.%d consumed from the install prefix\n", MORPH_VERSION_MAJOR, MORPH_VERSION_MINOR, MORPH_VERSION_PATCH); return 0; diff --git a/src/ui/interpreter.cpp b/src/ui/interpreter.cpp index dcf0faa68..669d5f5c2 100644 --- a/src/ui/interpreter.cpp +++ b/src/ui/interpreter.cpp @@ -52,8 +52,49 @@ namespace morph::ui { +static_assert(kMaxInlineFileBytes == (wire::kMaxEnvelopeBytes - (std::size_t{64} * 1024)) * 3 / 4, + "the inline cap must stay tied to the wire envelope"); + +class BridgeDispatcher::Channel final : public ModelChannel { +public: + // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the type id, then the key, as `bind` takes them. + Channel(bridge::Bridge& bridge, exec::IExecutor* cbExec, Evaluator evaluator, std::string const& typeId, + bridge::BindSharing sharing, std::string const& instanceKey) + : _cbExec{cbExec}, + _evaluator{std::move(evaluator)}, + _typeId{typeId}, + _handler{bridge, cbExec, typeId, sharing, instanceKey} {} + + [[nodiscard]] async::Completion execute(std::string const& actionId, std::string const& bodyJson, + CallOptions options) override; + + [[nodiscard]] ChannelFacts facts() const override; + +private: + exec::IExecutor* _cbExec; + Evaluator _evaluator; + std::string _typeId; + bridge::RawHandler _handler; +}; + namespace detail { +ElementState::ElementState(reactive::Runtime& runtime) + : draft{runtime}, + committed{runtime}, + edited{runtime, false}, + touched{runtime, false}, + focused{runtime, false}, + open{runtime, false}, + submitted{runtime, false}, + selection{runtime, Value{ValueList{}}}, + sort{runtime, Value{ValueList{}}}, + activeKey{runtime}, + checksVersion{runtime, 0}, + inner{runtime, nullptr} {} + +ElementState::~ElementState() = default; + [[nodiscard]] Value evalIn(RtScope const& scope, Bindings const* bindings, ExprPtr const& expr) { if (!expr) { return Value{}; @@ -216,12 +257,14 @@ void headCommandLists(Document const& doc, std::vector& lists) [[nodiscard]] bool statefulKind(std::string_view kind) { static constexpr std::array kStateful = { "textInput", "checkbox", "select", "dateTimeInput", "slider", "filePicker", - "dialog", "drawer", "table", "form", "collection", "wizard"}; + "dialog", "drawer", "table", "form", "collection", "wizard", + }; return listed(kStateful, kind); } } // namespace +// NOLINTNEXTLINE(modernize-use-string-view): callers keep the key as an owned string, in the log and in tests. [[nodiscard]] std::string commandKey(CommandKind kind) { switch (kind) { case CommandKind::Set: @@ -312,6 +355,7 @@ namespace { } // namespace +// NOLINTNEXTLINE(modernize-use-string-view): callers keep the kind as an owned string, in a reply's `kind`. [[nodiscard]] std::string defaultErrorKind(std::exception_ptr const& error) { try { std::rethrow_exception(error); @@ -385,10 +429,10 @@ namespace { return Value{std::move(merged)}; } -// NOLINTBEGIN(bugprone-easily-swappable-parameters): a list, a key and a row are distinct roles of one type. -[[nodiscard]] std::expected patchRows(Value const& value, std::string_view listMember, - Value const& key, Value const& with) { - // NOLINTEND(bugprone-easily-swappable-parameters) +[[nodiscard]] std::expected patchRows( + Value const& value, std::string_view listMember, + // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): a list, a key and a row are distinct roles of one type. + Value const& key, Value const& with) { ValueRecord const* const record = listMember.empty() ? nullptr : value.asRecord(); if (!listMember.empty() && (record == nullptr || !record->contains(listMember))) { return std::unexpected(PatchMiss::NoList); @@ -601,6 +645,7 @@ std::shared_ptr BridgeDispatcher::bind(std::string const& typeId, std::string const& instanceKey) { return std::make_shared(*_bridge, _cbExec, _evaluator, typeId, sharing, instanceKey); } + async::Completion BridgeDispatcher::Channel::execute(std::string const& actionId, std::string const& bodyJson, CallOptions options) { if (options.evaluate) { @@ -613,9 +658,12 @@ async::Completion BridgeDispatcher::Channel::execute(std::string co } return _handler.execute(actionId, bodyJson); } + ChannelFacts BridgeDispatcher::Channel::facts() const { return ChannelFacts{.instanceId = _handler.instanceId(), .primary = _handler.primary()}; } +// NOLINTBEGIN(performance-unnecessary-value-param,bugprone-easily-swappable-parameters): every default below ignores +// its arguments, so each keeps the parameter types of the interface it implements. bool InterpreterHost::navigate(NavigateRequest const& request, std::function onResult, std::function onCancel) { static_cast(request); @@ -623,40 +671,48 @@ bool InterpreterHost::navigate(NavigateRequest const& request, std::function(onCancel); return false; } + bool InterpreterHost::closeSelf(std::string const& screen, std::optional result) { static_cast(screen); static_cast(result); return false; } + bool InterpreterHost::hostCommand(std::string const& name, Value const& args) { static_cast(name); static_cast(args); return false; } + bool InterpreterHost::switchBackend(std::string const& name, std::function)> done) { static_cast(name); static_cast(done); return false; } + void InterpreterHost::resetPrefs(std::string const& screen, std::string const& point) { static_cast(screen); static_cast(point); } + bool InterpreterHost::notify(std::string const& text, std::string const& role) { static_cast(text); static_cast(role); return false; } + bool InterpreterHost::signIn(Value const& reply) { static_cast(reply); return false; } + bool InterpreterHost::setAppValue(std::string const& name, Value const& value) { static_cast(name); static_cast(value); return false; } + bool InterpreterHost::upload(Value const& file, std::function progress, std::function)> done) { static_cast(file); @@ -664,10 +720,12 @@ bool InterpreterHost::upload(Value const& file, std::function progr static_cast(done); return false; } + bool InterpreterHost::uploadFor(UploadRequest const& request, std::function progress, std::function)> done) { return upload(request.file, std::move(progress), std::move(done)); } + bool InterpreterHost::download(Value const& file, std::string const& option, Value const& name, std::function)> done) { static_cast(file); @@ -676,6 +734,7 @@ bool InterpreterHost::download(Value const& file, std::string const& option, Val static_cast(done); return false; } + bool InterpreterHost::readFile(Value const& file, std::size_t maxBytes, std::function)> done) { static_cast(file); @@ -683,6 +742,7 @@ bool InterpreterHost::readFile(Value const& file, std::size_t maxBytes, static_cast(done); return false; } + bool InterpreterHost::saveFile(InlineFile const& file, std::string const& option, std::function)> done) { static_cast(file); @@ -690,11 +750,14 @@ bool InterpreterHost::saveFile(InlineFile const& file, std::string const& option static_cast(done); return false; } + void InterpreterHost::preferenceChanged(std::string const& screen, std::string const& point, Value const& value) { static_cast(screen); static_cast(point); static_cast(value); } +// NOLINTEND(performance-unnecessary-value-param,bugprone-easily-swappable-parameters) + bool Session::can(std::string_view action) const { static constexpr std::string_view kHostPrefix = "host:"; if (action.starts_with(kHostPrefix)) { @@ -705,10 +768,12 @@ bool Session::can(std::string_view action) const { } return _permitted.get().contains(action); } + void Session::setFormatLocale(std::string tag) { _formatLocale = std::move(tag); applyFacts(_format.peek()->locale); } + std::shared_ptr Session::scopedFormatting(std::string_view tag) const { FormatContext next = *_format.get(); LocaleFacts const& facts = localeFacts(tag); @@ -719,9 +784,11 @@ std::shared_ptr Session::scopedFormatting(std::string_view next.dateTimePattern = _declaredDateTime.empty() ? std::string{facts.dateTimePattern} : _declaredDateTime; return std::make_shared(std::move(next)); } + bool Session::firstUnlistedLocale(std::string const& tag) { return findLocaleFacts(tag) == nullptr && _unlistedLocales.insert(tag).second; } + void Session::setFormatting(FormatContext format) { // One batch, so an effect never sees the new `env.locale` beside the old facts, and runs once. _runtime->batch([this, &format] { @@ -729,6 +796,7 @@ void Session::setFormatting(FormatContext format) { _format.set(std::make_shared(std::move(format))); }); } + void Session::setDatePatterns(std::string date, std::string dateTime) { _declaredDate = std::move(date); _declaredDateTime = std::move(dateTime); @@ -737,29 +805,35 @@ void Session::setDatePatterns(std::string date, std::string dateTime) { next.dateTimePattern = _declaredDateTime.empty() ? _localeDateTime : _declaredDateTime; setFormatting(std::move(next)); } + void Session::setTranslations(render::TranslationProvider translations) { FormatContext next = *_format.peek(); next.translations = std::move(translations); setFormatting(std::move(next)); } + void Session::setEnvironment(ValueRecord values) { values.insert_or_assign("locale", Value{_format.peek()->locale}); _env.set(std::move(values)); } + void Session::setEnvironmentValue(std::string const& name, Value value) { ValueRecord env = _env.peek(); env.insert_or_assign(name, std::move(value)); _env.set(std::move(env)); } + void Session::setHostCommands(HostCommands commands) { _hostCommandRunner = std::move(commands.run); _hostCommandNames.set(std::move(commands.available)); } + std::function const& Session::hostCommandRunner() const noexcept { return _hostCommandRunner; } + Value Session::client(ExprKind form, std::string_view name) const { - ValueRecord const& values = [&]() -> ValueRecord const& { + ValueRecord const& values = [&] -> ValueRecord const& { if (form == ExprKind::Env) { return _env.get(); } @@ -768,6 +842,7 @@ Value Session::client(ExprKind form, std::string_view name) const { auto const found = values.find(name); return found == values.end() ? Value{} : found->second; } + void Session::clear() { _runtime->batch([this] { for (auto const& [key, entry] : _entries) { @@ -782,14 +857,16 @@ void Session::clear() { } }); } + void Session::prefetch(std::shared_ptr const& channel, std::string const& token, std::string const& typeId, std::string const& action, Value const& body) { - auto entry = acquire(token, typeId, action, false, body); + auto const entry = acquire(token, typeId, action, false, body); if (!entry->pending.peek() && (!entry->hasValue.peek() || entry->stale)) { fetch(entry, channel); } release(entry); } + void Session::asUser(std::function const& body) { ++_userDepth; try { @@ -800,10 +877,12 @@ void Session::asUser(std::function const& body) { } --_userDepth; } + std::string Session::cacheKey(std::string const& token, std::string const& typeId, std::string const& action, bool evaluate, std::string const& body) { return typeId + '\x1f' + token + '\x1f' + (evaluate ? "evaluate:" : "") + action + '\x1f' + body; } + std::shared_ptr Session::acquire(std::string const& token, std::string const& typeId, std::string const& action, bool evaluate, Value const& body) { std::string const text = detail::canonicalJson(body); @@ -832,6 +911,7 @@ std::shared_ptr Session::acquire(std::string const& token, s found->second->evict.cancel(); return found->second; } + void Session::release(std::shared_ptr const& entry) { if (--entry->users > 0 || _options.scheduler == nullptr) { return; @@ -846,6 +926,7 @@ void Session::release(std::shared_ptr const& entry) { } }); } + void Session::fetch(std::shared_ptr const& entry, std::shared_ptr const& channel) { // The watch goes out before the read, on the same connection, so a change committed after the read is // seen as an event. @@ -877,10 +958,12 @@ void Session::fetch(std::shared_ptr const& entry, std::share settleFailure(*entry, detail::failureText(error), classify(error), detail::refusalValue(error)); } } + void Session::confirm(detail::CacheEntry& entry, Value const& confirmed) { entry.confirmed = detail::withoutFields(confirmed, entry.secretFields); showLayers(entry); } + void Session::showLayers(detail::CacheEntry& entry) { Value shown = entry.confirmed; for (detail::OptimisticLayer const& layer : entry.layers) { @@ -891,21 +974,25 @@ void Session::showLayers(detail::CacheEntry& entry) { noteWrite(); entry.value.set(std::move(shown)); } + std::string Session::classify(std::exception_ptr const& error) const { return _options.classify ? _options.classify(error) : detail::defaultErrorKind(error); } + std::chrono::milliseconds Session::now() const { if (_options.clock) { return _options.clock(); } return std::chrono::duration_cast(std::chrono::steady_clock::now().time_since_epoch()); } + void Session::markStale(detail::CacheEntry& entry) { entry.stale = true; if (entry.pending.peek()) { entry.refetchAfter = true; } } + SessionOptions Session::checkedOptions(SessionOptions options) { if (options.maxInlineFileBytes == 0 || options.maxInlineFileBytes > kMaxInlineFileBytes) { throw std::invalid_argument{"morph::ui::Session: maxInlineFileBytes is " + @@ -914,6 +1001,7 @@ SessionOptions Session::checkedOptions(SessionOptions options) { } return options; } + void Session::settleReply(detail::CacheEntry& entry, std::string const& reply) { auto json = parseJson(reply); auto value = json ? valueFromJson(*json) : std::unexpected(json.error()); @@ -936,6 +1024,7 @@ void Session::settleReply(detail::CacheEntry& entry, std::string const& reply) { } }); } + void Session::settleFailure(detail::CacheEntry& entry, std::string text, std::string kind, Value refusal) { _runtime->batch([&] { noteWrite(); @@ -945,6 +1034,7 @@ void Session::settleFailure(detail::CacheEntry& entry, std::string text, std::st entry.pending.set(false); }); } + void Session::applyFacts(std::string locale) { LocaleFacts const& facts = localeFacts(_formatLocale.empty() ? locale : _formatLocale); _localeDate = std::string{facts.datePattern}; @@ -957,6 +1047,7 @@ void Session::applyFacts(std::string locale) { next.dateTimePattern = _declaredDateTime.empty() ? _localeDateTime : _declaredDateTime; setFormatting(std::move(next)); } + Screen::~Screen() { try { if (Commands const* const commands = lifecycleList("onUnmount")) { @@ -972,12 +1063,14 @@ Screen::~Screen() { _headTools.clear(); _scope.reset(); } + Widget& Screen::root() const { if (!_mounted) { throw std::logic_error{"the screen is not mounted"}; } return _mounted->root(); } + Value Screen::read(Json const& expression) const { auto parsed = parseExpression(expression); if (!parsed) { @@ -985,6 +1078,7 @@ Value Screen::read(Json const& expression) const { } return detail::evalIn(*_scope, nullptr, *parsed); } + auto Screen::boundAliases() const -> std::vector { std::vector bound; for (auto const& alias : _scope->models) { @@ -998,30 +1092,38 @@ auto Screen::boundAliases() const -> std::vector { } return bound; } + std::vector Screen::status() const { std::vector shown; for (detail::BadgeModel const& badge : _headStatus) { if (badge.visible.evaluate()) { shown.push_back(HeadBadge{ - .text = badge.text.evaluate(), .tone = badge.tone.evaluate(), .icon = badge.icon.evaluate()}); + .text = badge.text.evaluate(), + .tone = badge.tone.evaluate(), + .icon = badge.icon.evaluate(), + }); } } return shown; } + std::vector Screen::actions() const { std::vector shown; for (detail::ActionModel const& action : _headActions) { if (action.visible.evaluate()) { - shown.push_back(HeadAction{.id = action.id, - .label = action.label.evaluate(), - .icon = action.icon.evaluate(), - .iconOnly = action.iconOnly.evaluate(), - .emphasis = action.emphasis, - .enabled = action.enabled.evaluate()}); + shown.push_back(HeadAction{ + .id = action.id, + .label = action.label.evaluate(), + .icon = action.icon.evaluate(), + .iconOnly = action.iconOnly.evaluate(), + .emphasis = action.emphasis, + .enabled = action.enabled.evaluate(), + }); } } return shown; } + bool Screen::runAction(std::string_view actionId) { auto const found = std::ranges::find(_headActions, actionId, &detail::ActionModel::id); if (found == _headActions.end()) { @@ -1039,12 +1141,14 @@ bool Screen::runAction(std::string_view actionId) { } return true; } + std::string Screen::menuLabel() const { if (!_core->doc().menuLabel) { return "More actions"; } return detail::textOf(detail::evalIn(*_scope, nullptr, _core->doc().menuLabel), _scope->formatting()); } + bool Screen::chooseMenuEntry(std::string_view entryId) { FoundEntry const found = runtime().untracked([&] { return findHeadEntry(_headMenu, entryId, FoundEntry{}); }); if (found.model == nullptr) { @@ -1061,6 +1165,7 @@ bool Screen::chooseMenuEntry(std::string_view entryId) { } return true; } + std::vector Screen::tools() const { std::vector shown; for (detail::HeadToolModel const& tool : _headTools) { @@ -1068,18 +1173,21 @@ std::vector Screen::tools() const { continue; } bool const search = tool.kind == HeadToolKind::Search; - shown.push_back(HeadTool{.id = tool.id, - .kind = tool.kind, - .label = tool.label.evaluate(), - .value = search ? tool.value.evaluate() : std::string{}, - .placeholder = search ? tool.placeholder.evaluate() : std::string{}, - .options = search ? std::vector{} : tool.options.evaluate(), - .selected = search ? std::nullopt : tool.selected.evaluate(), - .width = tool.width, - .enabled = tool.enabled.evaluate()}); + shown.push_back(HeadTool{ + .id = tool.id, + .kind = tool.kind, + .label = tool.label.evaluate(), + .value = search ? tool.value.evaluate() : std::string{}, + .placeholder = search ? tool.placeholder.evaluate() : std::string{}, + .options = search ? std::vector{} : tool.options.evaluate(), + .selected = search ? std::nullopt : tool.selected.evaluate(), + .width = tool.width, + .enabled = tool.enabled.evaluate(), + }); } return shown; } + bool Screen::editTool(std::string_view toolId, Value const& value) { detail::HeadToolModel const* const tool = usableTool(toolId); if (tool == nullptr) { @@ -1092,6 +1200,7 @@ bool Screen::editTool(std::string_view toolId, Value const& value) { tool->edit(value); return true; } + bool Screen::submitTool(std::string_view toolId) { detail::HeadToolModel const* const tool = usableTool(toolId); if (tool == nullptr) { @@ -1104,15 +1213,18 @@ bool Screen::submitTool(std::string_view toolId) { tool->submit(Value{runtime().untracked([&] { return tool->value.evaluate(); })}); return true; } + bool Screen::dirty() const { Value const value = detail::evalIn(*_scope, nullptr, _core->doc().dirty); bool const* const flag = value.asBool(); return flag != nullptr && *flag; } + bool Screen::requestClose() { std::shared_ptr const cancelled = beginClose(); return cancelled == nullptr || !*cancelled; } + std::shared_ptr Screen::beginClose() { Commands const* const commands = lifecycleList("onClose"); if (commands == nullptr) { @@ -1120,11 +1232,13 @@ std::shared_ptr Screen::beginClose() { } return runCommandsFlag(*commands); } + void Screen::runLifecycle(std::string_view key) { if (Commands const* const commands = lifecycleList(key)) { runCommands(*commands); } } + bool Screen::setPreference(std::string const& point, Value value) { auto const found = _core->doc().customize.find(point); if (found == _core->doc().customize.end() || !fits(found->second, value)) { @@ -1135,28 +1249,36 @@ bool Screen::setPreference(std::string const& point, Value value) { _core->prefs.set(std::move(prefs)); return true; } + std::map> Screen::ownState() const { std::map> states; for (auto const& slot : _scope->states) { if (slot->value) { - states.insert_or_assign(slot->decl->name, detail::ScreenCore::KeptState{.type = slot->decl->type.name(), - .value = slot->value->peek()}); + states.insert_or_assign(slot->decl->name, detail::ScreenCore::KeptState{ + .type = slot->decl->type.name(), + .value = slot->value->peek(), + }); } } return states; } + Commands const* Screen::lifecycleList(std::string_view key) const { auto const found = _core->doc().lifecycle.find(key); return found == _core->doc().lifecycle.end() ? nullptr : &found->second; } + std::shared_ptr Screen::runCommandsFlag(Commands const& commands) { - detail::CommandCtx const ctx{.scope = _scope, - .bindings = std::make_shared(), - .cancelClose = std::make_shared(false), - .boundary = nullptr}; + detail::CommandCtx const ctx{ + .scope = _scope, + .bindings = std::make_shared(), + .cancelClose = std::make_shared(false), + .boundary = nullptr, + }; _core->runtime().batch([&] { _core->runList(commands, ctx, {}); }); return ctx.cancelClose; } + bool Screen::fits(CustomizePoint const& point, Value const& value) { if (point.kind == "choice") { std::string const* const text = value.asString(); @@ -1167,9 +1289,11 @@ bool Screen::fits(CustomizePoint const& point, Value const& value) { } return true; } + bool Screen::listed(std::span options, std::string const& text) { return std::ranges::find(options, text) != options.end(); } + detail::HeadToolModel const* Screen::usableTool(std::string_view toolId) const { auto const found = std::ranges::find(_headTools, toolId, &detail::HeadToolModel::id); if (found == _headTools.end()) { @@ -1184,12 +1308,15 @@ detail::HeadToolModel const* Screen::usableTool(std::string_view toolId) const { } return &*found; } +// NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. auto Screen::findHeadEntry(std::vector const& level, std::string_view entryId, FoundEntry const& outer) -> FoundEntry { for (detail::HeadMenuModel const& model : level) { - FoundEntry const here{.model = &model, - .visible = outer.visible && model.item.visible.evaluate(), - .enabled = outer.enabled && model.item.enabled.evaluate()}; + FoundEntry const here{ + .model = &model, + .visible = outer.visible && model.item.visible.evaluate(), + .enabled = outer.enabled && model.item.enabled.evaluate(), + }; if (!model.id.empty() && model.id == entryId) { return here; } @@ -1199,6 +1326,7 @@ auto Screen::findHeadEntry(std::vector const& level, std: } return FoundEntry{}; } +// NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. std::vector Screen::shownHeadMenu(std::vector const& level) { std::vector shown; for (detail::HeadMenuModel const& model : level) { @@ -1212,21 +1340,24 @@ std::vector Screen::shownHeadMenu(std::vectordoc().lifecycle.find("onUnmount"); found != _core->doc().lifecycle.end()) { @@ -1240,12 +1371,15 @@ AppRoot::~AppRoot() { _core->session.setAppScope(nullptr); _scope.reset(); } + reactive::Computed> const& AppRoot::navigationBadges() const { return *_navigationBadges; } + PrincipalPlacement AppRoot::principalPlacement() const noexcept { return _core->doc().principalPlacement == "head" ? PrincipalPlacement::Head : PrincipalPlacement::Sidebar; } + Value AppRoot::read(Json const& expression) const { auto parsed = parseExpression(expression); if (!parsed) { @@ -1253,6 +1387,7 @@ Value AppRoot::read(Json const& expression) const { } return detail::evalIn(*_scope, nullptr, *parsed); } + auto AppRoot::query(std::string_view name) const -> QueryRead { detail::NameRef const* const found = _scope->find(name); if (found == nullptr || found->category != detail::NameCategory::Query) { @@ -1262,12 +1397,15 @@ auto AppRoot::query(std::string_view name) const -> QueryRead { Value const error = runtime.error(); Value const kind = runtime.errorKind(); std::string const* const kindText = kind.asString(); - return QueryRead{.value = runtime.value(), - .pending = runtime.pending(), - .failed = !error.isNull(), - .declared = true, - .denied = kindText != nullptr && *kindText == "denied"}; + return QueryRead{ + .value = runtime.value(), + .pending = runtime.pending(), + .failed = !error.isNull(), + .declared = true, + .denied = kindText != nullptr && *kindText == "denied", + }; } + bool AppRoot::setState(std::string_view name, Value value) { detail::NameRef const* const found = _scope->find(name); if (found == nullptr || found->category != detail::NameCategory::State) { @@ -1279,6 +1417,7 @@ bool AppRoot::setState(std::string_view name, Value value) { slot.value->set(std::move(value)); return true; } + bool AppRoot::runMutation(std::string_view name, Value body, std::function done) { detail::NameRef const* const found = _scope->find(name); if (found == nullptr || found->category != detail::NameCategory::Mutation) { @@ -1295,11 +1434,14 @@ bool AppRoot::runMutation(std::string_view name, Value body, std::function(), - .cancelClose = std::make_shared(false), - .boundary = nullptr}; + detail::CommandCtx const ctx{ + .scope = _scope, + .bindings = std::make_shared(), + .cancelClose = std::make_shared(false), + .boundary = nullptr, + }; _core->runtime().batch([&] { _core->runList(commands, ctx, {}); }); } @@ -1403,10 +1545,12 @@ void ScreenCore::runLifecycleOf(std::string_view key) { if (found == _doc->lifecycle.end() || !scope) { return; } - CommandCtx const ctx{.scope = scope, - .bindings = std::make_shared(), - .cancelClose = std::make_shared(false), - .boundary = nullptr}; + CommandCtx const ctx{ + .scope = scope, + .bindings = std::make_shared(), + .cancelClose = std::make_shared(false), + .boundary = nullptr, + }; runList(found->second, ctx, {}); } @@ -1445,10 +1589,12 @@ void ScreenCore::runEvent(Commands const* commands, LowerCtx const& ctx, Value e } auto bindings = std::make_shared(*ctx.bindings); bindings->push_back(Binding{.name = "event", .read = [event = std::move(event)] { return event; }}); - CommandCtx const command{.scope = ctx.scope, - .bindings = std::move(bindings), - .cancelClose = std::make_shared(false), - .boundary = ctx.boundary}; + CommandCtx const command{ + .scope = ctx.scope, + .bindings = std::move(bindings), + .cancelClose = std::make_shared(false), + .boundary = ctx.boundary, + }; session.asUser([&] { runtime().batch([&] { runList(*commands, command, {}); }); }); } @@ -1784,6 +1930,7 @@ namespace detail { } return canonicalJson(key); } + namespace { /// @brief The channel an alias is bound to for its current token, binding it when the token changed. @@ -2019,7 +2166,7 @@ std::shared_ptr QueryRuntime::channel() const { return channelOf(* // NOLINTNEXTLINE(readability-function-cognitive-complexity): the query's key, its fetch and its refresh triggers. void QueryRuntime::start() { RtScope& scope = *_scope; - auto& key = scope.nodes.computed([this]() -> Target { + auto& key = scope.nodes.computed([this] -> Target { Target target; if (_decl->when) { Value const when = evalIn(*_scope, nullptr, _decl->when); @@ -2045,7 +2192,7 @@ void QueryRuntime::start() { _key = &key; reactive::Scheduler* const scheduler = scope.core.session.options().scheduler; std::weak_ptr const alive = _alive; - scope.nodes.effect([this, &key, scheduler, alive, first = true]() mutable { + scope.nodes.effect([this, &key, scheduler, alive, first = true] mutable { Target target = key.get(); _scope->core.runtime().untracked([&] { if (first || target.idle || _decl->debounce <= 0 || scheduler == nullptr) { @@ -2098,7 +2245,7 @@ void QueryRuntime::switchTo(Target const& target) { } return; } - auto fresh = session.acquire(target.token, _typeId, _decl->action, _decl->evaluate, target.body); + auto const fresh = session.acquire(target.token, _typeId, _decl->action, _decl->evaluate, target.body); _carried.set(std::move(shown)); _entry.set(fresh); if (old) { @@ -2218,7 +2365,7 @@ MutationRuntime::~MutationRuntime() { // NOLINTBEGIN(misc-no-recursion): a mutation's commands can run another mutation, and a serial queue sends its next // run as the last one settles. void MutationRuntime::run(Value body, std::shared_ptr bindings, RunDone done) { - auto run = std::make_shared(); + auto const run = std::make_shared(); run->body = std::move(body); run->bindings = std::move(bindings); run->done = std::move(done); @@ -2326,10 +2473,12 @@ void MutationRuntime::settle(std::shared_ptr const& run, std::optionalconcurrency != Concurrency::Latest || run->id == _latest; std::shared_ptr const scope = _scope->shared_from_this(); auto commandCtx = [&](Bindings extra) { - return CommandCtx{.scope = scope, - .bindings = std::make_shared(std::move(extra)), - .cancelClose = std::make_shared(false), - .boundary = nullptr}; + return CommandCtx{ + .scope = scope, + .bindings = std::make_shared(std::move(extra)), + .cancelClose = std::make_shared(false), + .boundary = nullptr, + }; }; Value delivered; bool succeeded = false; @@ -2543,7 +2692,7 @@ void ScreenCore::declare(RtScope& scope, ScopeDecl const* decl, std::vectormode) { case InstanceMode::Keyed: - raw->token = &scope.nodes.computed([&scope, raw]() -> std::string { + raw->token = &scope.nodes.computed([&scope, raw] -> std::string { std::string const key = instanceKeyText(evalIn(scope, nullptr, raw->decl->key)); return key.empty() ? std::string{} : "shared:" + key; }); @@ -2588,7 +2737,7 @@ void ScreenCore::declare(RtScope& scope, ScopeDecl const* decl, std::vector ModelAlias* { + auto const aliasOf = [&scope](std::string const& model) -> ModelAlias* { NameRef const* const found = scope.find(model); return found != nullptr && found->category == NameCategory::Model ? found->model : nullptr; }; @@ -2641,7 +2790,7 @@ void ScreenCore::declare(RtScope& scope, ScopeDecl const* decl, std::vectorwatches) { auto& source = scope.nodes.computed([&scope, expr = watch.on] { return evalIn(scope, nullptr, expr); }); - scope.nodes.effect([this, &scope, &source, watched = &watch, first = true]() mutable { + scope.nodes.effect([this, &scope, &source, watched = &watch, first = true] mutable { static_cast(source.get()); if (first) { first = false; @@ -2652,10 +2801,12 @@ void ScreenCore::declare(RtScope& scope, ScopeDecl const* decl, std::vector(), - .cancelClose = std::make_shared(false), - .boundary = nullptr}; + CommandCtx const ctx{ + .scope = scope.shared_from_this(), + .bindings = std::make_shared(), + .cancelClose = std::make_shared(false), + .boundary = nullptr, + }; if (user) { session.asUser([&] { runList(watched->body, ctx, {}); }); } else { @@ -2665,6 +2816,7 @@ void ScreenCore::declare(RtScope& scope, ScopeDecl const* decl, std::vector Value { + element.errors = &scope.nodes.computed([this, &element] -> Value { static_cast(element.checksVersion.get()); DocNode const& field = *element.node; RtScope const& owner = *element.scope; @@ -2902,6 +3055,7 @@ void ScreenCore::wireElement(ElementState& element) { element.view = &scope.nodes.computed([this, &element] { return tableView(element, nullptr); }); } } + namespace { /// @brief A table's sort as its element value reads it: the bound `sort` when the key binds one, else the table's @@ -3165,6 +3319,7 @@ TableView ScreenCore::tableView(ElementState const& element, Bindings const* bin view.last = static_cast(std::min(total, (view.page + 1) * *perPage)); return view; } + namespace { /// @brief A table's selection as its element value reads it: the bound `selection` when the key binds one, else @@ -3188,6 +3343,7 @@ namespace { auto value = valueFromJson(*json); return value ? *std::move(value) : Value{}; } + namespace { /// @brief One field of a form as a record: `value` (the encoded value, `null` while blank or invalid), `draft` (the @@ -3264,7 +3420,7 @@ Value ScreenCore::elementValue(ElementState const& element, std::string_view nam DocNode const& node = *element.node; RtScope const& scope = *element.scope; std::string_view const kind = node.kind; - auto flagOf = [&](std::string_view key, bool fallback) -> Value { + auto const flagOf = [&](std::string_view key, bool fallback) -> Value { ExprPtr const expr = node.prop(key); if (!expr) { return fallback; @@ -3273,8 +3429,8 @@ Value ScreenCore::elementValue(ElementState const& element, std::string_view nam bool const* const flag = value.asBool(); return flag != nullptr && *flag; }; - auto errors = [&]() -> Value { return element.errors->get(); }; - auto count = [](Value const& list) -> Value { + auto const errors = [&] -> Value { return element.errors->get(); }; + auto const count = [](Value const& list) -> Value { ValueList const* const items = list.asList(); return static_cast(items == nullptr ? 0 : items->size()); }; @@ -3422,8 +3578,8 @@ void ScreenCore::runList(Commands const& commands, CommandCtx const& ctx, Done d if (recording) { logList(commands); } - auto join = std::make_shared(Join{.left = commands.size() + 1, .ok = true, .done = std::move(done)}); - auto finish = [join](bool succeeded) { + auto const join = std::make_shared(Join{.left = commands.size() + 1, .ok = true, .done = std::move(done)}); + auto const finish = [join](bool succeeded) { join->ok = join->ok && succeeded; if (--join->left == 0) { join->done(join->ok); @@ -3441,8 +3597,8 @@ void ScreenCore::runOne(Command const& command, CommandCtx const& ctx, Done done done = [](bool) {}; } RtScope const& scope = *ctx.scope; - auto eval = [&](ExprPtr const& expr) { return evalIn(scope, ctx.bindings.get(), expr); }; - auto finish = [&done](bool succeeded) { done(succeeded); }; + auto const eval = [&](ExprPtr const& expr) { return evalIn(scope, ctx.bindings.get(), expr); }; + auto const finish = [&done](bool succeeded) { done(succeeded); }; switch (command.kind) { case CommandKind::Set: runSet(command, ctx, done); @@ -3500,11 +3656,13 @@ void ScreenCore::runOne(Command const& command, CommandCtx const& ctx, Done done return; } case CommandKind::Navigate: { - NavigateRequest const request{.screen = command.target, - .route = eval(command.extra), - .params = eval(command.value), - .as = command.option, - .call = false}; + NavigateRequest const request{ + .screen = command.target, + .route = eval(command.extra), + .params = eval(command.value), + .as = command.option, + .call = false, + }; if (host == nullptr) { finish(unsupported(command, "`navigate`")); return; @@ -3519,12 +3677,14 @@ void ScreenCore::runOne(Command const& command, CommandCtx const& ctx, Done done CommandCtx const kept = detached(ctx); auto onResult = [this, weak, kept, list = &command.commands](Value const& result) { if (auto const held = weak.lock()) { - auto bindings = std::make_shared(*kept.bindings); + auto const bindings = std::make_shared(*kept.bindings); bindings->push_back(Binding{.name = "event", .read = [result] { return result; }}); - CommandCtx const next{.scope = held, - .bindings = bindings, - .cancelClose = kept.cancelClose, - .boundary = kept.boundary}; + CommandCtx const next{ + .scope = held, + .bindings = bindings, + .cancelClose = kept.cancelClose, + .boundary = kept.boundary, + }; runtime().batch([&] { runList(*list, next, {}); }); } }; @@ -3620,12 +3780,14 @@ void ScreenCore::runOne(Command const& command, CommandCtx const& ctx, Done done case CommandKind::Seq: { // A step that waits for a reply keeps the rest of the sequence in that reply's handler, which the // dispatcher may hold past the screen: the sequence holds its scope weakly and stops once it is gone. - CommandCtx const inner = detached(CommandCtx{.scope = nullptr, - .bindings = std::make_shared(*ctx.bindings), - .cancelClose = ctx.cancelClose, - .boundary = ctx.boundary}); + CommandCtx const inner = detached(CommandCtx{ + .scope = nullptr, + .bindings = std::make_shared(*ctx.bindings), + .cancelClose = ctx.cancelClose, + .boundary = ctx.boundary, + }); std::weak_ptr const weak = ctx.scope; - auto step = std::make_shared>(); + auto const step = std::make_shared>(); *step = [this, inner, weak, list = &command.commands, done = std::move(done), weakStep = std::weak_ptr>{step}](std::size_t index) { auto const held = weak.lock(); @@ -3648,10 +3810,12 @@ void ScreenCore::runOne(Command const& command, CommandCtx const& ctx, Done done return; } case CommandKind::All: { - CommandCtx const inner{.scope = ctx.scope, - .bindings = std::make_shared(*ctx.bindings), - .cancelClose = ctx.cancelClose, - .boundary = ctx.boundary}; + CommandCtx const inner{ + .scope = ctx.scope, + .bindings = std::make_shared(*ctx.bindings), + .cancelClose = ctx.cancelClose, + .boundary = ctx.boundary, + }; runList(command.commands, inner, std::move(done)); return; } @@ -3714,7 +3878,7 @@ void ScreenCore::runMutation(Command const& command, CommandCtx const& ctx, Done done(false); return; } - RtScope const& declaring = *[&]() -> RtScope const* { + RtScope const& declaring = *[&] -> RtScope const* { for (RtScope const* candidate = &scope; candidate != nullptr; candidate = candidate->parent.get()) { if (candidate->names.contains(command.target)) { return candidate; @@ -3722,7 +3886,7 @@ void ScreenCore::runMutation(Command const& command, CommandCtx const& ctx, Done } return &scope; }(); - auto bodyFor = [&](Bindings const& bindings) { + auto const bodyFor = [&](Bindings const& bindings) { if (command.value) { return evalIn(scope, &bindings, command.value); } @@ -3754,7 +3918,7 @@ void ScreenCore::runMutation(Command const& command, CommandCtx const& ctx, Done bool ok = true; Done done; }; - auto state = std::make_shared(Each{.left = items.size(), .ok = true, .done = std::move(done)}); + auto const state = std::make_shared(Each{.left = items.size(), .ok = true, .done = std::move(done)}); std::vector bodies; std::vector> bound; for (Value const& item : items) { @@ -3777,7 +3941,7 @@ void ScreenCore::runMutation(Command const& command, CommandCtx const& ctx, Done return; } // An exclusive mutation refuses a run while another is in flight, so its elements go one after another. - auto step = std::make_shared>(); + auto const step = std::make_shared>(); *step = [&mutation, bodies, bound, state, weakStep = std::weak_ptr>{step}](std::size_t index) { if (index == bodies.size()) { @@ -3866,7 +4030,7 @@ void ScreenCore::runSet(Command const& command, CommandCtx const& ctx, Done cons void ScreenCore::runReset(Command const& command, CommandCtx const& ctx, Done const& done) { RtScope const& scope = *ctx.scope; NameRef const* const found = scope.find(command.target); - auto resetStates = [this](RtScope const& owner) { + auto const resetStates = [this](RtScope const& owner) { for (auto const& slot : owner.states) { if (slot->value) { Value init = runtime().untracked([&] { return evalIn(owner, nullptr, slot->decl->init); }); @@ -3918,6 +4082,7 @@ void ScreenCore::runHostCommand(Command const& command, CommandCtx const& ctx, D } done(known); } + namespace { // NOLINTNEXTLINE(readability-function-cognitive-complexity): a download and an upload, each settled. @@ -3990,7 +4155,7 @@ class TransferHold { if (text.size() % 4 == 1) { return std::nullopt; } - auto digitOf = [](char chr) -> int { + auto const digitOf = [](char chr) -> int { if (chr >= 'A' && chr <= 'Z') { return chr - 'A'; } @@ -4150,7 +4315,8 @@ std::optional ScreenCore::inlineDownload( .mediaType = command.mediaType ? textOf(evalIn(*ctx.scope, ctx.bindings.get(), command.mediaType), ctx.scope->formatting()) : std::string{}, - .bytes = *std::move(bytes)}; + .bytes = *std::move(bytes), + }; } // NOLINTNEXTLINE(readability-function-cognitive-complexity): one branch per outcome an upload can have. @@ -4314,6 +4480,7 @@ namespace { } return textOf(value, format); } + namespace { /// @brief An exact rational as the nearest double, unrounded. @@ -4372,6 +4539,7 @@ namespace { } return fallback; } + namespace { /// @brief A text role by name. @@ -4460,13 +4628,15 @@ constexpr std::string_view kRoleNames = if (value.isNull()) { return Tone::Neutral; } - static constexpr std::array, 5> kTones = {{ - {"neutral", Tone::Neutral}, - {"info", Tone::Info}, - {"ok", Tone::Ok}, - {"warn", Tone::Warn}, - {"err", Tone::Err}, - }}; + static constexpr std::array, 5> kTones = { + { + {"neutral", Tone::Neutral}, + {"info", Tone::Info}, + {"ok", Tone::Ok}, + {"warn", Tone::Warn}, + {"err", Tone::Err}, + }, + }; if (std::string const* const text = value.asString()) { // A loop, not std::ranges::find: an array's iterator is a pointer on some standard libraries and not on // others, so `auto` there reads differently to each. @@ -4516,14 +4686,17 @@ constexpr std::string_view kRoleNames = *badTone = true; } } - spans.push_back(TextSpan{.text = textOf(*text, format), - .strong = flag(run.field("strong")), - .mono = flag(run.field("mono")), - .tone = tone, - .action = flag(run.field("action"))}); + spans.push_back(TextSpan{ + .text = textOf(*text, format), + .strong = flag(run.field("strong")), + .mono = flag(run.field("mono")), + .tone = tone, + .action = flag(run.field("action")), + }); } return spans; } + namespace { /// @brief Whether a scope declares any name, so a node in it reads names the screen's own scope lacks. @@ -4593,6 +4766,7 @@ constexpr std::string_view kSpanToneReason = } return record->contains("fixed") || record->contains("stretch"); } + namespace { /// @brief An alignment by name, as the loader checked it: `start`, `center`, `end`, or stretch for none. @@ -4865,7 +5039,7 @@ Node ScreenCore::lowerAll(std::span nodes, LowerCtx const& ctx void ScreenCore::fillHolder(std::vector& children, std::string const& path) { for (Node& child : children) { if (layoutHintsOf(child).width.kind == Sizing::Kind::Percent) { - report(path, std::string{kPercentInHolder}); + report(path, kPercentInHolder); child = withWidth(child, Sizing::stretch(1)); } } @@ -4985,8 +5159,10 @@ KeyValueItem ScreenCore::keyValueItemOf(Value const& item, std::string const& pa FormatContext const& format = scope.formatting(); Value const* const label = item.field("label"); Value const* const value = item.field("value"); - KeyValueItem out{.label = label == nullptr ? std::string{} : textOf(*label, format), - .value = value == nullptr ? std::string{} : textOf(*value, format)}; + KeyValueItem out{ + .label = label == nullptr ? std::string{} : textOf(*label, format), + .value = value == nullptr ? std::string{} : textOf(*value, format), + }; if (Value const* const spans = item.field("spans")) { bool dropped = false; bool badTone = false; @@ -5013,8 +5189,10 @@ KeyValueItem ScreenCore::keyValueItemOf(Value const& item, std::string const& pa // description. Node ScreenCore::lowerGroup(DocNode const& node, LowerCtx const& ctx, ElementState* element, std::vector children) { - Text legend{.text = bindProp(ctx, node.prop("label"), std::string{}, stringOf), - .role = TextRole::Label}; + Text legend{ + .text = bindProp(ctx, node.prop("label"), std::string{}, stringOf), + .role = TextRole::Label, + }; legend.field.required = bindProp(ctx, node.prop("required"), false, boolOf); std::vector column; column.reserve(children.size() + 3); @@ -5028,22 +5206,26 @@ Node ScreenCore::lowerGroup(DocNode const& node, LowerCtx const& ctx, ElementSta column.push_back(ui::text(std::move(line))); } // The shown errors, one line each: a check that targets the group shows its message here. - auto shown = [this, element, scope = ctx.scope, bindings = ctx.bindings, errors = node.prop("errors")] { + auto const shown = [this, element, scope = ctx.scope, bindings = ctx.bindings, errors = node.prop("errors")] { return stringsOf(element != nullptr ? elementValue(*element, "shownErrors") : evalIn(*scope, bindings.get(), errors)); }; - Text messages{.text = slotProp([shown] { - std::string joined; - for (std::string const& message : shown()) { - joined += (joined.empty() ? "" : "\n") + message; - } - return joined; - }), - .role = TextRole::Error}; + Text messages{ + .text = slotProp([shown] { + std::string joined; + for (std::string const& message : shown()) { + joined += (joined.empty() ? "" : "\n") + message; + } + return joined; + }), + .role = TextRole::Error, + }; messages.common.visible = slotProp([shown] { return !shown().empty(); }); column.push_back(ui::text(std::move(messages))); - Column spec{.children = std::move(column), - .gap = static_cast(intOf(node.prop("gap") ? once(ctx, node.prop("gap")) : Value{}, 0))}; + Column spec{ + .children = std::move(column), + .gap = static_cast(intOf(node.prop("gap") ? once(ctx, node.prop("gap")) : Value{}, 0)), + }; commonOf(node, ctx, element, spec.common); if (spec.common.a11y.role.empty()) { spec.common.a11y.role = "group"; @@ -5091,7 +5273,7 @@ void ScreenCore::layoutOf(DocNode const& node, LowerCtx const& ctx, LayoutHints& layout.width = width != nullptr ? sizingOf(*width) : Sizing::content(); layout.height = height != nullptr ? sizingOf(*height) : Sizing::content(); if (layout.height.kind == Sizing::Kind::Percent) { - report(sizing->path, std::string{kPercentPlaces}); + report(sizing->path, kPercentPlaces); layout.height = Sizing::content(); } } else { @@ -5103,14 +5285,18 @@ void ScreenCore::layoutOf(DocNode const& node, LowerCtx const& ctx, LayoutHints& } layout.bleed = node.flag("bleed"); // Literal integers, checked at load. - for (auto const& [key, bound] : - {std::pair{"minWidth", &LayoutHints::minWidth}, std::pair{"maxWidth", &LayoutHints::maxWidth}, - std::pair{"minHeight", &LayoutHints::minHeight}, std::pair{"maxHeight", &LayoutHints::maxHeight}}) { + for (auto const& [key, bound] : { + std::pair{"minWidth", &LayoutHints::minWidth}, + std::pair{"maxWidth", &LayoutHints::maxWidth}, + std::pair{"minHeight", &LayoutHints::minHeight}, + std::pair{"maxHeight", &LayoutHints::maxHeight}, + }) { if (ExprPtr const expr = node.prop(key); expr != nullptr && expr->literal.asInt() != nullptr) { layout.*bound = static_cast(*expr->literal.asInt()); } } } + namespace { /// @brief Where a declaration is lowered, as a focus key reads it. @@ -5181,8 +5367,8 @@ void ScreenCore::commonOf(DocNode const& node, LowerCtx const& ctx, ElementState } for (DocNodePtr const& drag : node.partList("drag")) { ExprPtr const payload = drag->prop("payload"); - common.dragKey = slotProp>( - [scope = ctx.scope, bindings = ctx.bindings, payload]() -> std::optional { + common.dragKey = + slotProp>([scope = ctx.scope, bindings = ctx.bindings, payload] -> std::optional { Value const value = evalIn(*scope, bindings.get(), payload); return value.isNull() ? std::nullopt : std::optional{keyOf(value)}; }); @@ -5258,7 +5444,7 @@ MenuItem ScreenCore::menuItemOf(DocNode const& part, LowerCtx const& ctx) { item.keys = std::string{part.name("keys")}; if (ExprPtr const checked = part.prop("checked")) { item.checked = slotProp>( - [scope = ctx.scope, bindings = ctx.bindings, checked]() -> std::optional { + [scope = ctx.scope, bindings = ctx.bindings, checked] -> std::optional { Value const value = evalIn(*scope, bindings.get(), checked); bool const* const flag = value.asBool(); return flag == nullptr ? std::nullopt : std::optional{*flag}; @@ -5286,10 +5472,12 @@ std::vector ScreenCore::lowerHeadMenu(std::span std::vector models; models.reserve(parts.size()); for (DocNodePtr const& part : parts) { - models.push_back(HeadMenuModel{.id = part->id, - .path = part->path, - .item = menuItemOf(*part, ctx), - .items = lowerHeadMenu(part->partList("items"), ctx)}); + models.push_back(HeadMenuModel{ + .id = part->id, + .path = part->path, + .item = menuItemOf(*part, ctx), + .items = lowerHeadMenu(part->partList("items"), ctx), + }); } return models; } @@ -5313,7 +5501,8 @@ std::vector ScreenCore::lowerHeadTools(std::span(ctx, part->prop("enabled"), true, boolOf), .visible = bindProp(ctx, part->prop("visible"), true, boolOf), .edit = {}, - .submit = {}}; + .submit = {}, + }; if (ExprPtr const width = part->prop("width")) { if (std::int64_t const* const units = width->literal.asInt()) { model.width = static_cast(*units); @@ -5324,11 +5513,11 @@ std::vector ScreenCore::lowerHeadTools(std::spanprop("options")] { return selectOptions(evalIn(*scope, bindings.get(), options), scope->formatting()); }); - model.selected = slotProp>([scope = ctx.scope, bindings = ctx.bindings, - selected = part->prop("selected")]() -> std::optional { - Value const value = selected ? evalIn(*scope, bindings.get(), selected) : Value{}; - return value.isNull() ? std::nullopt : std::optional{keyOf(value)}; - }); + model.selected = slotProp>( + [scope = ctx.scope, bindings = ctx.bindings, selected = part->prop("selected")] -> std::optional { + Value const value = selected ? evalIn(*scope, bindings.get(), selected) : Value{}; + return value.isNull() ? std::nullopt : std::optional{keyOf(value)}; + }); } Commands const* const edited = part->event(search ? "onChange" : "onChoose"); model.edit = [this, ctx, edited](Value event) { runEvent(edited, ctx, std::move(event)); }; @@ -5346,15 +5535,17 @@ ActionModels ScreenCore::lowerActionParts(std::span parts, Low ActionModels models; models.reserve(parts.size()); for (DocNodePtr const& part : parts) { - ActionModel model{.id = part->id, - .path = part->path, - .label = bindProp(ctx, part->prop("label"), std::string{}, stringOf), - .icon = bindProp(ctx, part->prop("icon"), std::string{}, stringOf), - .iconOnly = bindProp(ctx, part->prop("iconOnly"), false, boolOf), - .emphasis = ButtonEmphasis::Normal, - .enabled = bindProp(ctx, part->prop("enabled"), true, boolOf), - .visible = bindProp(ctx, part->prop("visible"), true, boolOf), - .run = {}}; + ActionModel model{ + .id = part->id, + .path = part->path, + .label = bindProp(ctx, part->prop("label"), std::string{}, stringOf), + .icon = bindProp(ctx, part->prop("icon"), std::string{}, stringOf), + .iconOnly = bindProp(ctx, part->prop("iconOnly"), false, boolOf), + .emphasis = ButtonEmphasis::Normal, + .enabled = bindProp(ctx, part->prop("enabled"), true, boolOf), + .visible = bindProp(ctx, part->prop("visible"), true, boolOf), + .run = {}, + }; model.emphasis = emphasisNamed(part->name("emphasis")).value_or(ButtonEmphasis::Normal); if (Commands const* const commands = part->event("onClick")) { model.run = [this, ctx, commands] { runEvent(commands, ctx, Value{}); }; @@ -5367,11 +5558,13 @@ ActionModels ScreenCore::lowerActionParts(std::span parts, Low Node ScreenCore::actionBarOf(ActionModels actions) { ActionBar bar; for (ActionModel& action : actions) { - Button button{.label = action.label, - .emphasis = action.emphasis, - .onClick = std::move(action.run), - .common = {}, - .icon = action.icon.evaluate()}; + Button button{ + .label = action.label, + .emphasis = action.emphasis, + .onClick = std::move(action.run), + .common = {}, // NOLINT(readability-trailing-comma): the comma ends the designator, not the empty braces. + .icon = action.icon.evaluate(), + }; if (action.iconOnly.isBound() || action.iconOnly.constant()) { // The label is the button's name and tooltip; the caption is empty while the icon stands alone. button.label = Prop{[label = action.label, iconOnly = action.iconOnly] { @@ -5392,10 +5585,12 @@ std::vector ScreenCore::lowerBadgeParts(std::span std::vector badges; badges.reserve(parts.size()); for (DocNodePtr const& part : parts) { - badges.push_back(BadgeModel{.text = bindProp(ctx, part->prop("text"), std::string{}, stringOf), - .tone = bindProp(ctx, part->prop("tone"), Tone::Neutral, toneOf), - .icon = bindProp(ctx, part->prop("icon"), std::string{}, stringOf), - .visible = bindProp(ctx, part->prop("visible"), true, boolOf)}); + badges.push_back(BadgeModel{ + .text = bindProp(ctx, part->prop("text"), std::string{}, stringOf), + .tone = bindProp(ctx, part->prop("tone"), Tone::Neutral, toneOf), + .icon = bindProp(ctx, part->prop("icon"), std::string{}, stringOf), + .visible = bindProp(ctx, part->prop("visible"), true, boolOf), + }); } return badges; } @@ -5569,8 +5764,8 @@ std::optional ScreenCore::lowerWidget(DocNode const& node, LowerCtx const& } if (kind == "textInput") { std::string const commitOn = node.name("commitOn").empty() ? "change" : std::string{node.name("commitOn")}; - auto commit = [this, ctx, element, commitOn, onChange = node.event("onChange")](std::string const& when, - std::string const& text) { + auto const commit = [this, ctx, element, commitOn, onChange = node.event("onChange")]( + std::string const& when, std::string const& text) { if (commitOn != when) { return; } @@ -5614,8 +5809,12 @@ std::optional ScreenCore::lowerWidget(DocNode const& node, LowerCtx const& } // A multiline input shows no unit and no icon; a computed mode that turns out multiline is reported and // its unit and icon left out, so the mount never meets them there. The loader refuses a literal one. - for (std::string_view const key : {std::string_view{"unit"}, std::string_view{"icon"}, - std::string_view{"prefix"}, std::string_view{"decimals"}}) { + for (std::string_view const key : { + std::string_view{"unit"}, + std::string_view{"icon"}, + std::string_view{"prefix"}, + std::string_view{"decimals"}, + }) { if (ExprPtr const given = node.prop(key); given != nullptr && spec.mode == TextInputMode::Multiline) { report(given->path, "a multiline input shows no " + std::string{key}); } @@ -5645,11 +5844,14 @@ std::optional ScreenCore::lowerWidget(DocNode const& node, LowerCtx const& return ui::textInput(std::move(spec)); } if (kind == "checkbox") { - Checkbox spec{.label = kit.textProp("label"), .checked = slotProp([read = kit.read("checked")] { - Value const value = read(); - bool const* const flag = value.asBool(); - return flag != nullptr && *flag; - })}; + Checkbox spec{ + .label = kit.textProp("label"), + .checked = slotProp([read = kit.read("checked")] { + Value const value = read(); + bool const* const flag = value.asBool(); + return flag != nullptr && *flag; + }), + }; spec.onToggle = [this, ctx, element, onToggle = node.event("onToggle"), onChange = node.event("onChange")](bool checked) { // A toggle is a check box's commit, so it touches the box. @@ -5671,7 +5873,7 @@ std::optional ScreenCore::lowerWidget(DocNode const& node, LowerCtx const& Select spec; spec.options = slotProp>( [scope = ctx.scope, element] { return selectOptions(element->rows->get(), scope->formatting()); }); - spec.selected = slotProp>([read = kit.read("selected")]() -> std::optional { + spec.selected = slotProp>([read = kit.read("selected")] -> std::optional { Value const selected = read(); return selected.isNull() ? std::nullopt : std::optional{keyOf(selected)}; }); @@ -5745,7 +5947,7 @@ std::optional ScreenCore::lowerWidget(DocNode const& node, LowerCtx const& std::string const valuePath = pointerAppend(node.path, "value"); std::int32_t const offsetMinutes = format.utcOffsetMinutes; spec.value = slotProp>([this, element, offsetMinutes, - valuePath]() -> std::optional { + valuePath] -> std::optional { DateReading const reading = dateInstantOf(element->draft.get(), offsetMinutes); if (!reading.readable) { report(valuePath, "`dateTimeInput` shows a timestamp or an ISO-8601 date or date-time string"); @@ -5854,8 +6056,10 @@ std::optional ScreenCore::lowerDisplay(DocNode const& node, LowerCtx const return ui::banner(std::move(spec)); } if (kind == "badge") { - Badge spec{.tone = bindProp(ctx, node.prop("tone"), Tone::Neutral, toneOf), - .text = kit.textProp("text")}; + Badge spec{ + .tone = bindProp(ctx, node.prop("tone"), Tone::Neutral, toneOf), + .text = kit.textProp("text"), + }; spec.icon = kit.onceText("icon"); std::string_view const style = node.name("style"); spec.style = BadgeStyle::Filled; @@ -5876,7 +6080,7 @@ std::optional ScreenCore::lowerDisplay(DocNode const& node, LowerCtx const if (kind == "progress") { Progress spec; spec.value = slotProp>( - [scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("value")]() -> std::optional { + [scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("value")] -> std::optional { Value const value = evalIn(*scope, bindings.get(), expr); if (std::int64_t const* const number = value.asInt()) { return static_cast(*number); @@ -5902,16 +6106,17 @@ std::optional ScreenCore::lowerDisplay(DocNode const& node, LowerCtx const Value const* const state = item.field("state"); Value const* const detail = item.field("detail"); std::string const name = state == nullptr ? std::string{} : textOf(*state, {}); - steps.push_back( - Step{.label = label == nullptr ? std::string{} : textOf(*label, scope->formatting()), - .state = stepStateOf(name), - .detail = detail == nullptr ? std::string{} : textOf(*detail, scope->formatting())}); + steps.push_back(Step{ + .label = label == nullptr ? std::string{} : textOf(*label, scope->formatting()), + .state = stepStateOf(name), + .detail = detail == nullptr ? std::string{} : textOf(*detail, scope->formatting()), + }); } } return steps; }); spec.current = slotProp>( - [scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("current")]() -> std::optional { + [scope = ctx.scope, bindings = ctx.bindings, expr = node.prop("current")] -> std::optional { std::int64_t const index = intOf(evalIn(*scope, bindings.get(), expr), -1); return index < 0 ? std::nullopt : std::optional{static_cast(index)}; }); @@ -5962,25 +6167,29 @@ Node ScreenCore::lowerStack(DocNode const& node, LowerCtx const& ctx, ElementSta gap); } if (kind == "column") { - Column spec{.children = kit.children("children", gap), - .gap = gap, - .align = alignOf(node.name("align")), - .justify = justifyOf(node.name("justify")), - .divided = node.flag("divided"), - .padding = kit.stackPadding()}; + Column spec{ + .children = kit.children("children", gap), + .gap = gap, + .align = alignOf(node.name("align")), + .justify = justifyOf(node.name("justify")), + .divided = node.flag("divided"), + .padding = kit.stackPadding(), + }; if (node.prop("selected")) { spec.selected = bindProp(ctx, node.prop("selected"), false, boolOf); } commonOf(node, ctx, element, spec.common); return ui::column(std::move(spec)); } - Row spec{.children = kit.children("children"), - .gap = gap, - .align = alignOf(node.name("align")), - .justify = justifyOf(node.name("justify")), - .wrap = node.flag("wrap"), - .divided = node.flag("divided"), - .padding = kit.stackPadding()}; + Row spec{ + .children = kit.children("children"), + .gap = gap, + .align = alignOf(node.name("align")), + .justify = justifyOf(node.name("justify")), + .wrap = node.flag("wrap"), + .divided = node.flag("divided"), + .padding = kit.stackPadding(), + }; if (node.prop("selected")) { spec.selected = bindProp(ctx, node.prop("selected"), false, boolOf); } @@ -5990,14 +6199,18 @@ Node ScreenCore::lowerStack(DocNode const& node, LowerCtx const& ctx, ElementSta Node ScreenCore::lowerGrid(DocNode const& node, LowerCtx const& ctx, ElementState* element) { KindKit const kit{*this, node, ctx, element}; - Grid spec{.columns = static_cast(kit.onceInt("columns", 1)), - .gap = static_cast(kit.onceInt("gap", 0)), - .align = alignOf(node.name("align")), - .minColumnWidth = static_cast(kit.onceInt("minColumnWidth", 0))}; + Grid spec{ + .columns = static_cast(kit.onceInt("columns", 1)), + .gap = static_cast(kit.onceInt("gap", 0)), + .align = alignOf(node.name("align")), + .minColumnWidth = static_cast(kit.onceInt("minColumnWidth", 0)), + }; for (DocNodePtr const& track : node.partList("tracks")) { ExprPtr const width = track->prop("width"); - spec.tracks.push_back(GridTrack{.width = width ? sizingOf(once(ctx, width)) : Sizing::stretch(), - .align = cellPlaceNamed(track->name("align")).value_or(Align::Start)}); + spec.tracks.push_back(GridTrack{ + .width = width ? sizingOf(once(ctx, width)) : Sizing::stretch(), + .align = cellPlaceNamed(track->name("align")).value_or(Align::Start), + }); } for (DocNodePtr const& cell : node.nodes("children")) { ExprPtr const span = cell->prop("span"); @@ -6025,9 +6238,11 @@ Node ScreenCore::lowerPanel(DocNode const& node, LowerCtx const& ctx, ElementSta Node ScreenCore::lowerSplitter(DocNode const& node, LowerCtx const& ctx, ElementState* element) { KindKit const kit{*this, node, ctx, element}; ExprPtr const orientation = node.prop("orientation"); - Splitter spec{.children = kit.children("children"), - .orientation = orientation && axisOf(once(ctx, orientation)) == Axis::Vertical ? Axis::Vertical - : Axis::Horizontal}; + Splitter spec{ + .children = kit.children("children"), + .orientation = + orientation && axisOf(once(ctx, orientation)) == Axis::Vertical ? Axis::Vertical : Axis::Horizontal, + }; // No `onResize`: a user's drag stays the splitter's own, and the document's sizes are where it starts. if (ExprPtr const sizes = node.prop("sizes")) { spec.sizes = bindProp>( @@ -6125,11 +6340,11 @@ Node ScreenCore::lowerPageRegion(DocNode const& node, LowerCtx const& ctx, Eleme } Node ScreenCore::lowerLocaleScope(DocNode const& node, LowerCtx const& ctx) { - auto holder = std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); + auto const holder = std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); holder->transparent = true; ExprPtr const locale = node.prop("locale"); holder->localeFormat = &holder->nodes.computed([this, scope = ctx.scope, bindings = ctx.bindings, - locale]() -> std::shared_ptr { + locale] -> std::shared_ptr { Value const value = evalIn(*scope, bindings.get(), locale); std::string const* const tag = value.asString(); if (tag == nullptr && !value.isNull()) { @@ -6159,8 +6374,8 @@ Node ScreenCore::lowerLocaleScope(DocNode const& node, LowerCtx const& ctx) { return Key{tag == nullptr ? std::string{} : *tag}; }); spec.fallback = lazy( - [this, ctx, holder, content, path = node.path]() -> Node { - auto inner = std::make_shared(*this, holder, nullptr, holder->nodes.depth() + 2); + [this, ctx, holder, content, path = node.path] -> Node { + auto const inner = std::make_shared(*this, holder, nullptr, holder->nodes.depth() + 2); inner->transparent = true; LowerCtx const innerCtx{.scope = inner, .bindings = ctx.bindings, .boundary = ctx.boundary, .listGap = 0}; std::vector children; @@ -6237,10 +6452,12 @@ Node ScreenCore::lowerKind(DocNode const& node, LowerCtx const& ctx, ElementStat } if (kind == "actionBar") { KindKit const bar{*this, node, ctx, element}; - ActionBar spec{.children = bar.children("children"), - .align = alignOf(node.name("align")), - .justify = justifyOf(node.name("justify")), - .wrap = node.flag("wrap")}; + ActionBar spec{ + .children = bar.children("children"), + .align = alignOf(node.name("align")), + .justify = justifyOf(node.name("justify")), + .wrap = node.flag("wrap"), + }; reportActionBarGaps(node, ctx); commonOf(node, ctx, element, spec.common); return ui::actionBar(std::move(spec)); @@ -6272,6 +6489,7 @@ Node ScreenCore::lowerKind(DocNode const& node, LowerCtx const& ctx, ElementStat report(node.path, "`" + node.kind + "` is a node kind this interpreter does not lower"); return ui::text(Text{.text = std::string{node.kind}, .role = TextRole::Muted}); } + namespace { /// @brief A document field overlay's expressions, evaluated once, as the engine's overlay. @@ -6338,6 +6556,7 @@ struct DetachedLower { } // namespace // Builds the form's session when its element is declared, so its values can be read before the form is drawn. +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one section per kind of form element and its sessions. void ScreenCore::wireForm(ElementState& element) { DocNode const& node = *element.node; RtScope& scope = *element.scope; @@ -6523,6 +6742,7 @@ Node ScreenCore::lowerForm(DocNode const& node, LowerCtx const& ctx, ElementStat } return *std::move(json); } + namespace { /// @brief What a form fills of a field component's props: the field's value, errors, read-only and required state, @@ -6530,7 +6750,7 @@ namespace { /// @param prop The prop's name. /// @param state The field. /// @return The read, or empty for a prop the form does not fill. -[[nodiscard]] std::function formFilled(std::string const& prop, forms::FieldState* state) { +[[nodiscard]] std::function formFilled(std::string const& prop, forms::FieldState const* state) { if (prop == "value") { return [state] { forms::Encoding const& encoding = state->encoded().get(); @@ -6562,17 +6782,22 @@ namespace { // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): a prop's name, then its declared type. CustomProp ScreenCore::componentProp(std::string const& prop, std::string const& type, std::function read) { if (type == "bool") { - return CustomProp{.name = prop, .value = slotProp([this, read = std::move(read)] { - return boolOf(read(), session.formatting()); - })}; + return CustomProp{ + .name = prop, + .value = slotProp([this, read = std::move(read)] { return boolOf(read(), session.formatting()); }), + }; } if (type == "number") { - return CustomProp{.name = prop, - .value = slotProp([read = std::move(read)] { return componentNumber(read()); })}; + return CustomProp{ + .name = prop, + .value = slotProp([read = std::move(read)] { return componentNumber(read()); }), + }; } - return CustomProp{.name = prop, .value = slotProp([this, read = std::move(read), type] { - return componentText(read(), type, session.formatting()); - })}; + return CustomProp{ + .name = prop, + .value = slotProp( + [this, read = std::move(read), type] { return componentText(read(), type, session.formatting()); }), + }; } void ScreenCore::changeField(forms::FieldState& state, forms::FieldSpec const& spec, std::string const& path, @@ -6600,21 +6825,24 @@ Node ScreenCore::fieldComponent(forms::FieldView const& view, DocNode const& ove // A loaded document's field component is declared, with a `value` prop and a `change` event. Component const& component = _doc->components.at(name); forms::FieldState* const state = &view.state(); - Custom spec{.name = name, - .fallback = view.defaultControl(), - .props = {}, - .minVersion = - static_cast(std::clamp(component.version, 0, std::numeric_limits::max())), - .onEvent = {}}; + Custom spec{ + .name = name, + .fallback = view.defaultControl(), + .props = {}, + .minVersion = + static_cast(std::clamp(component.version, 0, std::numeric_limits::max())), + .onEvent = {}, + }; for (auto const& [prop, type] : component.props) { if (prop == "value" && type == "json") { // The wire JSON itself, so an object's or a collection's every digit reaches the component. - spec.props.push_back(CustomProp{.name = prop, .value = slotProp([state] { - forms::Encoding const& encoding = state->encoded().get(); - return encoding.has_value() && encoding->has_value() - ? (*encoding)->json - : std::string{"null"}; - })}); + spec.props.push_back(CustomProp{ + .name = prop, + .value = slotProp([state] { + forms::Encoding const& encoding = state->encoded().get(); + return encoding.has_value() && encoding->has_value() ? (*encoding)->json : std::string{"null"}; + }), + }); continue; } std::function read = formFilled(prop, state); @@ -6810,8 +7038,8 @@ Node ScreenCore::lowerDialog(DocNode const& node, LowerCtx const& ctx, ElementSt node.prop("gap") ? static_cast(intOf(once(ctx, node.prop("gap")), kDialogGap)) : kDialogGap; LayoutHints const bodyHints = holderHints(bodyContent, node.scope ? &*node.scope : nullptr, ctx); Node body = lazy( - [this, ctx, &node, element, bodyGap]() -> Node { - auto inner = std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); + [this, ctx, &node, element, bodyGap] -> Node { + auto const inner = std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); inner->owner = element; addPending(1); inner->submitted = &element->submitted; @@ -6834,7 +7062,11 @@ Node ScreenCore::lowerDialog(DocNode const& node, LowerCtx const& ctx, ElementSt declare(*inner, node.scope ? &*node.scope : nullptr, content, lists); element->inner.set(inner.get()); LowerCtx const innerCtx{ - .scope = inner, .bindings = ctx.bindings, .boundary = ctx.boundary, .listGap = bodyGap}; + .scope = inner, + .bindings = ctx.bindings, + .boundary = ctx.boundary, + .listGap = bodyGap, + }; std::vector children; children.reserve(content.size()); for (DocNode const* const child : content) { @@ -6847,13 +7079,16 @@ Node ScreenCore::lowerDialog(DocNode const& node, LowerCtx const& ctx, ElementSt } std::vector keys; if (Commands const* const commands = node.event("default")) { - keys.push_back(KeyBinding{.chord = "Enter", .onPress = [this, innerCtx, commands] { - runEvent(commands, innerCtx, Value{}); - }}); + keys.push_back(KeyBinding{ + .chord = "Enter", + .onPress = [this, innerCtx, commands] { runEvent(commands, innerCtx, Value{}); }, + }); } if (Commands const* const commands = node.event("cancel")) { keys.push_back(KeyBinding{ - .chord = "Esc", .onPress = [this, innerCtx, commands] { runEvent(commands, innerCtx, Value{}); }}); + .chord = "Esc", + .onPress = [this, innerCtx, commands] { runEvent(commands, innerCtx, Value{}); }, + }); } fillHolder(children, node.path); return holding(std::move(children), inner, std::move(keys), bodyGap); @@ -6874,21 +7109,24 @@ Node ScreenCore::lowerDialog(DocNode const& node, LowerCtx const& ctx, ElementSt .description = bindProp(ctx, node.prop("description"), std::string{}, stringOf), .child = std::move(body), .onDismiss = std::move(onDismiss), - .side = side && textOf(once(ctx, side), ctx.scope->formatting()) == "start" ? Side::Start : Side::End}; + .side = side && textOf(once(ctx, side), ctx.scope->formatting()) == "start" ? Side::Start : Side::End, + }; if (ExprPtr const spans = node.prop("descriptionSpans")) { spec.descriptionSpans = spansProp(ctx, spans); } commonOf(node, ctx, element, spec.common); return ui::drawer(std::move(spec)); } - Dialog spec{.open = std::move(open), - .title = bindProp(ctx, node.prop("title"), std::string{}, stringOf), - .description = bindProp(ctx, node.prop("description"), std::string{}, stringOf), - .child = std::move(body), - .onDismiss = std::move(onDismiss), - .common = {}, - .sheet = bindProp(ctx, node.prop("sheet"), false, boolOf), - .dismissLabel = bindProp(ctx, node.prop("dismissLabel"), std::string{"Close"}, stringOf)}; + Dialog spec{ + .open = std::move(open), + .title = bindProp(ctx, node.prop("title"), std::string{}, stringOf), + .description = bindProp(ctx, node.prop("description"), std::string{}, stringOf), + .child = std::move(body), + .onDismiss = std::move(onDismiss), + .common = {}, // NOLINT(readability-trailing-comma): the comma ends the designator, not the empty braces. + .sheet = bindProp(ctx, node.prop("sheet"), false, boolOf), + .dismissLabel = bindProp(ctx, node.prop("dismissLabel"), std::string{"Close"}, stringOf), + }; if (ExprPtr const spans = node.prop("descriptionSpans")) { spec.descriptionSpans = spansProp(ctx, spans); } @@ -6911,15 +7149,20 @@ Node ScreenCore::lowerSwitch(DocNode const& node, LowerCtx const& ctx) { spec.cases.push_back(SwitchCase{ .key = Key{index++}, .node = lazy( - [this, ctx, casePart, caseGap = ctx.listGap]() -> Node { - auto inner = std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); + [this, ctx, casePart, caseGap = ctx.listGap] -> Node { + auto const inner = + std::make_shared(*this, ctx.scope, nullptr, ctx.scope->nodes.depth() + 2); std::vector content; for (DocNodePtr const& child : casePart->nodes("children")) { content.push_back(child.get()); } declare(*inner, casePart->scope ? &*casePart->scope : nullptr, content, {}); LowerCtx const innerCtx{ - .scope = inner, .bindings = ctx.bindings, .boundary = ctx.boundary, .listGap = caseGap}; + .scope = inner, + .bindings = ctx.bindings, + .boundary = ctx.boundary, + .listGap = caseGap, + }; std::vector children; children.reserve(content.size()); for (DocNode const* const child : content) { @@ -6928,7 +7171,8 @@ Node ScreenCore::lowerSwitch(DocNode const& node, LowerCtx const& ctx) { fillHolder(children, casePart->path); return holding(std::move(children), inner, {}, caseGap); }, - caseHints)}); + caseHints), + }); } spec.selector = slotProp( [scope = ctx.scope, bindings = ctx.bindings, selected = node.prop("on"), whens = std::move(whens)] { @@ -6951,7 +7195,7 @@ Prop ScreenCore::controlledTabSelection(DocNode const& node, LowerC std::shared_ptr> const& ids) { auto const unknownReported = std::make_shared(false); return Prop{[this, scope = ctx.scope, bindings = ctx.bindings, selected, ids, unknownReported, - path = pointerAppend(node.path, "selected")]() -> std::size_t { + path = pointerAppend(node.path, "selected")] -> std::size_t { Value const value = evalIn(*scope, bindings.get(), selected); std::string const* const named = value.asString(); auto const found = named == nullptr ? ids->end() : std::ranges::find(*ids, *named); @@ -6971,12 +7215,14 @@ Prop ScreenCore::controlledTabSelection(DocNode const& node, LowerC // user's pick itself, as a bound index too, whose page follows the pick: a constant would move only the highlight. Node ScreenCore::lowerTabs(DocNode const& node, LowerCtx const& ctx, ElementState* element) { Tabs spec; - auto ids = std::make_shared>(); + auto const ids = std::make_shared>(); for (DocNodePtr const& tab : node.partList("tabs")) { auto const nodes = tab->nodes("children"); ids->push_back(tab->id); - spec.tabs.push_back(Tab{.label = bindProp(ctx, tab->prop("label"), std::string{}, stringOf), - .node = nodes.empty() ? Node{} : lowerAll(nodes, ctx)}); + spec.tabs.push_back(Tab{ + .label = bindProp(ctx, tab->prop("label"), std::string{}, stringOf), + .node = nodes.empty() ? Node{} : lowerAll(nodes, ctx), + }); } spec.moreLabel = bindProp(ctx, node.prop("moreLabel"), std::string{"More"}, stringOf); if (ExprPtr const inset = node.prop("inset")) { @@ -7037,7 +7283,8 @@ bool ScreenCore::focusTarget(Command const& command, RtScope const& scope, Bindi } FocusPlace candidatePlace{ .prefix = place.prefix, - .rows = {place.rows.begin(), std::next(place.rows.begin(), static_cast(kept))}}; + .rows = {place.rows.begin(), std::next(place.rows.begin(), static_cast(kept))}, + }; if (row) { candidatePlace.rows.push_back(*row); } @@ -7087,7 +7334,7 @@ Node ScreenCore::lowerRows(DocNode const& node, LowerCtx const& ctx, ElementStat } auto rowView = [this, ctx, &node, content, keyFn](reactive::Signal const& row) -> Node { std::string key = runtime().untracked([&] { return canonicalJson(valueOfKey(keyFn(row.peek()))); }); - auto scope = rowScope(node, ctx, row, content, std::move(key)); + auto const scope = rowScope(node, ctx, row, content, std::move(key)); LowerCtx const rowCtx{.scope = scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; std::vector children; children.reserve(content.size()); @@ -7174,10 +7421,11 @@ Node ScreenCore::lowerRows(DocNode const& node, LowerCtx const& ctx, ElementStat Value const* const field = item.field("id"); Value const* const label = item.field("label"); fields.push_back(field == nullptr ? std::string{} : textOf(*field, format)); - columns.push_back( - TableColumn{.label = textOf(label != nullptr ? *label : Value{fields.back()}, format), - .align = placeOf(item, "align", Align::Start), - .valign = placeOf(item, "valign", tableValign)}); + columns.push_back(TableColumn{ + .label = textOf(label != nullptr ? *label : Value{fields.back()}, format), + .align = placeOf(item, "align", Align::Start), + .valign = placeOf(item, "valign", tableValign), + }); cells.push_back(nullptr); roles.push_back(TextRole::Normal); } @@ -7205,23 +7453,25 @@ Node ScreenCore::lowerRows(DocNode const& node, LowerCtx const& ctx, ElementStat report(part->path + "/shrink", "`shrink` lets a stretch column go narrower than its header; this column's width does not stretch"); } - columns.push_back(TableColumn{.label = label ? textOf(once(ctx, label), format) : std::string{}, - .width = sized, - .role = columnRole, - .align = cellPlaceNamed(part->name("align")).value_or(Align::Start), - .valign = cellPlaceNamed(part->name("valign")).value_or(tableValign), - .sortable = part->flag("sortable"), - .wrap = part->flag("wrap", true), - .shrink = shrink && sized.kind == Sizing::Kind::Stretch}); + columns.push_back(TableColumn{ + .label = label ? textOf(once(ctx, label), format) : std::string{}, + .width = sized, + .role = columnRole, + .align = cellPlaceNamed(part->name("align")).value_or(Align::Start), + .valign = cellPlaceNamed(part->name("valign")).value_or(tableValign), + .sortable = part->flag("sortable"), + .wrap = part->flag("wrap", true), + .shrink = shrink && sized.kind == Sizing::Kind::Stretch, + }); cells.push_back(part.get()); fields.emplace_back(part->id); roles.push_back(columnRole); } - auto registry = std::make_shared, std::less<>>>(); + auto const registry = std::make_shared, std::less<>>>(); // A value that names no tone is reported once for the table, whichever row and value it was. - auto toneReported = std::make_shared(false); + auto const toneReported = std::make_shared(false); // Likewise for a `rowSpans` value that is no list of spans. - auto spansReported = std::make_shared(false); + auto const spansReported = std::make_shared(false); auto cellsOf = [this, ctx, &node, cells, fields, roles, registry, keyFn, toneReported, spansReported](reactive::Signal const& row) { if (row.peek().field(kGroupHeadingField) != nullptr) { @@ -7237,7 +7487,7 @@ Node ScreenCore::lowerRows(DocNode const& node, LowerCtx const& ctx, ElementStat } } std::string key = runtime().untracked([&] { return canonicalJson(valueOfKey(keyFn(row.peek()))); }); - auto scope = rowScope(node, ctx, row, content, key); + auto const scope = rowScope(node, ctx, row, content, key); (*registry)[std::move(key)] = scope; LowerCtx const rowCtx{.scope = scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; std::vector out; @@ -7248,17 +7498,18 @@ Node ScreenCore::lowerRows(DocNode const& node, LowerCtx const& ctx, ElementStat out.push_back(lowerAll(nodes, rowCtx)); continue; } - out.push_back( - ui::text(Text{.text = slotProp([scope = rowCtx.scope, &row, field = fields.at(index)] { - Value const* const value = row.get().field(field); - return value == nullptr ? std::string{} : textOf(*value, scope->formatting()); - }), - .role = roles.at(index)})); + out.push_back(ui::text(Text{ + .text = slotProp([scope = rowCtx.scope, &row, field = fields.at(index)] { + Value const* const value = row.get().field(field); + return value == nullptr ? std::string{} : textOf(*value, scope->formatting()); + }), + .role = roles.at(index), + })); } if (!out.empty()) { // The row's first cell owns the row's scope, which lives as long as the row's node: a cell is placed by // its column, so the scope is not held by a wrapping container, which the column would place instead. - auto owner = std::make_shared> const>(out.front(), scope); + auto const owner = std::make_shared> const>(out.front(), scope); out.front() = Node{owner, owner->first.get()}; } TableRowView rowView{.cells = std::move(out), .tone = std::nullopt}; @@ -7268,7 +7519,7 @@ Node ScreenCore::lowerRows(DocNode const& node, LowerCtx const& ctx, ElementStat } if (ExprPtr const toneExpr = node.prop("rowTone")) { rowView.tone = slotProp>( - [this, scope, bindings = ctx.bindings, toneExpr, toneReported]() -> std::optional { + [this, scope, bindings = ctx.bindings, toneExpr, toneReported] -> std::optional { return rowToneOf(evalIn(*scope, bindings.get(), toneExpr), toneExpr->path, *toneReported); }); } @@ -7305,7 +7556,7 @@ Node ScreenCore::lowerRows(DocNode const& node, LowerCtx const& ctx, ElementStat // The selection the table shows: the bound `selection`, or the table's own. A slot even for a literal list, so // a bound selection is fixed until the document writes it, and a user's change the document leaves unwritten // snaps back. A bound value that is neither a list nor `null` is reported once. - auto selectionReported = std::make_shared(false); + auto const selectionReported = std::make_shared(false); options.selection = slotProp>([this, element, selectionReported, path = node.path] { std::vector keys; if (element->bound != nullptr) { @@ -7364,7 +7615,7 @@ Node ScreenCore::lowerRows(DocNode const& node, LowerCtx const& ctx, ElementStat } return derivedCount + static_cast(std::distance(parts.begin(), found)); }; - options.sort = slotProp>([element, &node, columnIndex]() -> std::optional { + options.sort = slotProp>([element, &node, columnIndex] -> std::optional { std::optional> const keys = sortKeysOf(node, tableSort(*element)); if (!keys || keys->empty()) { return std::nullopt; @@ -7373,8 +7624,10 @@ Node ScreenCore::lowerRows(DocNode const& node, LowerCtx const& ctx, ElementStat if (!index) { return std::nullopt; } - return TableSort{.column = *index, - .direction = keys->front().descending ? SortDirection::Descending : SortDirection::Ascending}; + return TableSort{ + .column = *index, + .direction = keys->front().descending ? SortDirection::Descending : SortDirection::Ascending, + }; }); // A header click makes its column the single key: descending when it already is the first key ascending, // ascending otherwise. The table's own sort takes it when no key binds one, then `onSortChange` runs with @@ -7450,10 +7703,11 @@ TableRowView ScreenCore::headingRow(DocNode const& node, LowerCtx const& ctx, re for (DocNodePtr const& child : heading) { content.push_back(child.get()); } - auto scope = rowScope(node, ctx, row, content, std::move(key)); + auto const scope = rowScope(node, ctx, row, content, std::move(key)); LowerCtx const rowCtx{.scope = scope, .bindings = ctx.bindings, .boundary = ctx.boundary}; // The cell owns the heading's scope, for as long as the row's node lives, as a data row's first cell does. - auto owner = std::make_shared> const>(lowerAll(heading, rowCtx), scope); + auto const owner = + std::make_shared> const>(lowerAll(heading, rowCtx), scope); return TableRowView{.cells = {Node{owner, owner->first.get()}}, .tone = std::nullopt, .heading = true}; } @@ -7491,13 +7745,15 @@ std::optional ScreenCore::chartMagnitude(Value const& value, std } std::optional ScreenCore::chartToneOf(Value const& value, std::string const& path) { - static constexpr std::array, 5> kTones = {{ - {"neutral", Tone::Neutral}, - {"info", Tone::Info}, - {"ok", Tone::Ok}, - {"warn", Tone::Warn}, - {"err", Tone::Err}, - }}; + static constexpr std::array, 5> kTones = { + { + {"neutral", Tone::Neutral}, + {"info", Tone::Info}, + {"ok", Tone::Ok}, + {"warn", Tone::Warn}, + {"err", Tone::Err}, + }, + }; if (value.isNull()) { return std::nullopt; } @@ -7579,6 +7835,7 @@ std::vector ScreenCore::chartPoints(DocNode const& series } return points; } + namespace { /// @brief A chart's exact value at @p places, as the active locale writes it. @@ -7665,9 +7922,10 @@ ChartRange ScreenCore::chartFixedRange(DocNode const& node, RtScope const& scope return range; } +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one branch per way a series can be drawn or clipped. void ScreenCore::chartSeries(ChartData& data, DocNode const& node, RtScope const& scope, Bindings const* bindings, std::vector>& series, bool positioned, - ChartRange const& range) const { + ChartRange const& range) { auto const positionOf = [positioned](detail::ChartRawPoint const& point) { return positioned && point.x ? *point.x : math::Rational{static_cast(point.index), math::DecimalPlaces{0}}; @@ -7728,12 +7986,14 @@ void ScreenCore::chartSeries(ChartData& data, DocNode const& node, RtScope const } drawn.joined = drawn.style == ChartStyle::Line && (!part->flags.contains("joined") || part->flag("joined")); for (detail::ChartRawPoint& point : series.at(index)) { - ChartPoint out{.x = realOf(positionOf(point)), - .y = std::nullopt, - .clip = ChartClip::None, - .xLabel = std::move(point.xLabel), - .tone = point.tone, - .note = std::move(point.note)}; + ChartPoint out{ + .x = realOf(positionOf(point)), + .y = std::nullopt, + .clip = ChartClip::None, + .xLabel = std::move(point.xLabel), + .tone = point.tone, + .note = std::move(point.note), + }; if (point.y) { auto const [shown, clip] = detail::chartClipped(*point.y, range); out.y = realOf(shown); @@ -7787,7 +8047,7 @@ ChartData ScreenCore::chartData(DocNode const& node, RtScope const& scope, Bindi } } if (barsHaveValues) { - axisValues.push_back(math::Rational{0, math::DecimalPlaces{0}}); + axisValues.emplace_back(0, math::DecimalPlaces{0}); padding.low = std::ranges::any_of(values, [](math::Rational const& value) { return value.numerator < 0; }); padding.high = std::ranges::any_of(values, [](math::Rational const& value) { return value.numerator > 0; }); } @@ -7816,11 +8076,12 @@ ChartData ScreenCore::chartData(DocNode const& node, RtScope const& scope, Bindi } } for (detail::ChartRawLine const& line : lines) { - data.lines.push_back( - ChartLine{.value = realOf(line.value), - .label = line.label.value_or(detail::chartNumberText(line.value, places, format)), - .tone = line.tone, - .style = line.style}); + data.lines.push_back(ChartLine{ + .value = realOf(line.value), + .label = line.label.value_or(detail::chartNumberText(line.value, places, format)), + .tone = line.tone, + .style = line.style, + }); } if (kinds.numbers && kinds.instants) { report(pointerAppend(node.path, "series"), @@ -7855,15 +8116,17 @@ std::vector ScreenCore::rowSpansOf(Value const& value, std::vectorasString() : nullptr; + std::string const* const columnId = column != nullptr ? column->asString() : nullptr; std::int64_t const* const count = rows != nullptr ? rows->asInt() : nullptr; - auto const found = id != nullptr ? std::ranges::find(columns, *id) : columns.end(); + auto const found = columnId != nullptr ? std::ranges::find(columns, *columnId) : columns.end(); if (found == columns.end() || count == nullptr || *count < 1) { bad = true; continue; } - spans.push_back(RowSpan{.column = static_cast(found - columns.begin()), - .rows = static_cast(*count)}); + spans.push_back(RowSpan{ + .column = static_cast(found - columns.begin()), + .rows = static_cast(*count), + }); } if (bad && !noted) { noted = true; @@ -7924,24 +8187,28 @@ void ScreenCore::ownQueries(DocNode const& node, RtScope const& scope, BoundaryR } Node ScreenCore::lowerBoundary(DocNode const& node, LowerCtx const& ctx) { - auto boundary = std::make_shared(); + auto const boundary = std::make_shared(); std::set> seen; for (DocNodePtr const& child : node.nodes("children")) { ownQueries(*child, *ctx.scope, *boundary, seen); } - auto bindings = std::make_shared(*ctx.bindings); - bindings->push_back(Binding{.name = "boundary", .read = [boundary] { - for (QueryRuntime const* const query : boundary->queries) { - Value const error = query->error(); - if (!error.isNull() && query->value().isNull()) { - return Value{ValueRecord{{"error", error}}}; - } - } - return Value{ValueRecord{{"error", Value{}}}}; - }}); + auto const bindings = std::make_shared(*ctx.bindings); + bindings->push_back(Binding{ + .name = "boundary", + .read = + [boundary] { + for (QueryRuntime const* const query : boundary->queries) { + Value const error = query->error(); + if (!error.isNull() && query->value().isNull()) { + return Value{ValueRecord{{"error", error}}}; + } + } + return Value{ValueRecord{{"error", Value{}}}}; + }, + }); LowerCtx const errorCtx{.scope = ctx.scope, .bindings = bindings, .boundary = boundary}; LowerCtx const childCtx{.scope = ctx.scope, .bindings = ctx.bindings, .boundary = boundary}; - auto group = [this](std::span nodes, LowerCtx const& where) -> Node { + auto const group = [this](std::span nodes, LowerCtx const& where) -> Node { return nodes.empty() ? ui::spacer() : lowerAll(nodes, where); }; Switch spec; @@ -7973,27 +8240,32 @@ Node ScreenCore::lowerCustom(DocNode const& node, LowerCtx const& ctx) { props.emplace_back(key, expr); } } - auto bindings = std::make_shared(); - bindings->push_back( - Binding{.name = "props", .read = [scope = ctx.scope, outer = ctx.bindings, props = std::move(props)] { - ValueRecord record; - for (auto const& [key, expr] : props) { - record.insert_or_assign(key, evalIn(*scope, outer.get(), expr)); - } - return Value{std::move(record)}; - }}); - auto scope = std::make_shared(*this, nullptr, nullptr, ctx.scope->nodes.depth() + 1); + auto const bindings = std::make_shared(); + bindings->push_back(Binding{ + .name = "props", + .read = + [scope = ctx.scope, outer = ctx.bindings, props = std::move(props)] { + ValueRecord record; + for (auto const& [key, expr] : props) { + record.insert_or_assign(key, evalIn(*scope, outer.get(), expr)); + } + return Value{std::move(record)}; + }, + }); + auto const scope = std::make_shared(*this, nullptr, nullptr, ctx.scope->nodes.depth() + 1); scope->formatSource = ctx.scope; scope->usePrefix = focusKeyOf(node.path, *ctx.scope) + ">"; DocNode const& fallback = *component.fallback; declare(*scope, nullptr, {&fallback}, {}); Node lowered = lower(fallback, LowerCtx{.scope = scope, .bindings = bindings, .boundary = nullptr}); - Custom spec{.name = name, - .fallback = std::move(lowered), - .props = {}, - .minVersion = - static_cast(std::clamp(component.version, 0, std::numeric_limits::max())), - .onEvent = {}}; + Custom spec{ + .name = name, + .fallback = std::move(lowered), + .props = {}, + .minVersion = + static_cast(std::clamp(component.version, 0, std::numeric_limits::max())), + .onEvent = {}, + }; // Every declared prop is given, a missing one as its type's empty value: a component lacking one is refused. for (auto const& [prop, type] : component.props) { ExprPtr expr; @@ -8006,16 +8278,18 @@ Node ScreenCore::lowerCustom(DocNode const& node, LowerCtx const& ctx) { spec.props.push_back(CustomProp{.name = prop, .value = bindProp(ctx, expr, false, boolOf)}); } else if (type == "number") { spec.props.push_back(CustomProp{ - .name = prop, .value = bindProp(ctx, expr, 0.0, [](Value const& value, FormatContext const&) { - return componentNumber(value); - })}); + .name = prop, + .value = bindProp( + ctx, expr, 0.0, [](Value const& value, FormatContext const&) { return componentNumber(value); }), + }); } else { - spec.props.push_back( - CustomProp{.name = prop, - .value = bindProp(ctx, expr, std::string{}, - [type](Value const& value, FormatContext const& format) { - return componentText(value, type, format); - })}); + spec.props.push_back(CustomProp{ + .name = prop, + .value = bindProp(ctx, expr, std::string{}, + [type](Value const& value, FormatContext const& format) { + return componentText(value, type, format); + }), + }); } } spec.onEvent = [this, ctx, site = &node, declared = &component](std::string const& event, @@ -8029,6 +8303,7 @@ Node ScreenCore::lowerCustom(DocNode const& node, LowerCtx const& ctx) { }; return ui::custom(std::move(spec)); } + namespace { /// @brief One child of an arranged container, as the user's choice places it. @@ -8156,7 +8431,8 @@ Node ScreenCore::lowerArranged(DocNode const& node, LowerCtx const& ctx, Element ForEach spec{ .model = std::make_shared const>(std::move(order), std::move(key), std::move(view)), .axis = axis, - .gap = gap}; + .gap = gap, + }; commonOf(node, ctx, element, spec.common); return makeNode(std::move(spec)); } @@ -8224,12 +8500,19 @@ Node ScreenCore::lowerArrangeEditor(DocNode const& node, LowerCtx const& ctx, st moveDown.common.a11y.name = "Move " + childId + " down"; moveDown.common.testId = "arrange-down-" + childId; shown.common.testId = "arrange-shown-" + childId; - return ui::row(Row{.children = {ui::checkbox(std::move(shown)), ui::button(std::move(moveUp)), - ui::button(std::move(moveDown))}, - .gap = 1}); + return ui::row(Row{ + .children = + { + ui::checkbox(std::move(shown)), + ui::button(std::move(moveUp)), + ui::button(std::move(moveDown)), + }, + .gap = 1, + }); + }; + ForEach editor{ + .model = std::make_shared const>(std::move(rows), std::move(key), std::move(view)), }; - ForEach editor{.model = - std::make_shared const>(std::move(rows), std::move(key), std::move(view))}; commonOf(node, ctx, nullptr, editor.common); return makeNode(std::move(editor)); } @@ -8238,7 +8521,7 @@ Node ScreenCore::lowerCustomize(DocNode const& node, LowerCtx const& ctx) { std::string const point{node.name("point")}; // A loaded document's customize node names a declared point, and every point has a choice in `prefs`. CustomizePoint const& spec = _doc->customize.at(point); - auto choose = [this, point](Value value) { + auto const choose = [this, point](Value value) { session.asUser([&] { ValueRecord next = prefs.peek(); next.insert_or_assign(point, value); @@ -8259,7 +8542,7 @@ Node ScreenCore::lowerCustomize(DocNode const& node, LowerCtx const& ctx) { options.push_back(SelectOption{.key = Key{option}, .label = option}); } select.options = std::move(options); - select.selected = slotProp>([this, point]() -> std::optional { + select.selected = slotProp>([this, point] -> std::optional { Value const& chosen = prefs.get().at(point); return chosen.isNull() ? std::nullopt : std::optional{keyOf(chosen)}; }); @@ -8397,14 +8680,16 @@ BorrowedModel Screen::lend(std::string_view alias) const { return {}; } detail::ModelAlias& model = *found->model; - return BorrowedModel{.channel = detail::channelOf(model, *_core), - .token = _core->runtime().untracked([&] { return model.token->get(); })}; + return BorrowedModel{ + .channel = detail::channelOf(model, *_core), + .token = _core->runtime().untracked([&] { return model.token->get(); }), + }; } std::expected, Refusal> Interpreter::mount(std::shared_ptr doc, ValueRecord const& params, IViewBackend& backend, MountOptions const& options) { - auto refuse = [&](std::string path, std::string reason) { + auto const refuse = [&](std::string path, std::string reason) { return std::unexpected(Refusal{.document = doc->id, .path = std::move(path), .reason = std::move(reason)}); }; if (!doc->view) { @@ -8457,7 +8742,10 @@ std::expected, Refusal> Interpreter::mount(std::shared_p Node root = runtime.untracked([&] { core.declare(scope, &doc->scope, {doc->view.get()}, lists); detail::LowerCtx const ctx{ - .scope = screen->_scope, .bindings = std::make_shared(), .boundary = nullptr}; + .scope = screen->_scope, + .bindings = std::make_shared(), + .boundary = nullptr, + }; Node lowered = core.lower(*doc->view, ctx); screen->_headStatus = core.lowerBadgeParts(doc->status, ctx); screen->_headActions = core.lowerActionParts(doc->actions, ctx); @@ -8467,7 +8755,9 @@ std::expected, Refusal> Interpreter::mount(std::shared_p std::vector keys; for (auto const& [chord, commands] : doc->keys) { keys.push_back(KeyBinding{ - .chord = chord, .onPress = [&core, ctx, list = &commands] { core.runEvent(list, ctx, Value{}); }}); + .chord = chord, + .onPress = [&core, ctx, list = &commands] { core.runEvent(list, ctx, Value{}); }, + }); } Column column{.children = {std::move(lowered)}}; column.common.keys = std::move(keys); @@ -8475,8 +8765,8 @@ std::expected, Refusal> Interpreter::mount(std::shared_p } return lowered; }); - screen->_mounted.emplace(runtime, backend, std::move(root), options.parent, options.depth + 1); - screen->_core->focusElement = [mounted = &*screen->_mounted](std::string_view element) { + screen->_mounted = std::make_unique(runtime, backend, std::move(root), options.parent, options.depth + 1); + screen->_core->focusElement = [mounted = screen->_mounted.get()](std::string_view element) { return mounted->focus(element); }; screen->runLifecycle("onMount"); @@ -8505,12 +8795,16 @@ std::expected, Refusal> Interpreter::mountApp(std::shar _session->runtime().untracked([&] { core.declare(*root->_scope, &doc->scope, {}, lists); detail::LowerCtx const ctx{ - .scope = root->_scope, .bindings = std::make_shared(), .boundary = nullptr}; + .scope = root->_scope, + .bindings = std::make_shared(), + .boundary = nullptr, + }; std::vector badges = core.lowerBadgeParts(doc->navigation, ctx); for (std::size_t index = 0; index < badges.size(); ++index) { - root->_navigation.push_back( - AppRoot::PlacedBadge{.screen = std::string{doc->navigation.at(index)->name("screen")}, - .badge = std::move(badges.at(index))}); + root->_navigation.push_back(AppRoot::PlacedBadge{ + .screen = std::string{doc->navigation.at(index)->name("screen")}, + .badge = std::move(badges.at(index)), + }); } }); root->_navigationBadges = std::make_unique>>( @@ -8518,9 +8812,11 @@ std::expected, Refusal> Interpreter::mountApp(std::shar std::vector shown; for (AppRoot::PlacedBadge const& entry : *placed) { if (entry.badge.visible.evaluate()) { - shown.push_back(NavigationBadge{.screen = entry.screen, - .text = entry.badge.text.evaluate(), - .tone = entry.badge.tone.evaluate()}); + shown.push_back(NavigationBadge{ + .screen = entry.screen, + .text = entry.badge.text.evaluate(), + .tone = entry.badge.tone.evaluate(), + }); } } return shown; diff --git a/tests/test_push_cache.cpp b/tests/test_push_cache.cpp index bde75f951..65ad5e6e8 100644 --- a/tests/test_push_cache.cpp +++ b/tests/test_push_cache.cpp @@ -6,6 +6,7 @@ #include #include #include +#include #include #include #include diff --git a/tests/test_ui_interpreter_commands.cpp b/tests/test_ui_interpreter_commands.cpp index b35c0ca09..8f7963b16 100644 --- a/tests/test_ui_interpreter_commands.cpp +++ b/tests/test_ui_interpreter_commands.cpp @@ -6,6 +6,7 @@ #include #include +#include #include #include #include diff --git a/tests/ui_interpreter_support.hpp b/tests/ui_interpreter_support.hpp index 35070ef56..79e36db9d 100644 --- a/tests/ui_interpreter_support.hpp +++ b/tests/ui_interpreter_support.hpp @@ -10,6 +10,7 @@ #include #include #include +#include #include #include #include From b32562d6785856117a1f787dbbb431d1d9488b0b Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 04:15:40 +0100 Subject: [PATCH 06/38] Move the document loader into src/ui/document.cpp The parser, the validator, the kind and key tables, and the loader's entry points (`loadDocument`, `loadDocumentText`, `nodeKinds`, `documentLookup`) move to the compiled library. The header keeps the document model, the key and kind vocabulary types the interpreter reads (`KeySpec`, `KindSpec`, their flags), `NameCategory`, `listed`, and documented MORPH_API declarations of `findKind`, `pageGeometryOf` and `regionGeometryOf`, which the interpreter calls. The parser, the validator and every table they read are in an unnamed namespace in the .cpp; nothing else uses them. Includes the header no longer needs are dropped: a TU that includes only document.hpp peaks at 446 MB of front-end memory, from 728 MB. The page `margins` reading is split out of `pageGeometryOf`, and the table regions carry a NOLINT for readability-trailing-comma beside the existing one for designated initializers, so clang-tidy is clean on the moved code. The branch-coverage allowlist entries for document.hpp now name src/ui/document.cpp. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- CMakeLists.txt | 1 + docs/spec/ui/document.md | 4 +- include/morph/ui/document.hpp | 4961 +----------------------- scripts/branch_partial_allowlist.json | 16 +- src/ui/document.cpp | 4990 +++++++++++++++++++++++++ 5 files changed, 5045 insertions(+), 4927 deletions(-) create mode 100644 src/ui/document.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index c5022c84e..677904835 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -412,6 +412,7 @@ endif() # once, in src/ui. include(GenerateExportHeader) add_library(morph STATIC + src/ui/document.cpp src/ui/interpreter.cpp src/ui/library.cpp ) diff --git a/docs/spec/ui/document.md b/docs/spec/ui/document.md index 835b93ad7..90bd23dab 100644 --- a/docs/spec/ui/document.md +++ b/docs/spec/ui/document.md @@ -249,8 +249,8 @@ box, any layout key a sheet sizes itself without) are in [`document_page.md`](do A `DocNode` is a node or a structured part of one. Its properties stay keyed by their document keys — `props` (expressions), `events` (command lists, a custom node's events as `on.`), `children` (node lists), `parts` (records such as columns and tabs), `names` (plain strings) and -`keys` — so the interpreter reads a kind's properties by name. One table in `document.hpp` -(`detail::kKinds`) says, per kind, which keys it has and what shape each takes; it is the only +`keys` — so the interpreter reads a kind's properties by name. One table in `src/ui/document.cpp` +(`kKinds`, reached through `detail::findKind`) says, per kind, which keys it has and what shape each takes; it is the only place a kind is described. **Every node** takes `id`, `visible`, `enabled` (conditions), `tooltip`, `sizing`, `span`, diff --git a/include/morph/ui/document.hpp b/include/morph/ui/document.hpp index ef9776af9..3c5d8d67f 100644 --- a/include/morph/ui/document.hpp +++ b/include/morph/ui/document.hpp @@ -2,28 +2,20 @@ #pragma once #include -#include #include #include -#include #include -#include #include -#include -#include #include #include +#include #include -#include -#include #include -#include #include #include #include #include -#include "control_shape.hpp" #include "expression.hpp" #include "page_layout.hpp" #include "shell_parts.hpp" @@ -128,17 +120,8 @@ struct Catalog { /// @brief A `Catalog::view` or `Catalog::wizard` lookup over documents by action id. /// @param documents The documents by action id; the lookup keeps its own copy. /// @return The lookup. -[[nodiscard]] inline std::function(std::string_view)> documentLookup( - std::map> documents) { - return [known = std::make_shared> const>(std::move(documents))]( - std::string_view actionId) -> std::optional { - auto const found = known->find(actionId); - if (found == known->end()) { - return std::nullopt; - } - return found->second; - }; -} +[[nodiscard]] MORPH_API std::function(std::string_view)> documentLookup( + std::map> documents); /// @brief Options of `loadDocument`. struct LoadOptions { @@ -656,28 +639,6 @@ struct Document { namespace detail { -/// @brief The exception the loader throws inside itself; `loadDocument` turns it into its result. -class DocumentRefused : public std::runtime_error { -public: - /// @brief Wraps a refusal. - /// @param refusal The refusal. - explicit DocumentRefused(Refusal refusal) : std::runtime_error{refusal.reason}, _refusal{std::move(refusal)} {} - - /// @brief The refusal. - /// @return It. - [[nodiscard]] Refusal const& refusal() const noexcept { return _refusal; } - -private: - Refusal _refusal; -}; - -/// @brief Refuses the document. -/// @param path Where. -/// @param reason Why. -[[noreturn]] inline void refuse(std::string const& path, std::string reason) { - throw DocumentRefused{Refusal{.document = {}, .path = path, .reason = std::move(reason)}}; -} - /// @brief What shape a node key's value takes. enum class Shape : std::uint8_t { Expr, ///< An expression. @@ -740,552 +701,35 @@ struct KindSpec { std::span values = {}; // NOLINT(readability-redundant-member-init): rows leave it out }; -// NOLINTBEGIN(modernize-use-designated-initializers): the kind table reads as rows; names on every field would not. -/// @brief The keys every node takes. -inline constexpr std::array kCommonKeys = {{ - {"id", Shape::Name}, {"visible", Shape::Condition}, {"enabled", Shape::Condition}, - {"tooltip", Shape::Expr}, {"sizing", Shape::Expr}, {"minWidth", Shape::Expr}, - {"maxWidth", Shape::Expr}, {"minHeight", Shape::Expr}, {"maxHeight", Shape::Expr}, - {"alignSelf", Shape::Text}, {"bleed", Shape::Flag}, {"span", Shape::Expr}, - {"testId", Shape::Text}, {"surface", Shape::Expr}, {"autofocus", Shape::Expr}, - {"a11y", Shape::Part, "a11y"}, {"drag", Shape::Part, "drag"}, {"drop", Shape::Part, "drop"}, - {"keys", Shape::Keys}, -}}; - -/// @brief The input decorations text and the inputs take; a text refuses `description` and `labelHint`. -inline constexpr std::array kFieldKeys = {{ - {"readonly", Shape::Condition}, - {"required", Shape::Condition}, - {"errors", Shape::Expr}, - {"stale", Shape::Condition}, - {"description", Shape::Expr}, - {"labelHint", Shape::Expr}, - {"tone", Shape::Expr}, -}}; - -/// @brief The element values every element has. -inline constexpr std::array kAnyValues = {"visible", "enabled", "valid", "errors", "shownErrors"}; -/// @brief The element values of a text, date-time or slider input. -inline constexpr std::array kInputValues = {"value", "draft", "dirty", "focused", "touched"}; -/// @brief The element values of a checkbox. -inline constexpr std::array kCheckboxValues = {"checked"}; -/// @brief The element values of a select. -inline constexpr std::array kSelectValues = {"selected", "selectedOption"}; -/// @brief The element values of a tabs node: the id of the tab shown. -inline constexpr std::array kTabsValues = {"selected"}; -/// @brief The element values of a table. -inline constexpr std::array kTableValues = { - "selection", "activeKey", "sort", "filters", "viewCount", "sourceCount", "selectedCount", - "pending", "error", "hoveredKey", "page", "pageCount", "pageFirst", "pageLast"}; -/// @brief The element values of a dialog or drawer. -inline constexpr std::array kDialogValues = {"open", "ready", "submitted"}; -/// @brief The element values of a form, beside its fields. -inline constexpr std::array kFormValues = {"ready", "body", "submitted"}; -/// @brief The values of a transfer id. -inline constexpr std::array kTransferValues = {"progress", "pending", "error"}; - -/// @brief The keys of `text`. -inline constexpr std::array kTextKeys = { - {{"text", Shape::Expr}, {"spans", Shape::Expr}, {"role", Shape::Expr}, {"align", Shape::Text}}}; -/// @brief The keys of `button`. -inline constexpr std::array kButtonKeys = {{{"label", Shape::Expr}, - {"icon", Shape::Expr}, - {"emphasis", Shape::Text}, - {"style", Shape::Text}, - {"selected", Shape::Condition}, - {"onClick", Shape::Commands}, - {"onActivate", Shape::Commands}, - {"children", Shape::Nodes}, - {"shape", Shape::Text}, - {"size", Shape::Text}, - {"mono", Shape::Flag}, - {"weight", Shape::Text}}}; -/// @brief The keys of `textInput`. -inline constexpr std::array kTextInputKeys = {{{"value", Shape::Expr}, - {"placeholder", Shape::Expr}, - {"mode", Shape::Expr}, - {"icon", Shape::Expr}, - {"unit", Shape::Expr}, - {"decimals", Shape::Expr}, - {"prefix", Shape::Expr}, - {"emphasis", Shape::Text}, - {"mono", Shape::Flag}, - {"align", Shape::Text}, - {"commitOn", Shape::Text}, - {"label", Shape::Expr}, - {"showLabel", Shape::Flag}, - {"onChange", Shape::Commands}, - {"onCommit", Shape::Commands}, - {"onSubmit", Shape::Commands}}}; -/// @brief The keys of `checkbox`. -inline constexpr std::array kCheckboxKeys = { - {{"label", Shape::Expr}, {"checked", Shape::Expr}, {"onToggle", Shape::Commands}, {"onChange", Shape::Commands}}}; -/// @brief The keys of `select`. -inline constexpr std::array kSelectKeys = {{{"options", Shape::Expr}, - {"selected", Shape::Expr}, - {"style", Shape::Expr}, - {"label", Shape::Expr}, - {"showLabel", Shape::Flag}, - {"onStale", Shape::Text}, - {"onChoose", Shape::Commands}, - {"onChange", Shape::Commands}}}; -/// @brief The keys of `menu`; `label`, `icon` and `emphasis` are a button-style menu's trigger. -inline constexpr std::array kMenuKeys = {{{"items", Shape::Parts, "menuItem"}, - {"style", Shape::Text}, - {"label", Shape::Expr}, - {"icon", Shape::Expr}, - {"emphasis", Shape::Text}}}; -/// @brief The keys of a menu item part. -inline constexpr std::array kMenuItemKeys = {{{"label", Shape::Expr}, - {"icon", Shape::Expr}, - {"keys", Shape::Text}, - {"checked", Shape::Expr}, - {"enabled", Shape::Condition}, - {"onClick", Shape::Commands}, - {"items", Shape::Parts, "menuItem"}, - {"separator", Shape::Flag}, - {"description", Shape::Expr}, - {"visible", Shape::Condition}}}; -/// @brief The keys of a `headMenuItem` part: an entry of a screen head's own menu, a menu item with the `id` that -/// `ScreenHead::choose` takes; its submenu's entries are head menu items too. -inline constexpr std::array kHeadMenuItemKeys = {{{"id", Shape::Name}, - {"label", Shape::Expr}, - {"icon", Shape::Expr}, - {"keys", Shape::Text}, - {"checked", Shape::Expr}, - {"enabled", Shape::Condition}, - {"onClick", Shape::Commands}, - {"items", Shape::Parts, "headMenuItem"}, - {"separator", Shape::Flag}, - {"description", Shape::Expr}, - {"visible", Shape::Condition}}}; -/// @brief The keys of a `headTool` part: a search field or a select of a screen's head. -inline constexpr std::array kHeadToolKeys = {{{"id", Shape::Name, {}, kRequired}, - {"kind", Shape::Text, {}, kRequired}, - {"label", Shape::Expr, {}, kRequired}, - {"value", Shape::Expr}, - {"placeholder", Shape::Expr}, - {"onChange", Shape::Commands}, - {"onSubmit", Shape::Commands}, - {"options", Shape::Expr}, - {"selected", Shape::Expr}, - {"style", Shape::Text}, - {"onChoose", Shape::Commands}, - {"width", Shape::Expr}, - {"visible", Shape::Condition}, - {"enabled", Shape::Condition}}}; -/// @brief The keys of `column` and `row`; `wrap` is a row's, read on a column only to refuse it, and `divided` a -/// column's or a row's that does not wrap. -inline constexpr std::array kContainerKeys = {{{"children", Shape::Nodes}, - {"gap", Shape::Expr}, - {"padding", Shape::Expr}, - {"align", Shape::Text}, - {"justify", Shape::Text}, - {"wrap", Shape::Flag}, - {"divided", Shape::Flag}, - {"pageEdge", Shape::Flag}, - {"headJoined", Shape::Flag}, - {"selected", Shape::Condition}}}; -/// @brief The keys of `grid`; `justify` and `selected` are read only to refuse them. -inline constexpr std::array kGridKeys = {{{"children", Shape::Nodes}, - {"gap", Shape::Expr}, - {"columns", Shape::Expr}, - {"minColumnWidth", Shape::Expr}, - {"tracks", Shape::Parts, "track"}, - {"align", Shape::Text}, - {"justify", Shape::Text}, - {"selected", Shape::Condition}}}; -/// @brief The keys of a `grid` track part. -inline constexpr std::array kTrackKeys = {{{"width", Shape::Expr}, {"align", Shape::Text}}}; -/// @brief The keys of `panel`. -inline constexpr std::array kPanelKeys = {{{"title", Shape::Expr}, - {"gap", Shape::Expr}, - {"header", Shape::Nodes}, - {"padding", Shape::Expr}, - {"collapsible", Shape::Expr}, - {"collapsed", Shape::Expr}, - {"onToggle", Shape::Commands}, - {"children", Shape::Nodes}}}; -/// @brief The keys of `scroll`. -inline constexpr std::array kScrollKeys = {{{"axis", Shape::Expr}, {"children", Shape::Nodes}}}; -/// @brief The keys of `switch`. -inline constexpr std::array kSwitchKeys = { - {{"on", Shape::Expr, {}, kRequired}, {"cases", Shape::Parts, "case"}, {"default", Shape::Nodes}}}; -/// @brief The keys of a `switch` case part. -inline constexpr std::array kCaseKeys = { - {{"when", Shape::Expr, {}, kRequired}, {"children", Shape::Nodes, {}, kInner}}}; -/// @brief The keys of `tabs`. -inline constexpr std::array kTabsKeys = {{{"tabs", Shape::Parts, "tab"}, - {"selected", Shape::Expr}, - {"onChoose", Shape::Commands}, - {"moreLabel", Shape::Expr}, - {"inset", Shape::Expr}, - {"pageInset", Shape::Expr}, - {"stripSurface", Shape::Text}}}; -/// @brief The keys of a `tabs` page part. -inline constexpr std::array kTabKeys = { - {{"id", Shape::Name}, {"label", Shape::Expr}, {"children", Shape::Nodes}}}; -/// @brief The keys of `dialog` and `drawer`. -inline constexpr std::array kDialogKeys = {{{"open", Shape::Condition}, - {"gap", Shape::Expr}, - {"title", Shape::Expr}, - {"description", Shape::Expr}, - {"showErrors", Shape::Text}, - {"children", Shape::Nodes, {}, kInner}, - {"onDismiss", Shape::Commands}, - {"default", Shape::Commands, {}, kInner}, - {"cancel", Shape::Commands, {}, kInner}, - {"actions", Shape::Parts, "actionButton", kInner}, - {"side", Shape::Expr}, - {"sheet", Shape::Condition}, - {"dismissLabel", Shape::Expr}, - {"descriptionSpans", Shape::Expr}}}; -/// @brief The keys of `group`: a labelled set of inputs, lowered to a column of existing kinds. -inline constexpr std::array kGroupKeys = {{{"label", Shape::Expr}, - {"required", Shape::Condition}, - {"description", Shape::Expr}, - {"errors", Shape::Expr}, - {"gap", Shape::Expr}, - {"children", Shape::Nodes}}}; -/// @brief The keys of `busy`. -inline constexpr std::array kBusyKeys = {{{"active", Shape::Condition}, {"label", Shape::Expr}}}; -/// @brief The keys of `forEach`. -inline constexpr std::array kForEachKeys = {{{"rows", Shape::Expr, {}, kRequired}, - {"key", Shape::Expr, {}, kInner}, - {"axis", Shape::Expr}, - {"gap", Shape::Expr}, - {"wrap", Shape::Flag}, - {"divided", Shape::Flag}, - {"children", Shape::Nodes, {}, kInner}}}; -/// @brief The keys of `table`. -inline constexpr std::array kTableKeys = {{{"rows", Shape::Expr}, - {"key", Shape::Expr, {}, kInner}, - {"model", Shape::Name}, - {"action", Shape::Text}, - {"body", Shape::Expr}, - {"mode", Shape::Expr}, - {"columns", Shape::PartsOrExpr, "column"}, - {"showHeader", Shape::Flag}, - {"virtualizeThreshold", Shape::Expr}, - {"virtualizeOverscan", Shape::Expr}, - {"selectionMode", Shape::Expr}, - {"selection", Shape::Expr}, - {"onSelectionChange", Shape::Commands}, - {"selectColumn", Shape::Flag}, - {"selectAllLabel", Shape::Expr}, - {"rowLabel", Shape::Expr, {}, kInner}, - {"sort", Shape::Expr}, - {"onSortChange", Shape::Commands}, - {"pageSize", Shape::Expr}, - {"page", Shape::Expr}, - {"group", Shape::Part, "group"}, - {"filters", Shape::Expr}, - {"rowTone", Shape::Expr, {}, kInner}, - {"rowSpans", Shape::Expr, {}, kInner}, - {"highlightKey", Shape::Expr}, - {"onActivate", Shape::Commands, {}, kInner}, - {"valign", Shape::Text}, - {"empty", Shape::Nodes}}}; -/// @brief The keys of a `table` column part. -inline constexpr std::array kColumnKeys = {{{"id", Shape::Name}, - {"label", Shape::Expr}, - {"width", Shape::Expr}, - {"role", Shape::Expr}, - {"align", Shape::Text}, - {"valign", Shape::Text}, - {"sortable", Shape::Flag}, - {"wrap", Shape::Flag}, - {"shrink", Shape::Flag}, - {"sortBy", Shape::Expr, {}, kInner}, - {"cell", Shape::Nodes, {}, kInner}}}; -/// @brief The keys of a `table` group part: the value its rows are grouped by, and the heading drawn before each -/// group, both read in the row scope. -inline constexpr std::array kTableGroupKeys = { - {{"by", Shape::Expr, {}, kInner | kRequired}, {"heading", Shape::Nodes, {}, kInner | kRequired}}}; -/// @brief The keys of `dateTimeInput`. -inline constexpr std::array kDateTimeKeys = {{{"value", Shape::Expr}, - {"mode", Shape::Expr}, - {"label", Shape::Expr}, - {"showLabel", Shape::Flag}, - {"onChange", Shape::Commands}, - {"onCommit", Shape::Commands}}}; -/// @brief The keys of `slider`. -inline constexpr std::array kSliderKeys = {{{"value", Shape::Expr}, - {"min", Shape::Expr}, - {"max", Shape::Expr}, - {"step", Shape::Expr}, - {"label", Shape::Expr}, - {"onChange", Shape::Commands}, - {"onCommit", Shape::Commands}}}; -/// @brief The keys of `filePicker`. -inline constexpr std::array kFilePickerKeys = {{{"accept", Shape::Expr}, - {"multiple", Shape::Expr}, - {"mode", Shape::Expr}, - {"label", Shape::Expr}, - {"onPick", Shape::Commands}}}; -/// @brief The keys of `banner`. -inline constexpr std::array kBannerKeys = {{{"tone", Shape::Expr}, - {"text", Shape::Expr}, - {"spans", Shape::Expr}, - {"dismissible", Shape::Expr}, - {"action", Shape::Part, "action"}, - {"actionStyle", Shape::Text}, - {"actionStretch", Shape::Flag}, - {"onDismiss", Shape::Commands}}}; -/// @brief The keys of an `action` part. -inline constexpr std::array kActionKeys = {{{"label", Shape::Expr}, {"onClick", Shape::Commands}}}; -/// @brief The keys of an `actionButton` part: a button a screen's head or an overlay's footer shows. -inline constexpr std::array kActionButtonKeys = {{{"id", Shape::Name, {}, kRequired}, - {"label", Shape::Expr, {}, kRequired}, - {"icon", Shape::Expr}, - {"iconOnly", Shape::Condition}, - {"emphasis", Shape::Text}, - {"enabled", Shape::Condition}, - {"visible", Shape::Condition}, - {"onClick", Shape::Commands}}}; -/// @brief The keys of a `headBadge` part: a status badge of a screen's head. -inline constexpr std::array kHeadBadgeKeys = { - {{"tone", Shape::Expr}, {"text", Shape::Expr}, {"icon", Shape::Expr}, {"visible", Shape::Condition}}}; -/// @brief The keys of a `navigationBadge` part: a count the app document puts on a navigator entry. `screen` is the -/// screen id the entry opens, a literal; the rest are read in the app scope. -inline constexpr std::array kNavigationBadgeKeys = {{{"screen", Shape::Text, {}, kRequired}, - {"text", Shape::Expr}, - {"tone", Shape::Expr}, - {"visible", Shape::Condition}}}; -/// @brief The keys of `badge`. -inline constexpr std::array kBadgeKeys = {{{"tone", Shape::Expr}, - {"text", Shape::Expr}, - {"icon", Shape::Expr}, - {"style", Shape::Text}, - {"onRemove", Shape::Commands}, - {"removeLabel", Shape::Expr}, - {"shape", Shape::Text}, - {"mono", Shape::Flag}}}; -/// @brief The keys of `progress`. -inline constexpr std::array kProgressKeys = {{{"value", Shape::Expr}, {"label", Shape::Expr}}}; -/// @brief The keys of `steps`. -inline constexpr std::array kStepsKeys = { - {{"items", Shape::Expr}, {"current", Shape::Expr}, {"labelled", Shape::Condition}}}; -/// @brief The keys of `keyValue`. -inline constexpr std::array kKeyValueKeys = { - {{"items", Shape::Expr}, {"fieldLayout", Shape::Text}, {"captionWidth", Shape::Expr}}}; -/// @brief The keys of `emptyState`. -inline constexpr std::array kEmptyStateKeys = { - {{"title", Shape::Expr}, {"text", Shape::Expr}, {"icon", Shape::Expr}, {"action", Shape::Part, "action"}}}; -/// @brief The keys of `chart`. -inline constexpr std::array kChartKeys = {{{"summary", Shape::Expr, {}, kRequired}, - {"series", Shape::Parts, "series", kRequired}, - {"lines", Shape::Parts, "line"}, - {"yMin", Shape::Expr}, - {"yMax", Shape::Expr}, - {"yPlaces", Shape::Expr}, - {"yLabel", Shape::Expr}}}; -/// @brief The keys of a chart's `series` part. The keys read per point are evaluated in the part's row scope, with -/// `row` the point's element. -inline constexpr std::array kSeriesKeys = {{{"points", Shape::Expr, {}, kRequired}, - {"y", Shape::Expr, {}, kRequired | kInner}, - {"x", Shape::Expr, {}, kInner}, - {"xLabel", Shape::Expr, {}, kInner}, - {"tone", Shape::Expr, {}, kInner}, - {"note", Shape::Expr, {}, kInner}, - {"label", Shape::Expr}, - {"joined", Shape::Flag}, - {"style", Shape::Text}}}; -/// @brief The keys of a chart's reference `line` part. -inline constexpr std::array kLineKeys = { - {{"value", Shape::Expr, {}, kRequired}, {"label", Shape::Expr}, {"tone", Shape::Expr}, {"style", Shape::Text}}}; -/// @brief The keys of `splitter`. -inline constexpr std::array kSplitterKeys = { - {{"orientation", Shape::Expr}, {"sizes", Shape::Expr}, {"children", Shape::Nodes}}}; -/// @brief The keys of `collapsible`. -inline constexpr std::array kCollapsibleKeys = {{{"title", Shape::Expr}, - {"gap", Shape::Expr}, - {"open", Shape::Condition}, - {"header", Shape::Nodes}, - {"children", Shape::Nodes}, - {"onToggle", Shape::Commands}}}; /// @brief Why an action bar takes no `gap`, and a horizontal `forEach` directly in it takes none either. inline constexpr char const* kActionBarGapRefusal = "an action bar's gap is the theme's `actions.gap`; set it there, not on the row"; -/// @brief The keys of `actionBar`; `gap` is read only to refuse it: its gap is the theme's. -inline constexpr std::array kActionBarKeys = {{{"children", Shape::Nodes}, - {"align", Shape::Text}, - {"justify", Shape::Text}, - {"gap", Shape::Expr}, - {"wrap", Shape::Flag}}}; -/// @brief The keys of `dropZone`. -inline constexpr std::array kDropZoneKeys = { - {{"accept", Shape::Expr}, {"multiple", Shape::Expr}, {"children", Shape::Nodes}, {"onDrop", Shape::Commands}}}; -/// @brief The keys of `page`: its sheet's size and margins as literal micrometres. -inline constexpr std::array kPageKeys = {{{"width", Shape::Expr, {}, kRequired}, - {"height", Shape::Expr, {}, kRequired}, - {"margins", Shape::Expr}, - {"children", Shape::Nodes}}}; -/// @brief The keys of `pageRegion`: its anchor and place as literal micrometres. -inline constexpr std::array kPageRegionKeys = {{{"anchor", Shape::Text, {}, kRequired}, - {"x", Shape::Expr}, - {"y", Shape::Expr}, - {"width", Shape::Expr}, - {"height", Shape::Expr}, - {"children", Shape::Nodes}}}; -/// @brief The keys of `localeScope`. -inline constexpr std::array kLocaleScopeKeys = { - {{"locale", Shape::Expr, {}, kRequired}, {"children", Shape::Nodes}}}; -/// @brief The keys of `customize`. -inline constexpr std::array kCustomizeKeys = {{{"point", Shape::Name, {}, kRequired}}}; -/// @brief The keys of `boundary`. -inline constexpr std::array kBoundaryKeys = { - {{"loading", Shape::Nodes}, {"error", Shape::Nodes, {}, kBoundaryError}, {"children", Shape::Nodes}}}; -/// @brief The keys of `form`. -inline constexpr std::array kFormKeys = {{{"model", Shape::Name, {}, kRequired}, - {"action", Shape::Text, {}, kRequired}, - {"prefill", Shape::Expr}, - {"key", Shape::Expr}, - {"submit", Shape::Text}, - {"showErrors", Shape::Text}, - {"fields", Shape::ExprRecord, "fields"}, - {"onSubmit", Shape::Commands}, - {"onSuccess", Shape::Commands}, - {"onError", Shape::Commands}, - {"title", Shape::Expr}, - {"submitLabel", Shape::Expr}, - {"showStatus", Shape::Flag}, - {"columns", Shape::Expr}, - {"fieldLayout", Shape::Text}, - {"captionWidth", Shape::Expr}}}; -/// @brief The keys of `collection` and `wizard`: the model and action, and the presentation keys that reach every -/// form the view draws. -inline constexpr std::array kCollectionKeys = {{{"model", Shape::Name, {}, kRequired}, - {"action", Shape::Text, {}, kRequired}, - {"title", Shape::Expr}, - {"submitLabel", Shape::Expr}, - {"showStatus", Shape::Flag}, - {"columns", Shape::Expr}, - {"fieldLayout", Shape::Text}, - {"captionWidth", Shape::Expr}}}; -/// @brief The keys of `custom`. -inline constexpr std::array kCustomKeys = { - {{"name", Shape::Text, {}, kRequired}, {"props", Shape::ExprRecord}, {"on", Shape::CommandRecord}}}; -/// @brief The keys of an `a11y` part. -inline constexpr std::array kA11yKeys = {{{"name", Shape::Expr}, {"role", Shape::Text}}}; -/// @brief The keys of a `drag` part. -inline constexpr std::array kDragKeys = {{{"payload", Shape::Expr, {}, kRequired}}}; -/// @brief The keys of a `drop` part. -inline constexpr std::array kDropKeys = {{{"accepts", Shape::Expr}, {"onDrop", Shape::Commands}}}; -/// @brief The view node kinds of `ui/1` and the part kinds inside them. -inline constexpr std::array kKinds = {{ - {"text", kTextKeys, kField}, - {"button", kButtonKeys}, - {"textInput", kTextInputKeys, kField | kWritable, kInputValues}, - {"checkbox", kCheckboxKeys, kField | kWritable, kCheckboxValues}, - {"select", kSelectKeys, kField | kWritable, kSelectValues}, - {"menu", kMenuKeys}, - {"column", kContainerKeys}, - {"row", kContainerKeys}, - {"group", kGroupKeys}, - {"grid", kGridKeys}, - {"spacer", {}}, - {"panel", kPanelKeys}, - {"scroll", kScrollKeys}, - {"switch", kSwitchKeys}, - {"tabs", kTabsKeys, 0, kTabsValues}, - {"dialog", kDialogKeys, kScope, kDialogValues}, - {"drawer", kDialogKeys, kScope, kDialogValues}, - {"busy", kBusyKeys}, - {"forEach", kForEachKeys, kScope | kRowScope}, - {"table", kTableKeys, kScope | kRowScope, kTableValues}, - {"dateTimeInput", kDateTimeKeys, kField | kWritable, kInputValues}, - {"slider", kSliderKeys, kField | kWritable, kInputValues}, - {"filePicker", kFilePickerKeys, kField}, - {"banner", kBannerKeys}, - {"badge", kBadgeKeys}, - {"progress", kProgressKeys}, - {"steps", kStepsKeys}, - {"keyValue", kKeyValueKeys}, - {"emptyState", kEmptyStateKeys}, - {"chart", kChartKeys}, - {"splitter", kSplitterKeys}, - {"collapsible", kCollapsibleKeys}, - {"dropZone", kDropZoneKeys}, - {"actionBar", kActionBarKeys}, - {"page", kPageKeys}, - {"pageRegion", kPageRegionKeys}, - {"localeScope", kLocaleScopeKeys}, - {"customize", kCustomizeKeys}, - {"boundary", kBoundaryKeys}, - {"form", kFormKeys, kOpenValues, kFormValues}, - {"collection", kCollectionKeys}, - {"wizard", kCollectionKeys}, - {"custom", kCustomKeys}, - {"menuItem", kMenuItemKeys, kPart}, - {"case", kCaseKeys, kPart | kScope}, - {"tab", kTabKeys, kPart}, - {"column", kColumnKeys, kPart}, - {"group", kTableGroupKeys, kPart}, - {"track", kTrackKeys, kPart}, - {"action", kActionKeys, kPart}, - {"a11y", kA11yKeys, kPart}, - {"drag", kDragKeys, kPart}, - {"drop", kDropKeys, kPart}, - {"actionButton", kActionButtonKeys, kPart}, - {"headBadge", kHeadBadgeKeys, kPart}, - {"headMenuItem", kHeadMenuItemKeys, kPart}, - {"headTool", kHeadToolKeys, kPart}, - {"navigationBadge", kNavigationBadgeKeys, kPart}, - {"fields", {}, kPart}, - {"series", kSeriesKeys, kPart | kRowScope}, - {"line", kLineKeys, kPart}, -}}; -// NOLINTEND(modernize-use-designated-initializers) +/// @brief What a name in a scope declares. +enum class NameCategory : std::uint8_t { + Param, ///< A screen param. + Model, ///< A model alias. + State, ///< State. + Let, ///< A derived value. + Query, ///< A query. + Mutation, ///< A mutation. + Element, ///< An element id. + Transfer, ///< A transfer id of `upload`. +}; -/// @brief A literal length of a page node: an integer count of micrometres. -/// @param expr The key's expression. -/// @param key The key, for the refusal. -/// @return The length. -[[nodiscard]] inline Mm pageLengthOf(ExprPtr const& expr, std::string_view key) { - std::int64_t const* const count = expr->kind == ExprKind::Literal ? expr->literal.asInt() : nullptr; - if (count == nullptr || *count < 0 || *count > std::numeric_limits::max()) { - refuse(expr->path, "`" + std::string{key} + "` is a literal integer count of micrometres, 0 or more"); - } - return Mm::fromMicrometres(static_cast(*count)); +/// @brief Whether a list of names holds one. +/// @param names The list. +/// @param name The candidate. +/// @return Whether @p name is in @p names. +[[nodiscard]] inline bool listed(std::span names, std::string_view name) { + return std::ranges::find(names, name) != names.end(); } /// @brief A page node's geometry, from its literal keys; the loader has checked nothing about it yet. /// @param node A `page` node. /// @return The geometry. /// @throws DocumentRefused when a key is not a literal length, or the geometry is not valid. -[[nodiscard]] inline PageGeometry pageGeometryOf(DocNode const& node) { - PageGeometry geometry; - geometry.width = pageLengthOf(node.prop("width"), "width"); - geometry.height = pageLengthOf(node.prop("height"), "height"); - if (ExprPtr const margins = node.prop("margins")) { - if (margins->kind == ExprKind::Literal && margins->literal.asRecord() != nullptr) { - ValueRecord const& record = *margins->literal.asRecord(); - for (auto const& [side, amount] : record) { - std::int64_t const* const count = amount.asInt(); - Mm* const target = side == "top" ? &geometry.margins.top - : side == "right" ? &geometry.margins.right - : side == "bottom" ? &geometry.margins.bottom - : side == "left" ? &geometry.margins.left - : nullptr; - if (target == nullptr || count == nullptr || *count < 0 || - *count > std::numeric_limits::max()) { - refuse(margins->path, - "`margins` is a literal count of micrometres, or a record of `top`, `right`, " - "`bottom` and `left` counts"); - } - *target = Mm::fromMicrometres(static_cast(*count)); - } - } else { - geometry.margins = PageMargins{pageLengthOf(margins, "margins")}; - } - } - if (std::optional const problem = geometry.problem()) { - refuse(node.path, *problem); - } - return geometry; -} +[[nodiscard]] MORPH_API PageGeometry pageGeometryOf(DocNode const& node); /// @brief A page region's geometry, from its literal keys. /// @param node A `pageRegion` node. @@ -1293,4356 +737,39 @@ inline constexpr std::array kKinds = {{ /// @return The geometry. /// @throws DocumentRefused when a key is not a literal length, the anchor is unknown, or the region is not valid on /// the sheet. -[[nodiscard]] inline RegionGeometry regionGeometryOf(DocNode const& node, PageGeometry const& page) { - RegionGeometry geometry; - std::string_view const anchor = node.name("anchor"); - if (anchor == "top") { - geometry.anchor = PageAnchor::Top; - } else if (anchor == "bottom") { - geometry.anchor = PageAnchor::Bottom; - } else if (anchor == "offset") { - geometry.anchor = PageAnchor::Offset; - } else { - refuse(pointerAppend(node.path, "anchor"), "`anchor` is `top`, `bottom` or `offset`"); - } - if (ExprPtr const x = node.prop("x")) { - geometry.x = pageLengthOf(x, "x"); - } - if (ExprPtr const y = node.prop("y")) { - geometry.y = pageLengthOf(y, "y"); - } - if (ExprPtr const width = node.prop("width")) { - geometry.width = pageLengthOf(width, "width"); - } - if (ExprPtr const height = node.prop("height")) { - geometry.height = pageLengthOf(height, "height"); - } - if (std::optional const problem = geometry.problem(page)) { - refuse(node.path, *problem); - } - return geometry; -} +[[nodiscard]] MORPH_API RegionGeometry regionGeometryOf(DocNode const& node, PageGeometry const& page); /// @brief Looks up a node kind or a part kind. /// @param kind The kind. /// @param part Whether a part kind is wanted. /// @return The spec, or `nullptr`. -[[nodiscard]] inline KindSpec const* findKind(std::string_view kind, bool part) { - for (KindSpec const& spec : kKinds) { - if (spec.kind == kind && ((spec.flags & kPart) != 0) == part) { - return &spec; - } - } - return nullptr; -} - -/// @brief Whether a list of names holds one. -/// @param names The list. -/// @param name The candidate. -/// @return Whether @p name is in @p names. -[[nodiscard]] inline bool listed(std::span names, std::string_view name) { - return std::ranges::find(names, name) != names.end(); -} - -/// @brief Refuses a must-understand key (`!name`) the client does not know; other unknown keys are ignored. -/// @param object The JSON object. -/// @param path Its JSON Pointer. -inline void refuseMustUnderstand(Json::object_t const& object, std::string const& path) { - for (auto const& [key, value] : object) { - static_cast(value); - if (key.starts_with('!')) { - refuse(pointerAppend(path, key), "the must-understand key `" + key + "` is not part of ui/1"); - } - } -} - -/// @brief Parses a key chord, and refuses one the workspace shell reserves. -/// @param chord The chord, such as `Ctrl+Shift+K`. -/// @param path Its JSON Pointer. -// NOLINTNEXTLINE(readability-function-cognitive-complexity): a chord's grammar, modifiers then one key name. -inline void checkChord(std::string const& chord, std::string const& path) { - static constexpr std::array kModifiers = {"Ctrl", "Shift", "Alt", "Meta"}; - static constexpr std::array kNamedKeys = {"Enter", "Esc", "Tab", "Up", "Down", - "Left", "Right", "Space", "Delete"}; - std::vector parts; - std::size_t start = 0; - for (std::size_t plus = chord.find('+'); plus != std::string::npos; plus = chord.find('+', start)) { - parts.push_back(std::string_view{chord}.substr(start, plus - start)); - start = plus + 1; - } - std::string_view const key = std::string_view{chord}.substr(start); - std::set modifiers; - for (std::string_view const modifier : parts) { - if (!listed(kModifiers, modifier) || !modifiers.insert(modifier).second) { - refuse(path, "`" + chord + "` is not a chord: modifiers are Ctrl, Shift, Alt and Meta, once each"); - } - } - bool const letterOrDigit = - key.size() == 1 && ((key.front() >= 'A' && key.front() <= 'Z') || (key.front() >= 'a' && key.front() <= 'z') || - (key.front() >= '0' && key.front() <= '9')); - bool function = key.size() >= 2 && key.size() <= 3 && key.front() == 'F'; - int number = 0; - for (char const chr : key.substr(function ? 1 : key.size())) { - function = function && chr >= '0' && chr <= '9'; - number = (number * 10) + (chr - '0'); - } - function = function && number >= 1 && number <= 24; - if (!letterOrDigit && !function && !listed(kNamedKeys, key)) { - refuse(path, "`" + chord + "` does not end in a key name"); - } - bool const ctrlOnly = modifiers.size() == 1 && modifiers.contains("Ctrl"); - bool const ctrlShift = modifiers.size() == 2 && modifiers.contains("Ctrl") && modifiers.contains("Shift"); - bool const reserved = (key == "Tab" && (ctrlOnly || ctrlShift)) || - (ctrlOnly && (key == "W" || key == "w" || key == "K" || key == "k")); - if (reserved) { - refuse(path, "`" + chord + "` is reserved for the workspace shell"); - } -} - -// NOLINTBEGIN(misc-no-recursion): a document is a tree of nodes and command lists, and parsing descends it. -/// @brief Turns the JSON of a document into its model, refusing what does not parse. -class DocumentParser { -public: - /// @brief Parses the whole document. - /// @param json The document. - /// @return The model, not yet checked against its names. - [[nodiscard]] Document parse(Json const& json) { - auto const* const object = std::get_if(&json.data); - if (object == nullptr) { - refuse("", "a document is a JSON object"); - } - refuseMustUnderstand(*object, ""); - Document doc; - doc.vocab = text(*object, "vocab", "", true); - if (doc.vocab != kVocabulary) { - refuse("/vocab", "the vocabulary `" + doc.vocab + "` is not supported; this client reads ui/1"); - } - doc.id = text(*object, "id", "", true); - if (doc.id.empty()) { - refuse("/id", "a document has a non-empty id"); - } - doc.title = optionalExpr(*object, "title", ""); - doc.identity = optionalExpr(*object, "identity", ""); - doc.dirty = optionalExpr(*object, "dirty", ""); - doc.titleSpans = optionalExpr(*object, "titleSpans", ""); - doc.eyebrow = optionalExpr(*object, "eyebrow", ""); - doc.eyebrowSpans = optionalExpr(*object, "eyebrowSpans", ""); - doc.subtitle = optionalExpr(*object, "subtitle", ""); - doc.subtitleSpans = optionalExpr(*object, "subtitleSpans", ""); - doc.leadPlacement = optionalExpr(*object, "leadPlacement", ""); - checkLeadPlacementLiteral(doc.leadPlacement); - doc.titleRole = optionalExpr(*object, "titleRole", ""); - checkTitleRoleLiteral(doc.titleRole); - doc.headSurface = optionalExpr(*object, "headSurface", ""); - doc.pageSurface = optionalExpr(*object, "pageSurface", ""); - doc.status = topParts(*object, "status", "headBadge"); - doc.actions = topParts(*object, "actions", "actionButton"); - doc.menu = topParts(*object, "menu", "headMenuItem"); - doc.menuLabel = optionalExpr(*object, "menuLabel", ""); - doc.tools = topParts(*object, "tools", "headTool"); - doc.navigation = navigation(*object, doc.id); - if (doc.id == "app") { - refuseScreenHead(*object); - } - static constexpr std::array kPrincipalPlacements = {"sidebar", "head"}; - doc.principalPlacement = choiceOf(*object, "principalPlacement", "", kPrincipalPlacements); - if (doc.id != "app" && member(*object, "principalPlacement") != nullptr) { - refuse("/principalPlacement", "`principalPlacement` is the app document's; a screen has none"); - } - doc.showErrors = showErrors(*object, ""); - datePatterns(*object, doc); - if (Json const* const params = member(*object, "params")) { - for (auto const& [name, type] : objectOf(*params, "/params", "`params` maps names to types")) { - std::string const path = pointerAppend("/params", name); - checkName(name, path); - doc.params.emplace_back(name, typeOf(type, path)); - } - } - doc.scope = scope(*object, ""); - shellParts(*object, doc); - for (std::string_view const key : {"onMount", "onUnmount", "onClose", "onSave", "onBackendChange"}) { - if (Json const* const commands = member(*object, key)) { - doc.lifecycle.emplace(std::string{key}, commandList(*commands, pointerAppend("", key))); - } - } - if (Json const* const keys = member(*object, "keys")) { - doc.keys = keyBindings(*keys, "/keys"); - } - if (Json const* const prefetch = member(*object, "prefetch")) { - doc.prefetch = nameList(*prefetch, "/prefetch"); - } - if (Json const* const components = member(*object, "components")) { - for (auto const& [name, entry] : objectOf(*components, "/components", "`components` is an object")) { - doc.components.emplace(name, component(name, entry, pointerAppend("/components", name))); - } - } - if (Json const* const points = member(*object, "customize")) { - for (auto const& [name, entry] : objectOf(*points, "/customize", "`customize` is an object")) { - doc.customize.emplace(name, point(name, entry, pointerAppend("/customize", name), doc.id == "app")); - } - } - if (Json const* const view = member(*object, "view")) { - doc.view = node(*view, "/view"); - } else if (doc.id != "app") { - refuse("", "a screen has a `view`"); - } - return doc; - } - -private: - // The app document's `formatting`: a record of the date pattern and the date-and-time pattern, each checked. - static void datePatterns(Json::object_t const& object, Document& doc) { - Json const* const formatting = member(object, "formatting"); - if (formatting == nullptr) { - return; - } - if (doc.id != "app") { - refuse("/formatting", "`formatting` is the application's; only the app document declares it"); - } - for (auto const& [key, value] : objectOf(*formatting, "/formatting", "`formatting` is a record")) { - std::string const path = pointerAppend("/formatting", key); - if (key != "date" && key != "dateTime") { - refuse(path, "`formatting` takes `date` and `dateTime`"); - } - std::string const* const pattern = std::get_if(&value.data); - if (pattern == nullptr) { - refuse(path, "a date pattern is a string, such as `dd-MMM-yyyy`"); - } - if (auto const checked = checkDatePattern(*pattern, key == "dateTime"); !checked) { - refuse(path, checked.error()); - } - (key == "date" ? doc.datePattern : doc.dateTimePattern) = *pattern; - } - } - - [[nodiscard]] static Json const* member(Json::object_t const& object, std::string_view key) { - auto const* const found = object.find(key); - return found == object.end() ? nullptr : &found->second; - } - - [[nodiscard]] static Json::object_t const& objectOf(Json const& json, std::string const& path, char const* what) { - auto const* const object = std::get_if(&json.data); - if (object == nullptr) { - refuse(path, what); - } - return *object; - } - - static void checkName(std::string const& name, std::string const& path) { - if (!isName(name)) { - refuse(path, "`" + name + "` is not a name: names match [A-Za-z_][A-Za-z0-9_]*"); - } - } - - [[nodiscard]] static std::string text(Json::object_t const& object, std::string_view key, std::string const& path, - bool required) { - Json const* const value = member(object, key); - std::string const keyPath = pointerAppend(path, key); - if (value == nullptr) { - if (required) { - refuse(path, "`" + std::string{key} + "` is required"); - } - return {}; - } - auto const* const string = std::get_if(&value->data); - if (string == nullptr) { - refuse(keyPath, "`" + std::string{key} + "` is a string"); - } - return *string; - } - - [[nodiscard]] static std::string choiceOf(Json::object_t const& object, std::string_view key, - std::string const& path, std::span choices) { - std::string value = text(object, key, path, false); - if (!value.empty() && !listed(choices, value)) { - refuse(pointerAppend(path, key), "`" + value + "` is not one of the values of `" + std::string{key} + "`"); - } - return value; - } - - [[nodiscard]] static std::string showErrors(Json::object_t const& object, std::string const& path) { - static constexpr std::array kPolicies = {"touched", "submit", "always"}; - return choiceOf(object, "showErrors", path, kPolicies); - } - - [[nodiscard]] static std::int64_t integer(Json::object_t const& object, std::string_view key, - std::string const& path) { - Json const* const value = member(object, key); - if (value == nullptr) { - return 0; - } - auto const number = detail::jsonInt(*value); - if (!number || *number < 0) { - refuse(pointerAppend(path, key), "`" + std::string{key} + "` is a non-negative integer"); - } - return *number; - } - - [[nodiscard]] static bool flag(Json::object_t const& object, std::string_view key, std::string const& path) { - Json const* const value = member(object, key); - if (value == nullptr) { - return false; - } - bool const* const set = std::get_if(&value->data); - if (set == nullptr) { - refuse(pointerAppend(path, key), "`" + std::string{key} + "` is a bool"); - } - return *set; - } - - [[nodiscard]] static Type typeOf(Json const& json, std::string const& path) { - auto const* const spelled = std::get_if(&json.data); - if (spelled == nullptr) { - refuse(path, "a type is written as a string, such as `int?`"); - } - auto type = parseType(*spelled); - if (!type) { - refuse(path, type.error()); - } - return *type; - } - - [[nodiscard]] static std::vector nameList(Json const& json, std::string const& path) { - auto const* const array = std::get_if(&json.data); - if (array == nullptr) { - refuse(path, "a list of names is an array of strings"); - } - std::vector names; - for (std::size_t index = 0; index < array->size(); ++index) { - auto const* const name = std::get_if(&array->at(index).data); - if (name == nullptr || name->empty()) { - refuse(pointerAppend(path, index), "a list of names is an array of strings"); - } - names.push_back(*name); - } - return names; - } - - [[nodiscard]] static ExprPtr expr(Json const& json, std::string const& path) { - auto parsed = parseExpression(json, path); - if (!parsed) { - throw DocumentRefused{std::move(parsed.error())}; - } - return std::move(*parsed); - } - - [[nodiscard]] static ExprPtr optionalExpr(Json::object_t const& object, std::string_view key, - std::string const& path) { - Json const* const value = member(object, key); - return value == nullptr ? nullptr : expr(*value, pointerAppend(path, key)); - } - - // The head belongs to a screen's tab; the app document has no view and so no head. - static void refuseScreenHead(Json::object_t const& object) { - for (std::string_view const key : - {"titleSpans", "eyebrow", "eyebrowSpans", "subtitle", "subtitleSpans", "leadPlacement", "titleRole", - "headSurface", "pageSurface", "status", "actions", "menu", "menuLabel", "tools"}) { - if (member(object, key) != nullptr) { - refuse(pointerAppend("", key), "`" + std::string{key} + "` is a screen's; the app document has none"); - } - } - } - - // A `leadPlacement` written as a literal is one of the three places; a computed one is read at run time. - static void checkLeadPlacementLiteral(ExprPtr const& placement) { - if (placement == nullptr || placement->kind != ExprKind::Literal) { - return; - } - std::string const* const name = placement->literal.asString(); - if (name == nullptr || (*name != "below" && *name != "inline" && *name != "end")) { - refuse(placement->path, "`leadPlacement` is `below`, `inline` or `end`"); - } - } - - // A `titleRole` written as a literal is one of the two roles a head's title takes; a computed one is read at run - // time. - static void checkTitleRoleLiteral(ExprPtr const& role) { - if (role == nullptr || role->kind != ExprKind::Literal) { - return; - } - std::string const* const name = role->literal.asString(); - if (name == nullptr || (*name != "heading" && *name != "headline")) { - refuse(role->path, "`titleRole` is `heading` or `headline`"); - } - } - - // The app document's `navigation` badges, each naming its screen; a screen declares none. - [[nodiscard]] std::vector navigation(Json::object_t const& object, std::string_view documentId) { - std::vector badges = topParts(object, "navigation", "navigationBadge"); - if (documentId != "app" && !badges.empty()) { - refuse("/navigation", "`navigation` is the app document's; a screen has none"); - } - for (DocNodePtr const& badge : badges) { - if (badge->name("screen").empty()) { - refuse(pointerAppend(badge->path, "screen"), "a navigation badge names the screen of its entry"); - } - } - return badges; - } - - // A top-level list of parts: the screen head's `status` and `actions`. - // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the document key, then its part kind, at every call. - [[nodiscard]] std::vector topParts(Json::object_t const& object, std::string_view key, - std::string_view kind) { - std::vector parts; - Json const* const value = member(object, key); - if (value == nullptr) { - return parts; - } - std::string const path = pointerAppend("", key); - auto const* const array = std::get_if(&value->data); - if (array == nullptr) { - refuse(path, "`" + std::string{key} + "` is an array"); - } - for (std::size_t index = 0; index < array->size(); ++index) { - parts.push_back(part(array->at(index), kind, pointerAppend(path, index))); - } - return parts; - } - - /// @brief Reads the app document's `shell` member, checks it, and appends the queries and state it lowers to. - /// @param object The document's JSON object. - /// @param doc The document being built; its scope receives the lowered declarations. - void shellParts(Json::object_t const& object, Document& doc) { - Json const* const declared = member(object, "shell"); - if (declared == nullptr) { - return; - } - if (doc.id != "app") { - refuse("/shell", "`shell` is the app document's; a screen has none"); - } - ShellParts parts; - auto const text = glz::write_json(*declared); - if (!text || glz::read_json(parts, *text)) { - refuse("/shell", - "`shell` holds the parts: context, modules, search, inbox, principal, brand, help, searchHint"); - } - checkShellParts(parts); - auto const checkNames = [](auto const& declarations) { - for (auto const& entry : declarations) { - if (shell_names::reserved(entry.name)) { - refuse(entry.path, "`" + entry.name + "` is reserved: the shell's parts declare it"); - } - } - }; - checkNames(doc.scope.models); - checkNames(doc.scope.state); - checkNames(doc.scope.lets); - checkNames(doc.scope.queries); - checkNames(doc.scope.mutations); - auto lowered = parseJson(lowerShellParts(parts)); - auto const* const loweredObject = lowered ? std::get_if(&lowered->data) : nullptr; - if (loweredObject == nullptr) { - refuse("/shell", "the shell's parts do not lower"); - } - ScopeDecl extra = scope(*loweredObject, "/shell"); - auto append = [](auto& into, auto& from) { - into.insert(into.end(), std::make_move_iterator(from.begin()), std::make_move_iterator(from.end())); - }; - append(doc.scope.models, extra.models); - append(doc.scope.state, extra.state); - append(doc.scope.queries, extra.queries); - append(doc.scope.mutations, extra.mutations); - doc.shell = std::move(parts); - } - - /// @brief Refuses a declaration that cannot be read: a repeated module, an empty required field, a repeated tag. - /// @param parts The parts. - static void checkShellParts(ShellParts const& parts) { - auto required = [](std::string const& value, std::string const& path) { - if (value.empty()) { - refuse(path, "the shell's part needs this name"); - } - }; - auto distinct = [](auto const& list, std::string const& path, auto key) { - std::set seen; - for (auto const& entry : list) { - if (!seen.insert(key(entry)).second) { - refuse(path, "the shell's parts list `" + key(entry) + "` twice"); - } - } - }; - if (parts.context) { - required(parts.context->model, "/shell/context/model"); - required(parts.context->action, "/shell/context/action"); - required(parts.context->optionsField, "/shell/context/optionsField"); - required(parts.context->labelField, "/shell/context/labelField"); - required(parts.context->valueField, "/shell/context/valueField"); - } - auto count = [&](ModuleCount const& entry, std::string const& path) { - required(entry.model, path + "/model"); - required(entry.action, path + "/action"); - required(entry.countField, path + "/countField"); - }; - for (std::size_t index = 0; index < parts.modules.size(); ++index) { - count(parts.modules.at(index), "/shell/modules/" + std::to_string(index)); - } - distinct(parts.modules, "/shell/modules", [](ModuleCount const& entry) { return entry.module; }); - for (std::size_t index = 0; index < parts.search.size(); ++index) { - std::string const path = "/shell/search/" + std::to_string(index); - required(parts.search.at(index).model, path + "/model"); - required(parts.search.at(index).action, path + "/action"); - required(parts.search.at(index).queryField, path + "/queryField"); - required(parts.search.at(index).resultsField, path + "/resultsField"); - } - distinct(parts.search, "/shell/search", [](SearchSource const& entry) { return entry.module; }); - if (parts.inbox) { - required(parts.inbox->screen, "/shell/inbox/screen"); - if (parts.inbox->sources.empty()) { - refuse("/shell/inbox/sources", "an inbox sums at least one source"); - } - for (std::size_t index = 0; index < parts.inbox->sources.size(); ++index) { - count(parts.inbox->sources.at(index), "/shell/inbox/sources/" + std::to_string(index)); - } - } - if (parts.principal) { - PrincipalMenu const& menu = *parts.principal; - required(menu.model, "/shell/principal/model"); - required(menu.action, "/shell/principal/action"); - required(menu.nameField, "/shell/principal/nameField"); - distinct(menu.locales, "/shell/principal/locales", [](std::string const& tag) { return tag; }); - distinct(menu.formats, "/shell/principal/formats", [](std::string const& tag) { return tag; }); - } - if (parts.brand) { - required(parts.brand->title, "/shell/brand/title"); - } - if (parts.help) { - HelpEntry const& help = *parts.help; - if (help.screen.empty() == help.action.empty()) { - refuse("/shell/help", "the help button opens a screen or runs an action: name one of the two"); - } - if (!help.action.empty()) { - required(help.model, "/shell/help/model"); - } else if (!help.model.empty()) { - refuse("/shell/help/model", "a model belongs to an action; the help button opens a screen"); - } - } - } - - // NOLINTNEXTLINE(readability-function-cognitive-complexity): one branch per kind of declaration. - [[nodiscard]] ScopeDecl scope(Json::object_t const& object, std::string const& path) { - ScopeDecl decl; - if (Json const* const models = member(object, "models")) { - std::string const where = pointerAppend(path, "models"); - for (auto const& [name, entry] : objectOf(*models, where, "`models` maps aliases to models")) { - decl.models.push_back(model(name, entry, pointerAppend(where, name))); - } - } - if (Json const* const state = member(object, "state")) { - std::string const where = pointerAppend(path, "state"); - for (auto const& [name, entry] : objectOf(*state, where, "`state` maps names to declarations")) { - std::string const entryPath = pointerAppend(where, name); - checkName(name, entryPath); - auto const& fields = objectOf(entry, entryPath, R"(a state declaration is {"init": e, "type": T})"); - refuseMustUnderstand(fields, entryPath); - StateDecl stateDecl{ - .name = name, .path = entryPath, .type = Type::any(), .typeDeclared = false, .init = nullptr}; - if (Json const* const type = member(fields, "type")) { - stateDecl.type = typeOf(*type, pointerAppend(entryPath, "type")); - stateDecl.typeDeclared = true; - } - stateDecl.init = optionalExpr(fields, "init", entryPath); - decl.state.push_back(std::move(stateDecl)); - } - } - if (Json const* const lets = member(object, "let")) { - std::string const where = pointerAppend(path, "let"); - for (auto const& [name, entry] : objectOf(*lets, where, "`let` maps names to expressions")) { - std::string const entryPath = pointerAppend(where, name); - checkName(name, entryPath); - decl.lets.push_back(LetDecl{.name = name, .path = entryPath, .value = expr(entry, entryPath)}); - } - } - if (Json const* const queries = member(object, "queries")) { - std::string const where = pointerAppend(path, "queries"); - for (auto const& [name, entry] : objectOf(*queries, where, "`queries` maps names to queries")) { - decl.queries.push_back(query(name, entry, pointerAppend(where, name))); - } - } - if (Json const* const mutations = member(object, "mutations")) { - std::string const where = pointerAppend(path, "mutations"); - for (auto const& [name, entry] : objectOf(*mutations, where, "`mutations` maps names to mutations")) { - decl.mutations.push_back(mutation(name, entry, pointerAppend(where, name))); - } - } - if (Json const* const watches = member(object, "watch")) { - std::string const where = pointerAppend(path, "watch"); - auto const* const array = std::get_if(&watches->data); - if (array == nullptr) { - refuse(where, "`watch` is an array"); - } - for (std::size_t index = 0; index < array->size(); ++index) { - decl.watches.push_back(watch(array->at(index), pointerAppend(where, index))); - } - } - if (Json const* const checks = member(object, "checks")) { - std::string const where = pointerAppend(path, "checks"); - auto const* const array = std::get_if(&checks->data); - if (array == nullptr) { - refuse(where, "`checks` is an array"); - } - for (std::size_t index = 0; index < array->size(); ++index) { - decl.checks.push_back(check(array->at(index), pointerAppend(where, index))); - } - } - return decl; - } - - [[nodiscard]] static ModelDecl model(std::string const& name, Json const& json, std::string const& path) { - checkName(name, path); - auto const& fields = objectOf(json, path, R"(a model alias is {"type": ..., "instance": ...})"); - refuseMustUnderstand(fields, path); - ModelDecl decl{.name = name, - .path = path, - .type = text(fields, "type", path, true), - .instance = {}, - .key = nullptr, - .borrowedFrom = {}}; - Json const* const instance = member(fields, "instance"); - if (instance == nullptr) { - return decl; - } - std::string const where = pointerAppend(path, "instance"); - auto const* const word = std::get_if(&instance->data); - if (word != nullptr && (*word == "private" || *word == "shared")) { - decl.instance = *word == "private" ? InstanceMode::Private : InstanceMode::Shared; - return decl; - } - if (auto const* const object = std::get_if(&instance->data)) { - if (Json const* const from = member(*object, "from")) { - auto const* const alias = std::get_if(&from->data); - if (alias == nullptr || !isName(*alias) || object->size() != 1) { - refuse(where, R"(a borrowed instance is {"from": alias})"); - } - decl.instance = InstanceMode::Borrowed; - decl.borrowedFrom = *alias; - return decl; - } - } - decl.instance = InstanceMode::Keyed; - decl.key = expr(*instance, where); - return decl; - } - - /// @brief Refuses @p key of @p fields: a refresh key, which a document does not declare. - /// @param fields The declaration's fields. - /// @param path The declaration's JSON Pointer. - /// @param key The refresh key: `invalidates`, `patch` or `refreshOn`. - static void refuseRefreshKey(Json::object_t const& fields, std::string const& path, std::string_view key) { - if (member(fields, key) != nullptr) { - refuse(pointerAppend(path, key), - std::format("a document does not declare `{}`: an action's effects say what it changes, and every " - "query holding a changed record refreshes; a refresh no action declares is a `refetch` " - "command", - key)); - } - } - - [[nodiscard]] static QueryDecl query(std::string const& name, Json const& json, std::string const& path) { - checkName(name, path); - auto const& fields = objectOf(json, path, "a query is an object"); - refuseMustUnderstand(fields, path); - QueryDecl decl; - decl.name = name; - decl.path = path; - decl.model = text(fields, "model", path, true); - std::string const action = text(fields, "action", path, false); - std::string const evaluate = text(fields, "evaluate", path, false); - if (action.empty() == evaluate.empty()) { - refuse(path, "a query names exactly one of `action` and `evaluate`"); - } - decl.action = action.empty() ? evaluate : action; - decl.evaluate = !evaluate.empty(); - decl.body = optionalExpr(fields, "body", path); - decl.when = optionalExpr(fields, "when", path); - decl.debounce = integer(fields, "debounce", path); - decl.refreshEvery = integer(fields, "refreshEvery", path); - decl.staleTime = integer(fields, "staleTime", path); - refuseRefreshKey(fields, path, "refreshOn"); - return decl; - } - - /// @brief Parses an `optimistic` write: `{"query": q, "at"?: m, "key": e, "with": e}`. - /// @param json The write's JSON. - /// @param path Its JSON Pointer. - /// @return The write. - [[nodiscard]] static OptimisticDecl optimistic(Json const& json, std::string const& path) { - static constexpr char const* shape = R"(an optimistic write is {"query": q, "at"?: m, "key": e, "with": e})"; - auto const& fields = objectOf(json, path, shape); - refuseMustUnderstand(fields, path); - Json const* const key = member(fields, "key"); - Json const* const with = member(fields, "with"); - if (key == nullptr || with == nullptr) { - refuse(path, shape); - } - std::string listMember = text(fields, "at", path, false); - if (member(fields, "at") != nullptr && listMember.empty()) { - refuse(pointerAppend(path, "at"), "`at` names the member of the query's record that holds the list"); - } - return OptimisticDecl{.query = text(fields, "query", path, true), - .at = std::move(listMember), - .key = expr(*key, pointerAppend(path, "key")), - .with = expr(*with, pointerAppend(path, "with"))}; - } - - [[nodiscard]] MutationDecl mutation(std::string const& name, Json const& json, std::string const& path) { - checkName(name, path); - auto const& fields = objectOf(json, path, "a mutation is an object"); - refuseMustUnderstand(fields, path); - MutationDecl decl; - decl.name = name; - decl.path = path; - decl.model = text(fields, "model", path, true); - decl.action = text(fields, "action", path, true); - decl.body = optionalExpr(fields, "body", path); - static constexpr std::array kModes = {"exclusive", "serial", "latest", "parallel"}; - std::string const mode = choiceOf(fields, "concurrency", path, kModes); - if (mode == "serial") { - decl.concurrency = Concurrency::Serial; - } else if (mode == "latest") { - decl.concurrency = Concurrency::Latest; - } else if (mode == "parallel") { - decl.concurrency = Concurrency::Parallel; - } - decl.serialKey = optionalExpr(fields, "serialKey", path); - if (decl.serialKey && decl.concurrency != Concurrency::Serial) { - refuse(pointerAppend(path, "serialKey"), "`serialKey` applies to `serial` concurrency only"); - } - refuseRefreshKey(fields, path, "invalidates"); - refuseRefreshKey(fields, path, "patch"); - if (Json const* const value = member(fields, "optimistic")) { - decl.optimistic = optimistic(*value, pointerAppend(path, "optimistic")); - } - if (Json const* const commands = member(fields, "onSuccess")) { - decl.onSuccess = commandList(*commands, pointerAppend(path, "onSuccess")); - } - if (Json const* const commands = member(fields, "onError")) { - decl.onError = commandList(*commands, pointerAppend(path, "onError")); - } - static constexpr std::array kOffline = {"queue"}; - decl.offlineQueue = !choiceOf(fields, "offline", path, kOffline).empty(); - return decl; - } - - [[nodiscard]] WatchDecl watch(Json const& json, std::string const& path) { - auto const& fields = objectOf(json, path, R"(a watch is {"on": e, "do": [...]})"); - refuseMustUnderstand(fields, path); - Json const* const watched = member(fields, "on"); - Json const* const body = member(fields, "do"); - if (watched == nullptr || body == nullptr) { - refuse(path, R"(a watch is {"on": e, "do": [...]})"); - } - static constexpr std::array kSources = {"any", "user"}; - return WatchDecl{ - .path = path, - .on = expr(*watched, pointerAppend(path, "on")), - .source = choiceOf(fields, "source", path, kSources) == "user" ? WatchSource::User : WatchSource::Any, - .body = commandList(*body, pointerAppend(path, "do"))}; - } - - [[nodiscard]] static CheckDecl check(Json const& json, std::string const& path) { - auto const& fields = objectOf(json, path, R"(a check is {"id": ..., "assert": e, ...})"); - refuseMustUnderstand(fields, path); - Json const* const assertion = member(fields, "assert"); - if (assertion == nullptr) { - refuse(path, "a check has an `assert`"); - } - CheckDecl decl; - decl.id = text(fields, "id", path, false); - decl.path = path; - decl.assertion = expr(*assertion, pointerAppend(path, "assert")); - decl.message = optionalExpr(fields, "message", path); - if (Json const* const targets = member(fields, "targets")) { - decl.targets = nameList(*targets, pointerAppend(path, "targets")); - } - decl.blocking = flag(fields, "blocking", path); - return decl; - } - - struct CommandSpec { - std::string_view key; - CommandKind kind; - std::array companions; - }; - - // NOLINTBEGIN(modernize-use-designated-initializers): one row per command reads as a table. - static constexpr std::array kCommands = {{ - {"set", CommandKind::Set, {"value"}}, - {"reset", CommandKind::Reset, {}}, - {"run", CommandKind::Run, {"body", "as", "each"}}, - {"refetch", CommandKind::Refetch, {}}, - {"open", CommandKind::Open, {}}, - {"close", CommandKind::Close, {}}, - {"navigate", CommandKind::Navigate, {"params", "as", "onResult", "onCancel"}}, - {"return", CommandKind::Return, {}}, - {"focus", CommandKind::Focus, {"row"}}, - {"host", CommandKind::Host, {"args"}}, - {"switchBackend", CommandKind::SwitchBackend, {}}, - {"resetPrefs", CommandKind::ResetPrefs, {}}, - {"setLocale", CommandKind::SetLocale, {}}, - {"setContext", CommandKind::SetContext, {}}, - {"notify", CommandKind::Notify, {"role"}}, - {"seq", CommandKind::Seq, {}}, - {"all", CommandKind::All, {}}, - {"if", CommandKind::If, {}}, - {"cancelClose", CommandKind::CancelClose, {}}, - {"retry", CommandKind::Retry, {}}, - {"signIn", CommandKind::SignIn, {}}, - {"signOut", CommandKind::SignOut, {}}, - {"upload", CommandKind::Upload, {"to", "as", "id", "into", "nameAs", "typeAs"}}, - {"download", CommandKind::Download, {"save", "name", "to", "as", "from", "type"}}, - }}; - // NOLINTEND(modernize-use-designated-initializers) - - [[nodiscard]] Commands commandList(Json const& json, std::string const& path) { - Commands commands; - if (auto const* const array = std::get_if(&json.data)) { - for (std::size_t index = 0; index < array->size(); ++index) { - commands.push_back(command(array->at(index), pointerAppend(path, index))); - } - return commands; - } - commands.push_back(command(json, path)); - return commands; - } - - [[nodiscard]] static std::string nameOf(Json const& json, std::string const& path, char const* what, - bool dotted = false) { - auto const* const name = std::get_if(&json.data); - bool valid = name != nullptr && !name->empty(); - if (valid && dotted) { - auto const segments = splitPath(*name); - valid = segments.has_value() && isName(segments->front()); - } else if (valid) { - valid = isName(*name); - } - if (!valid) { - refuse(path, what); - } - return *name; - } - - [[nodiscard]] static std::string nonEmpty(Json const& json, std::string const& path, char const* what) { - auto const* const name = std::get_if(&json.data); - if (name == nullptr || name->empty()) { - refuse(path, what); - } - return *name; - } - - static void requireTrue(Json const& json, std::string const& path, std::string_view key) { - bool const* const value = std::get_if(&json.data); - if (value == nullptr || !*value) { - refuse(path, "`" + std::string{key} + "` is written `true`"); - } - } - - // NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per command of ui/1. - [[nodiscard]] Command command(Json const& json, std::string const& path) { - auto const& fields = objectOf(json, path, R"(a command is an object such as {"set": ..., "value": ...})"); - CommandSpec const* chosen = nullptr; - for (auto const& [key, value] : fields) { - static_cast(value); - for (CommandSpec const& spec : kCommands) { - if (spec.key == key) { - if (chosen != nullptr) { - refuse(path, - "a command has one kind; found `" + std::string{chosen->key} + "` and `" + key + "`"); - } - chosen = &spec; - } - } - } - if (chosen == nullptr) { - refuse(path, "not a command of ui/1"); - } - refuseMustUnderstand(fields, path); - Command cmd; - cmd.kind = chosen->kind; - cmd.path = path; - Json const& primary = *member(fields, chosen->key); - std::string const where = pointerAppend(path, chosen->key); - switch (chosen->kind) { - case CommandKind::Set: { - cmd.target = nameOf(primary, where, "`set` names state or an element as `name.path`", true); - Json const* const value = member(fields, "value"); - if (value == nullptr) { - refuse(path, "`set` needs a `value`"); - } - cmd.value = expr(*value, pointerAppend(path, "value")); - break; - } - case CommandKind::Run: - cmd.target = nameOf(primary, where, "`run` names a mutation"); - cmd.value = optionalExpr(fields, "body", path); - cmd.extra = optionalExpr(fields, "each", path); - if (Json const* const binding = member(fields, "as")) { - cmd.binding = nameOf(*binding, pointerAppend(path, "as"), "`as` is a name"); - } - break; - case CommandKind::Reset: - case CommandKind::Refetch: - case CommandKind::Open: - cmd.target = nameOf(primary, where, "the command names a declaration or an element"); - break; - case CommandKind::Focus: - cmd.target = nameOf(primary, where, "the command names a declaration or an element"); - cmd.extra = optionalExpr(fields, "row", path); - break; - case CommandKind::Close: - cmd.target = nameOf(primary, where, "`close` names a dialog, or `self`"); - break; - case CommandKind::Navigate: - navigate(cmd, fields, primary, path); - break; - case CommandKind::Return: - case CommandKind::SetContext: - cmd.value = expr(primary, where); - break; - case CommandKind::Host: - cmd.target = nonEmpty(primary, where, "`host` names a registered command"); - cmd.value = optionalExpr(fields, "args", path); - break; - case CommandKind::SwitchBackend: - case CommandKind::SetLocale: - cmd.target = nonEmpty(primary, where, "the command takes a non-empty string"); - break; - case CommandKind::ResetPrefs: - cmd.target = nameOf(primary, where, "`resetPrefs` names a customization point, or `all`"); - break; - case CommandKind::Notify: { - cmd.value = expr(primary, where); - static constexpr std::array kRoles = {"info", "success", "warning", "error"}; - cmd.option = choiceOf(fields, "role", path, kRoles); - break; - } - case CommandKind::Seq: - case CommandKind::All: { - if (!std::holds_alternative(primary.data)) { - refuse(where, "`" + std::string{chosen->key} + "` takes an array of commands"); - } - cmd.commands = commandList(primary, where); - break; - } - case CommandKind::If: { - auto const* const array = std::get_if(&primary.data); - if (array == nullptr || array->size() < 2 || array->size() > 3) { - refuse(where, "`if` takes [condition, [then...], [else...]]"); - } - cmd.value = expr(array->at(0), pointerAppend(where, std::size_t{0})); - cmd.commands = commandList(array->at(1), pointerAppend(where, 1)); - if (array->size() == 3) { - cmd.alternative = commandList(array->at(2), pointerAppend(where, 2)); - } - break; - } - case CommandKind::CancelClose: - case CommandKind::Retry: - case CommandKind::SignOut: - requireTrue(primary, where, chosen->key); - break; - case CommandKind::SignIn: { - auto const* const object = std::get_if(&primary.data); - Json const* const from = object == nullptr ? nullptr : member(*object, "from"); - if (from == nullptr) { - refuse(where, R"(`signIn` is {"from": mutation})"); - } - cmd.target = nameOf(*from, pointerAppend(where, "from"), "`signIn` names its mutation"); - break; - } - case CommandKind::Upload: { - cmd.value = expr(primary, where); - Json const* const destination = member(fields, "to"); - if (destination == nullptr) { - refuse(path, "`upload` names its mutation with `to`"); - } - cmd.target = nameOf(*destination, pointerAppend(path, "to"), "`to` names a mutation"); - if (Json const* const binding = member(fields, "as")) { - cmd.binding = nameOf(*binding, pointerAppend(path, "as"), "`as` is a name"); - } - if (Json const* const transfer = member(fields, "id")) { - cmd.transfer = nameOf(*transfer, pointerAppend(path, "id"), "`id` is a name"); - } - static constexpr std::array kInto = {"ref", "bytes"}; - cmd.bytes = choiceOf(fields, "into", path, kInto) == "bytes"; - for (auto const& [key, slot] : {std::pair{"nameAs", &cmd.nameAs}, std::pair{"typeAs", &cmd.typeAs}}) { - if (Json const* const name = member(fields, key)) { - if (!cmd.bytes) { - refuse(pointerAppend(path, key), - "`" + std::string{key} + - R"(` names a body member for inline bytes; give `"into": "bytes"`)"); - } - *slot = nameOf(*name, pointerAppend(path, key), "a body member is a name"); - } - } - break; - } - case CommandKind::Download: - default: - download(cmd, fields, primary, path); - break; - } - return cmd; - } - - void navigate(Command& cmd, Json::object_t const& fields, Json const& primary, std::string const& path) { - std::string const where = pointerAppend(path, "navigate"); - if (auto const* const route = std::get_if(&primary.data)) { - Json const* const value = member(*route, "route"); - if (value == nullptr || route->size() != 1) { - refuse(where, R"(`navigate` names a screen, or is {"route": e})"); - } - cmd.extra = expr(*value, pointerAppend(where, "route")); - } else { - cmd.target = nonEmpty(primary, where, R"(`navigate` names a screen, or is {"route": e})"); - } - cmd.value = optionalExpr(fields, "params", path); - static constexpr std::array kModes = {"tab", "dialog", "drawer", "window"}; - cmd.option = choiceOf(fields, "as", path, kModes); - if (Json const* const result = member(fields, "onResult")) { - cmd.commands = commandList(*result, pointerAppend(path, "onResult")); - } - if (Json const* const cancel = member(fields, "onCancel")) { - cmd.alternative = commandList(*cancel, pointerAppend(path, "onCancel")); - } - } - - static void download(Command& cmd, Json::object_t const& fields, Json const& primary, std::string const& path) { - cmd.value = expr(primary, pointerAppend(path, "download")); - static constexpr std::array kFrom = {"ref", "bytes"}; - cmd.bytes = choiceOf(fields, "from", path, kFrom) == "bytes"; - if (cmd.bytes) { - // Inline bytes carry no name or type of their own, so the document gives the name. - if (member(fields, "name") == nullptr) { - refuse(path, "a download from bytes names its file with `name`"); - } - cmd.extra = optionalExpr(fields, "name", path); - cmd.mediaType = optionalExpr(fields, "type", path); - } else if (member(fields, "type") != nullptr) { - refuse(pointerAppend(path, "type"), R"(`type` is the media type of inline bytes; give `"from": "bytes"`)"); - } - std::string const save = text(fields, "save", path, false); - std::string const destination = text(fields, "to", path, false); - if (save == "dialog" && destination.empty()) { - cmd.option = "dialog"; - cmd.extra = optionalExpr(fields, "name", path); - return; - } - if (destination == "preview" && save.empty()) { - Json const* const binding = member(fields, "as"); - if (binding == nullptr) { - refuse(path, "a download to preview binds a state with `as`"); - } - cmd.option = "preview"; - cmd.target = nameOf(*binding, pointerAppend(path, "as"), "`as` names a state"); - return; - } - refuse(path, R"(`download` takes `"save": "dialog"` or `"to": "preview"`)"); - } - - [[nodiscard]] std::map> keyBindings(Json const& json, std::string const& path) { - std::map> keys; - for (auto const& [chord, commands] : objectOf(json, path, "`keys` maps chords to commands")) { - std::string const where = pointerAppend(path, chord); - checkChord(chord, where); - keys.emplace(chord, commandList(commands, where)); - } - return keys; - } +[[nodiscard]] MORPH_API KindSpec const* findKind(std::string_view kind, bool part); - // NOLINTNEXTLINE(readability-function-cognitive-complexity): a component's rules, one after another. - [[nodiscard]] Component component(std::string const& name, Json const& json, std::string const& path) { - checkName(name, path); - auto const& fields = objectOf(json, path, "a component is an object"); - refuseMustUnderstand(fields, path); - Component decl; - decl.name = name; - decl.path = path; - decl.qml = text(fields, "qml", path, false); - decl.host = text(fields, "host", path, false); - if (decl.qml.empty() == decl.host.empty()) { - refuse(path, "a component names exactly one of `qml` and `host`"); - } - if (!decl.qml.empty()) { - bool hash = decl.qml.size() == 71 && decl.qml.starts_with("sha256:"); - for (char const chr : std::string_view{decl.qml}.substr(std::min(7, decl.qml.size()))) { - hash = hash && ((chr >= '0' && chr <= '9') || (chr >= 'a' && chr <= 'f')); - } - if (!hash) { - refuse(pointerAppend(path, "qml"), "`qml` is a content hash `sha256:<64 hex digits>`"); - } - } else { - Json const* const version = member(fields, "version"); - auto const number = version == nullptr ? std::nullopt : detail::jsonInt(*version); - if (!number) { - refuse(path, "a host component has an integer `version`"); - } - decl.version = *number; - } - static constexpr std::array kPropTypes = {"string", "bool", "int", - "exact", "number", "json"}; - if (Json const* const props = member(fields, "props")) { - std::string const where = pointerAppend(path, "props"); - for (auto const& [prop, type] : objectOf(*props, where, "`props` maps names to prop types")) { - auto const* const spelled = std::get_if(&type.data); - if (spelled == nullptr || !listed(kPropTypes, *spelled)) { - refuse(pointerAppend(where, prop), "a prop type is string, bool, int, exact, number or json"); - } - decl.props.emplace(prop, *spelled); - } - } - if (Json const* const events = member(fields, "events")) { - std::string const where = pointerAppend(path, "events"); - for (auto const& [event, type] : objectOf(*events, where, "`events` maps names to payload types")) { - decl.events.emplace(event, typeOf(type, pointerAppend(where, event))); - } - } - Json const* const fallback = member(fields, "fallback"); - if (fallback == nullptr) { - refuse(path, "a component names a `fallback` of built-in nodes"); - } - decl.fallback = node(*fallback, pointerAppend(path, "fallback")); - return decl; - } +} // namespace detail - [[nodiscard]] static CustomizePoint point(std::string const& name, Json const& json, std::string const& path, - bool appDocument) { - checkName(name, path); - auto const& fields = objectOf(json, path, "a customization point is an object"); - refuseMustUnderstand(fields, path); - static constexpr std::array kPointKinds = {"columns", "choice", "value", "layout", - "saved", "pins", "arrange"}; - CustomizePoint decl; - decl.name = name; - decl.path = path; - decl.kind = text(fields, "kind", path, true); - if (!listed(kPointKinds, decl.kind)) { - refuse(pointerAppend(path, "kind"), "`" + decl.kind + "` is not a kind of customization point"); - } - if (decl.kind == "pins" && !appDocument) { - refuse(pointerAppend(path, "kind"), "a `pins` point belongs to the app document"); - } - // The container an `arrange` point orders is a screen's, and the app document has no view. - if (decl.kind == "arrange" && appDocument) { - refuse(pointerAppend(path, "kind"), "an `arrange` point belongs to the screen whose container it orders"); - } - decl.of = text(fields, "of", path, decl.kind == "columns" || decl.kind == "arrange"); - Json const* const fallback = member(fields, "default"); - if (decl.kind == "choice") { - Json const* const options = member(fields, "options"); - if (options == nullptr) { - refuse(path, "a `choice` point lists its `options`"); - } - decl.options = nameList(*options, pointerAppend(path, "options")); - if (fallback != nullptr) { - auto const* const chosen = std::get_if(&fallback->data); - if (chosen == nullptr || std::ranges::find(decl.options, *chosen) == decl.options.end()) { - refuse(pointerAppend(path, "default"), "the default of a `choice` is one of its options"); - } - decl.defaultValue = *chosen; - } - decl.type = Type::of(TypeKind::String); - } else if (decl.kind == "value") { - Json const* const type = member(fields, "type"); - if (type == nullptr) { - refuse(path, "a `value` point declares its `type`"); - } - decl.type = typeOf(*type, pointerAppend(path, "type")); - if (fallback != nullptr) { - auto value = valueFromJson(*fallback, decl.type); - if (!value) { - refuse(pointerAppend(path, "default"), - "the default does not have the point's type: " + value.error()); - } - decl.defaultValue = std::move(*value); - } - } - return decl; - } +/// @brief Parses a UI document and runs its load-time validation (spec 5 §3). +/// +/// A document is refused when it does not parse, when a reference does not resolve, when a type does not check, +/// when the `let` or `watch` graph has a cycle, when an expression exceeds 256 nodes, when a node kind, command or +/// function is not in the vocabulary, when a document declares `invalidates`, `patch` or `refreshOn`, when a +/// must-understand key is unknown, or when a rule of spec 5 or spec 6 fails; the list is in +/// `docs/spec/ui/document.md`. The rules that need catalog facts run when @p options supplies them. +/// @param json The document's JSON. +/// @param options The catalog facts. +/// @return The document, with what validation found that does not refuse it in `Document::warnings`, or the first +/// refusal, naming the document id, the JSON Pointer and the reason. +[[nodiscard]] MORPH_API std::expected loadDocument(Json const& json, + LoadOptions const& options = {}); - [[nodiscard]] DocNodePtr node(Json const& json, std::string const& path) { - auto const* const object = std::get_if(&json.data); - if (object == nullptr) { - refuse(path, "a node is an object with a `kind`"); - } - std::string const kind = text(*object, "kind", path, true); - KindSpec const* const spec = findKind(kind, false); - if (spec == nullptr) { - refuse(pointerAppend(path, "kind"), "the node kind `" + kind + "` is not in ui/1"); - } - auto made = std::make_shared(); - made->kind = kind; - made->path = path; - refuseMustUnderstand(*object, path); - fill(*made, *object, *spec, path); - return made; - } - - void fill(DocNode& made, Json::object_t const& object, KindSpec const& spec, std::string const& path) { - bool const isPart = (spec.flags & kPart) != 0; - auto apply = [&](KeySpec const& key) { - Json const* const value = member(object, key.key); - if (value == nullptr) { - if ((key.flags & kRequired) != 0) { - refuse(path, "`" + std::string{key.key} + "` is required on `" + std::string{spec.kind} + "`"); - } - return; - } - entry(made, key, *value, pointerAppend(path, key.key)); - }; - if (!isPart) { - for (KeySpec const& key : kCommonKeys) { - apply(key); - } - if ((spec.flags & kField) != 0) { - for (KeySpec const& key : kFieldKeys) { - apply(key); - } - } - } - for (KeySpec const& key : spec.keys) { - apply(key); - } - if ((spec.flags & kScope) != 0) { - if (Json const* const declarations = member(object, "scope")) { - std::string const where = pointerAppend(path, "scope"); - auto const& fields = objectOf(*declarations, where, "`scope` holds a scope's declarations"); - refuseMustUnderstand(fields, where); - made.scope = scope(fields, where); - } else { - made.scope = ScopeDecl{}; - } - } - if (made.kind == "fields") { - for (auto const& [field, overlay] : object) { - made.parts["fields"].push_back(fieldOverlay(field, overlay, pointerAppend(path, field))); - } - } - } - - // One field overlay of a form's `fields`: expressions by key, and the host `component` that draws the field with - // its `props`. - [[nodiscard]] static DocNodePtr fieldOverlay(std::string const& field, Json const& overlay, - std::string const& where) { - auto const& settings = objectOf(overlay, where, "a field overlay is an object"); - auto part = std::make_shared(); - part->kind = "field"; - part->id = field; - part->path = where; - for (auto const& [key, value] : settings) { - std::string const keyPath = pointerAppend(where, key); - if (key == "component") { - // The host component that draws the field, and the props it is given beside the field's. - auto const* const name = std::get_if(&value.data); - if (name == nullptr || !isName(*name)) { - refuse(keyPath, "`component` is a name"); - } - part->names.emplace(key, *name); - } else if (key == "props") { - auto record = std::make_shared(); - record->kind = "props"; - record->path = keyPath; - for (auto const& [prop, propValue] : objectOf(value, keyPath, "`props` is a record of expressions")) { - record->props.emplace(prop, expr(propValue, pointerAppend(keyPath, prop))); - } - part->parts["props"].push_back(std::move(record)); - } else { - part->props.emplace(key, expr(value, keyPath)); - } - } - return part; - } - - [[nodiscard]] DocNodePtr part(Json const& json, std::string_view kind, std::string const& path) { - KindSpec const* const spec = findKind(kind, true); - auto const& object = objectOf(json, path, "a part of a node is an object"); - refuseMustUnderstand(object, path); - auto made = std::make_shared(); - made->kind = std::string{kind}; - made->path = path; - fill(*made, object, *spec, path); - if (kind == "actionButton" && made->prop("iconOnly") != nullptr && made->prop("icon") == nullptr) { - refuse(pointerAppend(path, "iconOnly"), "an icon-only action names its `icon`"); - } - return made; - } - - // NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per shape a key takes. - void entry(DocNode& made, KeySpec const& key, Json const& value, std::string const& path) { - std::string const name{key.key}; - switch (key.shape) { - case Shape::Expr: - case Shape::Condition: - made.props.emplace(name, expr(value, path)); - break; - case Shape::Commands: - made.events.emplace(name, commandList(value, path)); - break; - case Shape::Nodes: { - std::vector nodes; - if (auto const* const array = std::get_if(&value.data)) { - for (std::size_t index = 0; index < array->size(); ++index) { - nodes.push_back(node(array->at(index), pointerAppend(path, index))); - } - } else { - nodes.push_back(node(value, path)); - } - made.children.emplace(name, std::move(nodes)); - break; - } - case Shape::Text: - case Shape::Name: { - auto const* const string = std::get_if(&value.data); - if (string == nullptr || (key.shape == Shape::Name && !isName(*string))) { - refuse(path, "`" + name + "` is " + (key.shape == Shape::Name ? "a name" : "a string")); - } - if (name == "id") { - made.id = *string; - } else { - made.names.emplace(name, *string); - } - break; - } - case Shape::Part: - made.parts[name].push_back(part(value, key.part, path)); - break; - case Shape::Parts: - case Shape::PartsOrExpr: { - auto const* const array = std::get_if(&value.data); - if (array == nullptr && key.shape == Shape::PartsOrExpr) { - made.props.emplace(name, expr(value, path)); - break; - } - if (array == nullptr) { - refuse(path, "`" + name + "` is an array"); - } - auto& list = made.parts[name]; - for (std::size_t index = 0; index < array->size(); ++index) { - list.push_back(part(array->at(index), key.part, pointerAppend(path, index))); - } - break; - } - case Shape::ExprRecord: { - if (!key.part.empty()) { - made.parts[name].push_back(part(value, key.part, path)); - break; - } - auto record = std::make_shared(); - record->kind = name; - record->path = path; - for (auto const& [field, fieldValue] : objectOf(value, path, "a record of expressions")) { - record->props.emplace(field, expr(fieldValue, pointerAppend(path, field))); - } - made.parts[name].push_back(std::move(record)); - break; - } - case Shape::CommandRecord: - for (auto const& [event, commands] : objectOf(value, path, "a record of command lists")) { - made.events.emplace(std::format("{}.{}", name, event), - commandList(commands, pointerAppend(path, event))); - } - break; - case Shape::Flag: { - auto const* const flag = std::get_if(&value.data); - if (flag == nullptr) { - refuse(path, "`" + name + "` is a literal `true` or `false`"); - } - made.flags.emplace(name, *flag); - break; - } - case Shape::Keys: - default: - made.keys = keyBindings(value, path); - break; - } - } - // NOLINTEND(misc-no-recursion) -}; - -/// @brief What a name in a scope declares. -enum class NameCategory : std::uint8_t { - Param, ///< A screen param. - Model, ///< A model alias. - State, ///< State. - Let, ///< A derived value. - Query, ///< A query. - Mutation, ///< A mutation. - Element, ///< An element id. - Transfer, ///< A transfer id of `upload`. -}; - -struct ScopeInfo; - -/// @brief One declared name of a scope. -struct NameEntry { - /// @brief What it declares. - NameCategory category = NameCategory::Param; - /// @brief The declaration's JSON Pointer. - std::string path; - /// @brief The scope that declares it. - ScopeInfo* scope = nullptr; - /// @brief The type of a param, of typed state, and of state or a `let` once derived. - Type type; - /// @brief The model of a `Model` entry. - ModelDecl const* model = nullptr; - /// @brief The expression a state or `let` type is derived from; `nullptr` when the type is declared. - ExprPtr derivedFrom; - /// @brief The query of a `Query` entry. - QueryDecl const* query = nullptr; - /// @brief The mutation of a `Mutation` entry. - MutationDecl const* mutation = nullptr; - /// @brief The element of an `Element` entry. - DocNode const* element = nullptr; - /// @brief 0 before its type is derived, 1 while it is, 2 after. - int visit = 0; -}; - -/// @brief One scope during validation: its names and its parent. -struct ScopeInfo { - /// @brief The enclosing scope; `nullptr` for a screen or a component fallback. - ScopeInfo* parent = nullptr; - /// @brief The scopes it encloses directly, in document order. - std::vector children; - /// @brief Whether it is a `forEach` or `table` row scope. - bool row = false; - /// @brief The `switch` whose case it is; `nullptr` for any other scope. - DocNode const* switchNode = nullptr; - /// @brief Whether it is the screen's own scope. - bool screen = false; - /// @brief The names it declares. - std::map> names; -}; - -/// @brief Where an expression or command is checked: its scope and what is valid there. -struct CheckContext { - /// @brief The scope. - ScopeInfo* scope = nullptr; - /// @brief Inside a command list, where `event` is valid. - bool commands = false; - /// @brief Inside a boundary's `error`, where `boundary.error` and `retry` are valid. - bool boundaryError = false; - /// @brief Inside `onClose`, where `cancelClose` is valid. - bool onClose = false; - /// @brief Names bound here: `as` of a sequence step or `each`, `result`, `body`, `props`. - std::vector> bindings; -}; - -class DocumentValidator; - -/// @brief Resolves an expression's names against a scope chain and a context. -class ScopeResolver final : public NameResolver { -public: - /// @brief Resolves for @p validator in @p context. - /// @param validator The validator, which derives state and `let` types on demand. - /// @param context Where the expression is. - ScopeResolver(DocumentValidator& validator, CheckContext const& context) - : _validator{validator}, _context{context} {} - - /// @brief Resolves a reference. - /// @param head The first segment. - /// @param path The rest. - /// @return The type, or why it does not resolve. - [[nodiscard]] std::expected ref(std::string_view head, - std::span path) const override; - - /// @brief Resolves a row field. - /// @param path The field path. - /// @return `any` inside a row, or why there is no row. - [[nodiscard]] std::expected row(std::span path) const override; - - /// @brief Resolves a query or mutation name. - /// @param form The form. - /// @param name The name. - /// @return The type, or why it does not resolve. - [[nodiscard]] std::expected control(ExprKind form, std::string_view name) const override; - - /// @brief Resolves a customization point. - /// @param point The point. - /// @param path The rest. - /// @return The type, or why it does not resolve. - [[nodiscard]] std::expected pref(std::string_view point, - std::span path) const override; - -private: - DocumentValidator& _validator; - CheckContext const& _context; -}; - -/// @brief The type of an element value. -/// @param value The value's name. -/// @return Its type. -[[nodiscard]] inline Type elementValueType(std::string_view value) { - static constexpr std::array kBools = {"visible", "enabled", "valid", "dirty", "focused", - "touched", "checked", "open", "ready", "submitted"}; - static constexpr std::array kCounts = {"viewCount", "sourceCount", "selectedCount"}; - if (listed(kBools, value) || value == "pending") { - return Type::of(TypeKind::Bool); - } - if (value == "errors" || value == "shownErrors") { - return Type::listOf(Type::of(TypeKind::String)); - } - if (listed(kCounts, value)) { - return Type::of(TypeKind::Int); - } - if (value == "error") { - return Type::of(TypeKind::String, true); - } - return Type::any(); -} - -/// @brief Whether a value of type @p actual may stand where @p declared is expected. -/// @param declared The expected type. -/// @param actual The type found. -/// @return Whether they are compatible: equal kinds, `any` on either side, an `int` for a `decimal` or `key`, a -/// `string` for a `key`. -[[nodiscard]] inline bool compatible(Type const& declared, Type const& actual) { - if (declared.isAny() || actual.isAny() || declared.kind == actual.kind) { - return true; - } - bool const integer = actual.kind == TypeKind::Int; - return (declared.kind == TypeKind::Decimal && integer) || - (declared.kind == TypeKind::Key && (integer || actual.kind == TypeKind::String)); -} - -// NOLINTBEGIN(misc-no-recursion): a document is a tree of scopes, nodes and command lists, and checking descends it. -/// @brief Checks a parsed document against its own names and the catalog: every load-time rule that needs more -/// than one place in the document. -class DocumentValidator { -public: - /// @brief Validates @p doc. - /// @param doc The parsed document. - /// @param options The catalog facts. - DocumentValidator(Document const& doc, LoadOptions const& options) : _doc{&doc}, _options{&options} {} - - /// @brief Runs every rule; throws `DocumentRefused` on the first refusal. - void run() { - ScopeInfo& screen = newScope(nullptr, false); - screen.screen = true; - for (auto const& [name, type] : _doc->params) { - NameEntry entry; - entry.category = NameCategory::Param; - entry.path = pointerAppend("/params", name); - entry.type = type; - add(screen, name, std::move(entry)); - } - declare(_doc->scope, screen); - for (auto const& [key, commands] : _doc->lifecycle) { - static_cast(key); - collectTransfers(commands, screen); - } - for (auto const& [chord, commands] : _doc->keys) { - static_cast(chord); - collectTransfers(commands, screen); - } - if (_doc->view) { - collect(*_doc->view, screen); - } - for (DocNodePtr const& part : headParts()) { - collectPart(*part, screen, screen, *part); - } - std::vector componentScopes; - for (auto const& [name, component] : _doc->components) { - static_cast(name); - ScopeInfo& fallbackScope = newScope(nullptr, false); - collect(*component.fallback, fallbackScope); - componentScopes.push_back(&fallbackScope); - } - - CheckContext const root{ - .scope = &screen, .commands = false, .boundaryError = false, .onClose = false, .bindings = {}}; - checkScope(_doc->scope, root); - if (_doc->title) { - checkExpr(*_doc->title, root); - } - if (_doc->identity) { - checkExpr(*_doc->identity, root); - } - if (_doc->dirty) { - checkCondition(*_doc->dirty, root, "`dirty`"); - } - if (_doc->titleSpans) { - checkExpr(*_doc->titleSpans, root); - checkSpans(_doc->titleSpans); - } - if (_doc->eyebrow) { - checkExpr(*_doc->eyebrow, root); - } - if (_doc->eyebrowSpans) { - checkExpr(*_doc->eyebrowSpans, root); - checkSpans(_doc->eyebrowSpans); - } - if (_doc->subtitle) { - checkExpr(*_doc->subtitle, root); - } - if (_doc->subtitleSpans) { - checkExpr(*_doc->subtitleSpans, root); - checkSpans(_doc->subtitleSpans); - } - if (_doc->leadPlacement) { - checkExpr(*_doc->leadPlacement, root); - } - if (_doc->titleRole) { - checkExpr(*_doc->titleRole, root); - } - if (_doc->headSurface) { - checkExpr(*_doc->headSurface, root); - } - if (_doc->pageSurface) { - checkExpr(*_doc->pageSurface, root); - } - if (_doc->menuLabel) { - checkExpr(*_doc->menuLabel, root); - } - for (DocNodePtr const& part : headParts()) { - checkElement(*part, root, true); - } - checkActionButtons(_doc->actions, "/actions"); - std::set menuIds; - checkHeadMenu(_doc->menu, menuIds); - checkHeadTools(_doc->tools); - for (auto const& [key, commands] : _doc->lifecycle) { - CheckContext context = root; - context.onClose = key == "onClose"; - checkCommands(commands, context); - } - for (auto const& [chord, commands] : _doc->keys) { - static_cast(chord); - checkCommands(commands, root); - } - checkPrefetch(); - if (_doc->view) { - checkNode(*_doc->view, root); - } - std::size_t index = 0; - for (auto const& [name, component] : _doc->components) { - static_cast(name); - CheckContext context{.scope = componentScopes.at(index++), - .commands = false, - .boundaryError = false, - .onClose = false, - .bindings = {}}; - context.bindings.emplace_back("props", Type::of(TypeKind::Record)); - checkNode(*component.fallback, context); - } - checkCustomizePoints(); - checkWatchGraph(); - checkEffects(); - } - - /// @brief What validation found that does not refuse the document. - /// @return The warnings, in the order found; the validator keeps none. - [[nodiscard]] std::vector takeWarnings() noexcept { return std::move(_warnings); } - - /// @brief The static type of each date input's `value` that the checker could decide. - /// @return The table, keyed by node; the validator keeps none. - [[nodiscard]] std::map takeDateValueKinds() noexcept { - return std::move(_dateValueKinds); - } - - /// @brief Where each `focus` command's target resolved, keyed by the command's JSON Pointer. - /// @return The table; the validator keeps none. - [[nodiscard]] std::map> takeFocusTargets() noexcept { - return std::move(_focusTargets); - } - - /// @brief Finds a name in a scope chain. - /// @param scope The innermost scope. - /// @param name The name. - /// @return The entry, or `nullptr`. - [[nodiscard]] static NameEntry* lookup(ScopeInfo* scope, std::string_view name) { - for (ScopeInfo* current = scope; current != nullptr; current = current->parent) { - auto const found = current->names.find(name); - if (found != current->names.end()) { - return &found->second; - } - } - return nullptr; - } - - /// @brief The type of a name whose type is derived from an expression, derived on first use. - /// @param entry The state or `let` entry. - /// @param name Its name, for the cycle's description. - /// @return The type, or the cycle it closes. - [[nodiscard]] std::expected derivedType(NameEntry& entry, std::string_view name) { - if (entry.visit == 2 || !entry.derivedFrom) { - return entry.type; - } - if (entry.visit == 1) { - std::string cycle; - auto const start = std::ranges::find(_deriving, name); - for (auto step = start; step != _deriving.end(); ++step) { - cycle += *step + " → "; - } - std::string const graph = - entry.category == NameCategory::Let ? "the let graph has a cycle: " : "the state inits form a cycle: "; - return std::unexpected(graph + cycle + std::string{name}); - } - entry.visit = 1; - _deriving.emplace_back(name); - CheckContext const context{ - .scope = entry.scope, .commands = false, .boundaryError = false, .onClose = false, .bindings = {}}; - Type type = checkExpr(*entry.derivedFrom, context); - _deriving.pop_back(); - entry.visit = 2; - entry.type = type; - return type; - } - - /// @brief The document. - /// @return It. - [[nodiscard]] Document const& document() const noexcept { return *_doc; } - -private: - ScopeInfo& newScope(ScopeInfo* parent, bool row) { - ScopeInfo& made = _scopes.emplace_back(); - made.parent = parent; - made.row = row; - if (parent != nullptr) { - parent->children.push_back(&made); - } - return made; - } - - static void add(ScopeInfo& scope, std::string const& name, NameEntry entry) { - static constexpr std::array kReserved = {"event", "app", "boundary", - "props", "result", "body"}; - if (listed(kReserved, name)) { - refuse(entry.path, "`" + name + "` is reserved and cannot be declared"); - } - auto const found = scope.names.find(name); - if (found != scope.names.end()) { - refuse(entry.path, "`" + name + "` is declared twice in this scope (first at " + found->second.path + ")"); - } - entry.scope = &scope; - scope.names.emplace(name, std::move(entry)); - } - - /// Checks a model alias against the catalog's facts, when there is a catalog. - void checkCatalog(ModelDecl const& model) { - if (!_options->catalog.model) { - return; - } - auto const info = _options->catalog.model(model.type); - if (!info) { - refuse(pointerAppend(model.path, "type"), "the model type `" + model.type + "` is not in the catalog"); - } - if (model.instance == InstanceMode::Shared && !info->stateless) { - refuse(pointerAppend(model.path, "instance"), - "the model type `" + model.type + - "` keeps state, so `shared` names no instance: it needs a key, or `private`"); - } - if (model.instance == InstanceMode::Keyed && !info->keyed) { - refuse(pointerAppend(model.path, "instance"), - "the model type `" + model.type + "` is not keyed, so its instance is not an expression"); - } - } - - void declare(ScopeDecl const& decl, ScopeInfo& scope) { - for (ModelDecl const& model : decl.models) { - if (scope.row && model.instance == InstanceMode::Default) { - refuse(model.path, "a model alias in a row scope names its `instance`"); - } - if (!scope.screen && model.instance == InstanceMode::Borrowed) { - refuse(model.path, "only a screen's own aliases borrow the opener's instance"); - } - checkCatalog(model); - NameEntry entry; - entry.category = NameCategory::Model; - entry.path = model.path; - entry.model = &model; - add(scope, model.name, std::move(entry)); - } - for (StateDecl const& state : decl.state) { - NameEntry entry; - entry.category = NameCategory::State; - entry.path = state.path; - entry.type = state.type; - entry.derivedFrom = state.typeDeclared ? nullptr : state.init; - add(scope, state.name, std::move(entry)); - } - for (LetDecl const& let : decl.lets) { - NameEntry entry; - entry.category = NameCategory::Let; - entry.path = let.path; - entry.derivedFrom = let.value; - add(scope, let.name, std::move(entry)); - } - for (QueryDecl const& query : decl.queries) { - NameEntry entry; - entry.category = NameCategory::Query; - entry.path = query.path; - entry.query = &query; - add(scope, query.name, std::move(entry)); - _queries.emplace(query.name, &query); - _queryScopes.emplace_back(&query, &scope); - } - for (MutationDecl const& mutation : decl.mutations) { - NameEntry entry; - entry.category = NameCategory::Mutation; - entry.path = mutation.path; - entry.mutation = &mutation; - add(scope, mutation.name, std::move(entry)); - _mutations.emplace_back(&mutation, &scope); - collectTransfers(mutation.onSuccess, scope); - collectTransfers(mutation.onError, scope); - } - for (WatchDecl const& watch : decl.watches) { - _watches.emplace_back(&watch, &scope); - collectTransfers(watch.body, scope); - } - } - - void collectTransfers(Commands const& commands, ScopeInfo& scope) { - for (Command const& cmd : commands) { - if (cmd.kind == CommandKind::Upload && !cmd.transfer.empty()) { - NameEntry entry; - entry.category = NameCategory::Transfer; - entry.path = pointerAppend(cmd.path, "id"); - add(scope, cmd.transfer, std::move(entry)); - } - collectTransfers(cmd.commands, scope); - collectTransfers(cmd.alternative, scope); - } - } - - void collect(DocNode const& node, ScopeInfo& scope) { collectIn(node, scope); } - - void collectIn(DocNode const& node, ScopeInfo& scope) { - KindSpec const* const spec = findKind(node.kind, false); - if (!node.id.empty()) { - NameEntry entry; - entry.category = NameCategory::Element; - entry.path = pointerAppend(node.path, "id"); - entry.element = &node; - add(scope, node.id, std::move(entry)); - _elements.emplace(node.id, &node); - } - ScopeInfo* inner = &scope; - if (spec != nullptr && (spec->flags & kScope) != 0) { - inner = &newScope(&scope, (spec->flags & kRowScope) != 0); - _scopeOf.emplace(&node, inner); - // NOLINTNEXTLINE(bugprone-unchecked-optional-access): the parser gives every scope-creating node a scope. - declare(*node.scope, *inner); - } - _innerOf.emplace(&node, inner); - for (auto const& [key, commands] : node.events) { - collectTransfers(commands, isInner(spec, key) ? *inner : scope); - } - for (auto const& [chord, commands] : node.keys) { - static_cast(chord); - collectTransfers(commands, scope); - } - for (auto const& [key, nodes] : node.children) { - for (DocNodePtr const& child : nodes) { - collectIn(*child, isInner(spec, key) ? *inner : scope); - } - } - for (auto const& [key, parts] : node.parts) { - for (DocNodePtr const& child : parts) { - collectPart(*child, isInner(spec, key) ? *inner : scope, *inner, node); - } - } - } - - void collectPart(DocNode const& part, ScopeInfo& outer, ScopeInfo& ownerInner, DocNode const& owner) { - KindSpec const* const spec = findKind(part.kind, true); - ScopeInfo* inner = &ownerInner; - if (spec != nullptr && (spec->flags & kScope) != 0) { - inner = &newScope(&outer, false); - inner->switchNode = owner.kind == "switch" ? &owner : nullptr; - _scopeOf.emplace(&part, inner); - // NOLINTNEXTLINE(bugprone-unchecked-optional-access): the parser gives every switch case a scope. - declare(*part.scope, *inner); - } else if (spec != nullptr && (spec->flags & kRowScope) != 0) { - inner = &newScope(&outer, true); - } - _innerOf.emplace(&part, inner); - for (auto const& [key, commands] : part.events) { - collectTransfers(commands, outer); - } - for (auto const& [key, nodes] : part.children) { - for (DocNodePtr const& child : nodes) { - collectIn(*child, isInner(spec, key) ? *inner : outer); - } - } - for (auto const& [key, parts] : part.parts) { - static_cast(key); - for (DocNodePtr const& child : parts) { - collectPart(*child, outer, ownerInner, part); - } - } - } - - [[nodiscard]] static bool isInner(KindSpec const* spec, std::string_view key) { - if (spec == nullptr) { - return false; - } - auto const found = std::ranges::find(spec->keys, key, &KeySpec::key); - return found != spec->keys.end() && (found->flags & kInner) != 0; - } - - /// The flags of a child-node key. The parser fills `children` only from a kind's own keys, so the kind and the key - /// are always found. - [[nodiscard]] static std::uint8_t keyFlags(KindSpec const& spec, std::string_view key) { - return std::ranges::find(spec.keys, key, &KeySpec::key)->flags; - } - - [[nodiscard]] static bool isCondition(KindSpec const* spec, std::string_view key) { - auto shapeOf = [key](std::span keys) { - auto const found = std::ranges::find(keys, key, &KeySpec::key); - return found == keys.end() ? Shape::Expr : found->shape; - }; - return (spec != nullptr && shapeOf(spec->keys) == Shape::Condition) || - shapeOf(kCommonKeys) == Shape::Condition || shapeOf(kFieldKeys) == Shape::Condition; - } - - Type checkExpr(Expr const& expr, CheckContext const& context) { - ScopeResolver const resolver{*this, context}; - auto checked = checkExpression(expr, resolver); - if (!checked) { - throw DocumentRefused{std::move(checked.error())}; - } - return std::move(*checked); - } - - void checkCondition(Expr const& expr, CheckContext const& context, std::string_view what) { - Type const type = checkExpr(expr, context); - if (!compatible(Type::of(TypeKind::Bool), type)) { - refuse(expr.path, std::string{what} + " is " + type.name() + "; expected bool"); - } - } - - // A date input shows a timestamp or an ISO-8601 date or date-time string; any other type it can never show. - void checkDateValue(DocNode const& node, Expr const& expr, Type const& type) { - if (type.kind == TypeKind::String || type.kind == TypeKind::Timestamp) { - _dateValueKinds.insert_or_assign(&node, type.kind); - } else if (type.kind != TypeKind::Any && type.kind != TypeKind::Key) { - refuse(expr.path, - "`dateTimeInput` shows a timestamp or an ISO-8601 date or date-time string; `value` is " + - type.name()); - } - } - - [[nodiscard]] static NameEntry& require(CheckContext const& context, std::string const& name, - std::string const& path, std::initializer_list categories, - std::string_view what) { - NameEntry* const entry = lookup(context.scope, name); - if (entry == nullptr || std::ranges::find(categories, entry->category) == categories.end()) { - refuse(path, "`" + name + "` is not " + std::string{what} + " of this scope"); - } - return *entry; - } - - // How many row scopes enclose @p scope, itself included, up to its screen or component fallback. - [[nodiscard]] static std::size_t rowDepth(ScopeInfo const* scope) { - std::size_t rows = 0; - for (; scope != nullptr; scope = scope->parent) { - rows += scope->row ? 1U : 0U; - } - return rows; - } - - // The element @p name declares in @p scope itself, or nothing. - [[nodiscard]] static NameEntry const* elementIn(ScopeInfo const& scope, std::string_view name) { - auto const found = scope.names.find(name); - return found != scope.names.end() && found->second.category == NameCategory::Element ? &found->second - : nullptr; - } - - // The elements named @p name in the switch cases below @p scope, at any depth through cases only. - // NOLINTNEXTLINE(misc-no-recursion): the scope tree, walked down through switch cases. - static void elementsInCases(ScopeInfo const& scope, std::string_view name, std::vector& out) { - for (ScopeInfo const* const child : scope.children) { - if (child->switchNode == nullptr) { - continue; - } - if (NameEntry const* const entry = elementIn(*child, name)) { - out.push_back(entry); - } - elementsInCases(*child, name, out); - } - } - - // The row scopes directly below @p scope, or below it through switch cases, that declare the element @p name. - // NOLINTNEXTLINE(misc-no-recursion): the scope tree, walked down through switch cases. - static void rowScopesBelow(ScopeInfo const& scope, std::string_view name, std::vector& out) { - for (ScopeInfo const* const child : scope.children) { - if (child->row) { - if (elementIn(*child, name) != nullptr && std::ranges::find(out, child) == out.end()) { - out.push_back(child); - } - } else if (child->switchNode != nullptr) { - rowScopesBelow(*child, name, out); - } - } - } - - // A `focus` target resolves to declarations. Without `row`: the element the scope chain names, else those in the - // switch cases below the chain, which must all be cases of one switch (at most one case is mounted). With `row`: - // the one row scope that declares it among the chain's and those below the chain through switch cases. - void checkFocus(Command const& cmd, CheckContext const& context) { - FocusTarget target{.candidates = {}, .row = cmd.extra != nullptr}; - if (cmd.extra) { - checkExpr(*cmd.extra, context); - std::vector found; - for (ScopeInfo const* scope = context.scope; scope != nullptr; scope = scope->parent) { - if (scope->row && elementIn(*scope, cmd.target) != nullptr && - std::ranges::find(found, scope) == found.end()) { - found.push_back(scope); - } - rowScopesBelow(*scope, cmd.target, found); - } - if (found.empty()) { - refuse(pointerAppend(cmd.path, "row"), "`row` names a row of a `forEach` or table; `" + cmd.target + - "` is not an element of a row scope this command reaches"); - } - if (found.size() > 1) { - refuse(cmd.path, "`" + cmd.target + "` is declared in two row scopes this command reaches, at " + - elementIn(*found.at(0), cmd.target)->path + " and " + - elementIn(*found.at(1), cmd.target)->path); - } - target.candidates.push_back(FocusCandidate{.path = elementIn(*found.front(), cmd.target)->element->path, - .rows = rowDepth(found.front())}); - } else if (lookup(context.scope, cmd.target) != nullptr) { - NameEntry const& entry = require(context, cmd.target, cmd.path, {NameCategory::Element}, "an element"); - target.candidates.push_back(FocusCandidate{.path = entry.element->path, .rows = rowDepth(entry.scope)}); - } else { - std::vector inCases; - for (ScopeInfo const* scope = context.scope; scope != nullptr; scope = scope->parent) { - elementsInCases(*scope, cmd.target, inCases); - } - if (inCases.empty()) { - static_cast(require(context, cmd.target, cmd.path, {NameCategory::Element}, "an element")); - } - for (NameEntry const* const entry : inCases) { - if (entry->scope->switchNode != inCases.front()->scope->switchNode) { - refuse(cmd.path, "`" + cmd.target + "` is declared in the cases of two switches, at " + - inCases.front()->path + " and " + entry->path + - "; both may be mounted, so a focus cannot choose"); - } - target.candidates.push_back( - FocusCandidate{.path = entry->element->path, .rows = rowDepth(entry->scope)}); - } - } - _focusTargets.insert_or_assign(cmd.path, std::move(target)); - } - - // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the alias, then the action it runs, as a query reads. - std::optional checkModelAction(CheckContext const& context, std::string const& alias, - std::string const& action, std::string const& path) { - std::string const modelPath = pointerAppend(path, "model"); - NameEntry const& model = require(context, alias, modelPath, {NameCategory::Model}, "a model alias"); - if (!_options->catalog.action) { - return std::nullopt; - } - auto const info = _options->catalog.action(action); - if (!info) { - refuse(path, "the action `" + action + "` is not in the catalog"); - } - if (info->modelType != model.model->type) { - refuse(path, "the action `" + action + "` belongs to `" + info->modelType + "`, not `" + - model.model->type + "`"); - } - return info; - } - - void checkScope(ScopeDecl const& decl, CheckContext const& context) { - for (ModelDecl const& model : decl.models) { - if (model.key) { - checkExpr(*model.key, context); - } - } - for (StateDecl const& state : decl.state) { - if (!state.init) { - continue; - } - Type const type = checkExpr(*state.init, context); - bool const literalFits = state.init->kind != ExprKind::Literal || state.type.admits(state.init->literal); - if (!literalFits || !compatible(state.type, type)) { - refuse(state.init->path, - "the init of `" + state.name + "` does not have its type " + state.type.name()); - } - // The type is derived now, so a state no expression reads is still checked. - auto const derived = derivedType(*lookup(context.scope, state.name), state.name); - static_cast(derived); - } - for (LetDecl const& let : decl.lets) { - auto type = derivedType(*lookup(context.scope, let.name), let.name); - static_cast(type); - } - for (QueryDecl const& query : decl.queries) { - checkQuery(query, context); - } - for (MutationDecl const& mutation : decl.mutations) { - checkMutation(mutation, context); - } - for (WatchDecl const& watch : decl.watches) { - checkExpr(*watch.on, context); - checkCommands(watch.body, context); - } - for (CheckDecl const& check : decl.checks) { - checkCondition(*check.assertion, context, "the `assert` of a check"); - if (check.message) { - checkExpr(*check.message, context); - } - for (std::size_t index = 0; index < check.targets.size(); ++index) { - static_cast(require(context, check.targets.at(index), - pointerAppend(pointerAppend(check.path, "targets"), index), - {NameCategory::Element}, "an element")); - } - } - } - - void checkQuery(QueryDecl const& query, CheckContext const& context) { - auto const action = checkModelAction(context, query.model, query.action, query.path); - // An evaluation runs no handler, so only a call can change anything. - if (action && action->effects && !query.evaluate) { - refuse(query.path, std::format("a query reads, so its action declares no effects; `{}` declares {}, " - "so it runs as a mutation", - query.action, describeEffects(*action->effects))); - } - if (query.body) { - checkExpr(*query.body, context); - } - if (query.when) { - checkCondition(*query.when, context, "`when`"); - } - } - - void checkMutation(MutationDecl const& mutation, CheckContext const& context) { - auto const action = checkModelAction(context, mutation.model, mutation.action, mutation.path); - if (mutation.body) { - checkExpr(*mutation.body, context); - } - if (mutation.serialKey) { - CheckContext keyContext = context; - keyContext.bindings.emplace_back("body", Type::any()); - checkExpr(*mutation.serialKey, keyContext); - } - if (mutation.optimistic) { - OptimisticDecl const& decl = *mutation.optimistic; - std::string const path = pointerAppend(mutation.path, "optimistic"); - auto const target = _queries.find(decl.query); - if (target == _queries.end()) { - refuse(pointerAppend(path, "query"), "`" + decl.query + "` is not a query of this document"); - } - CheckContext bodyContext = context; - bodyContext.bindings.emplace_back("body", Type::any()); - checkExpr(*decl.key, bodyContext); - checkExpr(*decl.with, bodyContext); - checkPatchAt(decl.query, decl.at, *target->second, path); - checkOptimistic(decl, *target->second); - } - if (mutation.offlineQueue && action) { - if (action->credential || !action->secretFields.empty()) { - refuse(pointerAppend(mutation.path, "offline"), - "a mutation that sends a credential or returns a secret is never queued offline"); - } - } - checkCommands(mutation.onSuccess, context); - checkCommands(mutation.onError, context); - } - - // Only a catalog that knows the result is a record can say a patch misses its list; otherwise the interpreter - // reports the miss when the patch runs. - // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the query's name, then the member holding the list. - void checkPatchAt(std::string const& queryName, std::string const& listMember, QueryDecl const& query, - std::string const& path) { - if (!_options->catalog.action) { - return; - } - auto const info = _options->catalog.action(query.action); - if (!info || !info->listFields) { - return; - } - if (listMember.empty()) { - refuse(path, std::format("`{}` answers a record, so a patch of `{}` names the member holding its list " - "with `at`", - query.action, queryName)); - } - if (std::ranges::find(*info->listFields, listMember) == info->listFields->end()) { - refuse(pointerAppend(path, "at"), - std::format("the result of `{}` has no list member `{}`", query.action, listMember)); - } - } - - void checkOptimistic(OptimisticDecl const& decl, QueryDecl const& query) { - if (!_options->catalog.action || decl.with->kind != ExprKind::Object) { - return; - } - auto const info = _options->catalog.action(query.action); - if (!info) { - return; - } - for (auto const& [field, value] : decl.with->fields) { - if (std::ranges::find(info->calculatedFields, field) != info->calculatedFields.end()) { - refuse(value->path, - std::format("`{}` is calculated by the server and is never written optimistically", field)); - } - } - } - - void checkPrefetch() { - for (std::size_t index = 0; index < _doc->prefetch.size(); ++index) { - std::string const& name = _doc->prefetch.at(index); - std::string const path = pointerAppend("/prefetch", index); - auto const found = std::ranges::find(_doc->scope.queries, name, &QueryDecl::name); - if (found == _doc->scope.queries.end()) { - refuse(path, "`" + name + "` is not a query of the screen"); - } - if (found->body && !readsOnlyParams(*found->body)) { - refuse(path, "the body of `" + name + "` reads more than the screen's params, so it cannot prefetch"); - } - } - } - - [[nodiscard]] bool readsOnlyParams(Expr const& expr) const { - if (expr.kind == ExprKind::Ref) { - return std::ranges::find(_doc->params, expr.name, &std::pair::first) != - _doc->params.end(); - } - if (expr.kind != ExprKind::Literal && expr.kind != ExprKind::Call && expr.kind != ExprKind::If && - expr.kind != ExprKind::Object && expr.kind != ExprKind::List && expr.kind != ExprKind::Get) { - return false; - } - bool only = true; - for (ExprPtr const& arg : expr.args) { - only = only && readsOnlyParams(*arg); - } - for (auto const& [name, field] : expr.fields) { - static_cast(name); - only = only && readsOnlyParams(*field); - } - return only; - } - - void checkCustomizePoints() { - std::set> arranged; - for (auto const& [name, point] : _doc->customize) { - static_cast(name); - if (point.kind == "columns" && _doc->view) { - auto const found = _elements.find(point.of); - if (found == _elements.end() || found->second->kind != "table") { - refuse(pointerAppend(point.path, "of"), - "a `columns` point names a table; `" + point.of + "` is not one"); - } - } - if (point.kind == "arrange") { - checkArranged(point, arranged); - } - } - } - - // The stored order names children by id, so the container is a stack whose every child has one, and one point - // orders it: two would each claim the order. - void checkArranged(CustomizePoint const& point, std::set>& arranged) { - auto const found = _elements.find(point.of); - if (found == _elements.end() || (found->second->kind != "column" && found->second->kind != "row") || - found->second->nodes("children").empty()) { - refuse(pointerAppend(point.path, "of"), - "an `arrange` point names a column or row of this screen that has children; `" + point.of + - "` is not one"); - } - for (DocNodePtr const& child : found->second->nodes("children")) { - if (child->id.empty()) { - refuse(pointerAppend(point.path, "of"), - "an `arrange` point orders its container's children by id; a child of `" + point.of + - "` has none"); - } - } - // An arranged container is drawn as a keyed list, which places its children as a list does. - std::string const asList = - "an arranged `" + found->second->kind + "` is drawn as a list, which takes no `align` or `justify`"; - for (std::string_view const key : {"align", "justify"}) { - if (!found->second->name(key).empty()) { - refuse(pointerAppend(found->second->path, key), asList); - } - } - if (!arranged.insert(point.of).second) { - refuse(pointerAppend(point.path, "of"), "`" + point.of + "` is arranged by another point"); - } - } - - [[nodiscard]] CheckContext innerContext(DocNode const& node, CheckContext const& context) const { - CheckContext inner = context; - inner.scope = _innerOf.at(&node); - return inner; - } - - void checkNode(DocNode const& node, CheckContext const& context) { - if (node.kind == "pageRegion") { - refuse(node.path, "a page region belongs in a page"); - } - if (!node.name("alignSelf").empty()) { - refuse(pointerAppend(node.path, "alignSelf"), std::string{kAlignSelfPlaces}); - } - if (node.flag("bleed")) { - refuse(pointerAppend(node.path, "bleed"), std::string{kBleedPlaces}); - } - checkElement(node, context, false); - } - - // What `alignSelf` places a node in. - static constexpr std::string_view kAlignSelfPlaces = "`alignSelf` places a node in its row, column or grid"; - - // What `bleed` reaches past: the horizontal padding of the stack, panel or tab page that holds the node. - static constexpr std::string_view kBleedPlaces = "`bleed` is a child's of a column, a panel or a tab"; - - // Whether the nodes under @p key of @p parent may be sized by a share of its width: a row that does not wrap, a - // splitter that is not literally vertical, and a `forEach` that is literally horizontal and does not wrap (its - // rows are the children of a row). - static bool takesPercent(DocNode const& parent, std::string_view key) { - // The content of a switch case or of an overlay is mounted into a holder that fills its slot: the interpreter - // reports a share there and makes the node fill, so the loader leaves it to the interpreter. - if (parent.kind == "case" || parent.kind == "switch" || parent.kind == "dialog" || parent.kind == "drawer") { - return true; - } - if (key != "children") { - return false; - } - if (parent.kind == "row") { - return !parent.flag("wrap"); - } - if (parent.kind == "splitter") { - ExprPtr const orientation = parent.prop("orientation"); - if (orientation != nullptr && orientation->kind == ExprKind::Literal) { - std::string const* const named = orientation->literal.asString(); - return named == nullptr || *named != "vertical"; - } - return true; - } - if (parent.kind == "forEach") { - ExprPtr const axis = parent.prop("axis"); - if (axis == nullptr || axis->kind != ExprKind::Literal) { - return false; - } - std::string const* const named = axis->literal.asString(); - return named != nullptr && *named == "horizontal" && !parent.flag("wrap"); - } - return false; - } - - // A child that places itself sits in a row, a column, a grid or a `forEach`; any other parent (a panel, a dialog, - // a tab page) has no cross axis to place it on. - static void checkPlacements(DocNode const& parent) { - bool const places = parent.kind == "row" || parent.kind == "column" || parent.kind == "grid" || - parent.kind == "forEach" || parent.kind == "actionBar"; - bool const bleeds = parent.kind == "column" || parent.kind == "panel" || parent.kind == "tab"; - for (auto const& [key, nodes] : parent.children) { - for (DocNodePtr const& child : nodes) { - if (child->kind == "pageRegion" && parent.kind != "page") { - refuse(child->path, "a page region belongs in a page"); - } - if (!child->name("alignSelf").empty() && (!places || key != "children")) { - refuse(pointerAppend(child->path, "alignSelf"), std::string{kAlignSelfPlaces}); - } - if (child->flag("bleed") && (!bleeds || key != "children")) { - refuse(pointerAppend(child->path, "bleed"), std::string{kBleedPlaces}); - } - if (hasPercentWidth(*child) && !takesPercent(parent, key)) { - refuse(pointerAppend(child->path, "sizing"), std::string{kPercentPlaces}); - } - } - } - } - - // A tab page's padding is `pageInset`, else `inset`, both literal steps. A page of no padding has nothing for a - // child's `bleed` to reach past, so the document is refused rather than the flag silently doing nothing; a step - // that is computed is left to the mount. Any node that is not a `tabs` is passed over. - static void checkTabBleed(DocNode const& tabs) { - if (tabs.kind != "tabs") { - return; - } - auto const step = [&tabs](std::string_view key) -> std::optional { - ExprPtr const expr = tabs.prop(key); - if (expr == nullptr) { - return std::nullopt; - } - std::int64_t const* const literal = expr->kind == ExprKind::Literal ? expr->literal.asInt() : nullptr; - return literal != nullptr ? std::optional{*literal} : std::optional{-1}; - }; - auto const page = step("pageInset"); - auto const outer = step("inset"); - std::int64_t const effective = page.value_or(outer.value_or(0)); - if (effective != 0) { - return; - } - for (DocNodePtr const& tab : tabs.partList("tabs")) { - auto const found = tab->children.find("children"); - if (found == tab->children.end()) { - continue; - } - for (DocNodePtr const& child : found->second) { - if (child->flag("bleed")) { - refuse(pointerAppend(child->path, "bleed"), - "`bleed` reaches past the padding of the tab page, and this page has none: give the tabs " - "a `pageInset`, or an `inset`, above 0"); - } - } - } - } - - void checkElement(DocNode const& node, CheckContext const& outer, bool part) { - KindSpec const* const spec = findKind(node.kind, part); - CheckContext const inner = innerContext(node, outer); - if (auto const found = _scopeOf.find(&node); found != _scopeOf.end()) { - // NOLINTNEXTLINE(bugprone-unchecked-optional-access): a node or case with a scope of its own has its declarations. - checkScope(*node.scope, inner); - } - checkProps(node, spec, inner, outer); - for (auto const& [key, commands] : node.events) { - if (node.kind == "custom") { - checkCustomEvent(node, key.substr(3), node.path); - } - checkCommands(commands, isInner(spec, key) ? inner : outer); - } - for (auto const& [chord, commands] : node.keys) { - static_cast(chord); - checkCommands(commands, outer); - } - for (auto const& [key, nodes] : node.children) { - CheckContext context = isInner(spec, key) ? inner : outer; - context.boundaryError = (keyFlags(*spec, key) & kBoundaryError) != 0 || context.boundaryError; - for (DocNodePtr const& child : nodes) { - checkElement(*child, context, false); - } - } - for (auto const& [key, parts] : node.parts) { - CheckContext const& context = isInner(spec, key) ? inner : outer; - for (DocNodePtr const& child : parts) { - checkElement(*child, context, true); - } - } - checkPlacements(node); - checkTabBleed(node); - if (part) { - checkPartNode(node); - } else { - checkFlags(node); - checkLayoutKeys(node); - checkKindRules(node, outer); - // An overlay's footer actions; a form's field components. - checkActionButtons(node.partList("actions"), pointerAppend(node.path, "actions")); - checkFieldComponents(node); - } - } - - static void checkPartNode(DocNode const& node) { - if (node.kind == "column" || node.kind == "track") { - checkNoPercentWidth(node); - } - if (node.kind == "column") { - checkColumnPart(node); - } else if (node.kind == "track") { - checkCellPlace(node, "align"); - } else if (isMenuEntry(node.kind)) { - checkMenuItem(node); - } - } - - void checkProps(DocNode const& node, KindSpec const* spec, CheckContext const& inner, CheckContext const& outer) { - for (auto const& [key, expr] : node.props) { - CheckContext const& context = isInner(spec, key) ? inner : outer; - if (isCondition(spec, key)) { - checkCondition(*expr, context, "`" + key + "`"); - continue; - } - Type const type = checkExpr(*expr, context); - if (node.kind == "dateTimeInput" && key == "value") { - checkDateValue(node, *expr, type); - } - } - } - - void checkCustomEvent(DocNode const& node, std::string const& event, std::string const& path) { - auto const found = _doc->components.find(node.name("name")); - if (found != _doc->components.end() && !found->second.events.contains(event)) { - refuse(pointerAppend(pointerAppend(path, "on"), event), - "the component `" + found->second.name + "` declares no event `" + event + "`"); - } - } - - // What a chart's literal keys may be, and the shape of its series and lines. A computed `tone` or `yMin` is - // checked when it is evaluated, and reported then. - static void checkChart(DocNode const& node) { - static constexpr std::size_t kMaxSeries = 4; - static constexpr std::size_t kMaxLines = 16; - std::span const series = node.partList("series"); - std::string const seriesPath = pointerAppend(node.path, "series"); - if (series.empty() || series.size() > kMaxSeries) { - refuse(seriesPath, "a chart draws 1 to 4 series"); - } - if (node.partList("lines").size() > kMaxLines) { - refuse(pointerAppend(node.path, "lines"), "a chart draws at most 16 reference lines"); - } - bool const positioned = series.front()->prop("x") != nullptr; - for (DocNodePtr const& part : series) { - DocNode const& one = *part; - if (series.size() > 1 && one.prop("label") == nullptr) { - refuse(one.path, "each of two or more series has a `label`, its name in the legend"); - } - if ((one.prop("x") != nullptr) != positioned) { - refuse(one.path, "`x` is on every series of a chart or on none"); - } - checkChartTone(one); - std::string_view const style = one.name("style"); - if (!style.empty() && style != "line" && style != "bars") { - refuse(pointerAppend(one.path, "style"), "a series `style` is `line` or `bars`"); - } - if (style == "bars" && one.flag("joined")) { - refuse(pointerAppend(one.path, "joined"), "a `bars` series is not joined"); - } - } - for (DocNodePtr const& line : node.partList("lines")) { - checkChartTone(*line); - std::string_view const style = line->name("style"); - if (!style.empty() && style != "solid" && style != "dashed" && style != "dotted") { - refuse(pointerAppend(line->path, "style"), "`style` is `solid`, `dashed` or `dotted`"); - } - } - if (ExprPtr const places = node.prop("yPlaces")) { - std::int64_t const* const literal = places->kind == ExprKind::Literal ? places->literal.asInt() : nullptr; - if (literal == nullptr || *literal < 0 || std::cmp_greater(*literal, math::kMaxDecimalPlaces)) { - refuse(places->path, "`yPlaces` is a literal integer from 0 to 18"); - } - } - ExprPtr const low = node.prop("yMin"); - ExprPtr const high = node.prop("yMax"); - if (low && high && low->kind == ExprKind::Literal && high->kind == ExprKind::Literal) { - std::optional const lowNumber = numeric(low->literal); - std::optional const highNumber = numeric(high->literal); - if (lowNumber && highNumber && highNumber->value < lowNumber->value) { - refuse(low->path, "`yMin` is above `yMax`"); - } - } - } - - // A literal `tone` of a chart's series or line names one of the five tones; `null` marks nothing. - static void checkChartTone(DocNode const& part) { - ExprPtr const tone = part.prop("tone"); - if (!tone || tone->kind != ExprKind::Literal || tone->literal.isNull()) { - return; - } - static constexpr std::array kTones = {"neutral", "info", "ok", "warn", "err"}; - std::string const* const name = tone->literal.asString(); - if (name == nullptr || !listed(kTones, *name)) { - refuse(tone->path, "`tone` is `neutral`, `info`, `ok`, `warn` or `err`"); - } - } - - // A flag that needs a key beside it. - static void checkFlags(DocNode const& node) { - if (node.flag("showLabel") && node.prop("label") == nullptr) { - refuse(pointerAppend(node.path, "showLabel"), "`showLabel` shows the `label`, and the node gives none"); - } - } - - void checkKindRules(DocNode const& node, CheckContext const& context) { - if (node.kind == "custom") { - checkCustomProps(node); - } else if (node.kind == "tabs") { - checkTabIds(node); - checkTabsInset(node); - } else if (node.kind == "chart") { - checkChart(node); - } else if (node.kind == "page") { - checkPage(node); - } else if (node.kind == "localeScope") { - checkLocaleScope(node); - } else if (node.kind == "customize" && !_doc->customize.contains(node.name("point"))) { - refuse(pointerAppend(node.path, "point"), - "`" + std::string{node.name("point")} + "` is not a customization point of this document"); - } - checkKindValues(node); - checkSheet(node); - std::string_view const model = node.name("model"); - if (!model.empty()) { - if (node.name("action").empty()) { - refuse(node.path, "a `" + node.kind + "` with a `model` names its `action`"); - } - checkModelAction(context, std::string{model}, std::string{node.name("action")}, node.path); - } else if (node.kind == "table" && !node.prop("rows")) { - refuse(node.path, "a table takes `rows`, or a `model` and `action`"); - } - if (node.kind == "table") { - checkTableSelection(node); - checkSelectColumn(node); - checkTableSort(node); - checkTablePaging(node); - checkTableGroup(node); - checkRowsTableKeys(node); - } - } - - // Whether a node gives the common key @p key. - static bool gives(DocNode const& node, std::string_view key) { - return node.props.contains(key) || node.names.contains(key) || node.flags.contains(key) || - node.parts.contains(key) || (key == "keys" && !node.keys.empty()) || (key == "id" && !node.id.empty()); - } - - // The common keys a page node does not take, each refused where it is written. - static void refuseKeys(DocNode const& node, std::span keys, std::string_view why) { - for (std::string_view const key : keys) { - if (gives(node, key)) { - refuse(pointerAppend(node.path, key), "`" + std::string{key} + "` " + std::string{why}); - } - } - } - - // A page holds regions and nothing else, each valid on the sheet; the sheet sizes itself. - static void checkPage(DocNode const& node) { - static constexpr std::array kRefused = { - "sizing", "minWidth", "maxWidth", "minHeight", "maxHeight", "bleed", "drag", "drop", "autofocus"}; - refuseKeys(node, kRefused, "is refused on a page: the sheet is sized by its geometry"); - if (node.name("alignSelf") == "stretch") { - refuse(pointerAppend(node.path, "alignSelf"), "a page is never stretched; `alignSelf` places the sheet"); - } - PageGeometry const page = pageGeometryOf(node); - for (DocNodePtr const& child : node.nodes("children")) { - if (child->kind != "pageRegion") { - refuse(child->path, "a page holds page regions and nothing else"); - } - static constexpr std::array kRegionRefused = { - "sizing", "minWidth", "maxWidth", "minHeight", "maxHeight", "alignSelf", - "bleed", "span", "drag", "drop", "autofocus"}; - refuseKeys(*child, kRegionRefused, "is refused on a page region: its geometry names its size"); - static_cast(regionGeometryOf(*child, page)); - } - } - - // A scope is not a widget, so it takes none of the keys every widget takes. - static void checkLocaleScope(DocNode const& node) { - for (KeySpec const& key : kCommonKeys) { - if (gives(node, key.key)) { - refuse(pointerAppend(node.path, key.key), - "`" + std::string{key.key} + - "` is refused on a locale scope: it is not a widget; wrap it in a " - "node that has one"); - } - } - } - - // A dialog's `sheet` and the label of its dismiss control: a drawer already fills the height on a phone and takes - // neither, and a `dismissLabel` labels only a sheet's control. - static void checkSheet(DocNode const& node) { - if (node.kind == "drawer") { - for (std::string_view const key : {"sheet", "dismissLabel"}) { - if (node.prop(key)) { - refuse(pointerAppend(node.path, key), - "`" + std::string{key} + "` is a dialog's; a drawer already fills the height"); - } - } - } else if (node.kind == "dialog" && node.prop("dismissLabel") && !node.prop("sheet")) { - refuse(pointerAppend(node.path, "dismissLabel"), - "`dismissLabel` labels a sheet's dismiss control; give the dialog `sheet`"); - } - } - - // A sortable column is named by its id, which a sort key gives; `sortBy` says how a sortable column orders. A - // literal `sort` names sortable columns, each once, with a direction, and `onSortChange` needs a header that - // sorts. A model-backed table's engine sorts, so none of these belongs on one. - static void checkTableSort(DocNode const& node) { - bool const modelBacked = !node.name("model").empty(); - std::set> sortable; - for (DocNodePtr const& column : node.partList("columns")) { - bool const sorts = column->flag("sortable"); - if (sorts && modelBacked) { - refuse(pointerAppend(column->path, "sortable"), - "a model-backed table's engine sorts; `sortable` is for a table over `rows`"); - } - if (sorts && column->id.empty()) { - refuse(pointerAppend(column->path, "sortable"), "a sortable column needs an `id`, which a sort names"); - } - if (column->prop("sortBy") != nullptr && !sorts) { - refuse(pointerAppend(column->path, "sortBy"), - "`sortBy` says how a sortable column orders the rows; give the column `sortable`"); - } - if (sorts) { - sortable.insert(column->id); - } - } - if (node.event("onSortChange") != nullptr && sortable.empty()) { - refuse(pointerAppend(node.path, "onSortChange"), - "`onSortChange` runs when a header sorts the table; give a column `sortable`"); - } - ExprPtr const sort = node.prop("sort"); - if (sort != nullptr && sort->kind == ExprKind::Literal && !modelBacked && !sort->literal.isNull()) { - checkLiteralSort(sort->literal, pointerAppend(node.path, "sort"), sortable); - } - } - - // A literal sort: a list of keys, each naming one of @p sortable once, with a direction. - static void checkLiteralSort(Value const& sort, std::string const& where, - std::set> const& sortable) { - ValueList const* const keys = sort.asList(); - if (keys == nullptr) { - refuse( - where, - R"(a table's sort is a list of keys, each {"column": , "direction": "asc" or "desc"})"); - } - std::set> named; - for (Value const& key : *keys) { - Value const* const column = key.field("column"); - Value const* const direction = key.field("direction"); - std::string const* const columnId = column == nullptr ? nullptr : column->asString(); - std::string const* const way = direction == nullptr ? nullptr : direction->asString(); - if (columnId == nullptr || way == nullptr || (*way != "asc" && *way != "desc")) { - refuse(where, R"(a sort key is {"column": , "direction": "asc" or "desc"})"); - } - if (!sortable.contains(*columnId)) { - refuse(where, "the sort names `" + *columnId + "`, which is not a sortable column"); - } - if (!named.insert(*columnId).second) { - refuse(where, "the sort names `" + *columnId + "` twice"); - } - } - } - - // A table over `rows` draws its own group headings; a model-backed table's engine shapes its rows. - static void checkTableGroup(DocNode const& node) { - if (!node.name("model").empty() && !node.partList("group").empty()) { - refuse(pointerAppend(node.path, "group"), - "a model-backed table's engine shapes its rows; `group` is for a table over `rows`"); - } - } - - // A table over `rows` pages itself by `pageSize`, at `page`; a model-backed table's engine pages. - static void checkTablePaging(DocNode const& node) { - ExprPtr const size = node.prop("pageSize"); - ExprPtr const page = node.prop("page"); - if (!node.name("model").empty() && (size != nullptr || page != nullptr)) { - refuse(pointerAppend(node.path, size != nullptr ? "pageSize" : "page"), - "a model-backed table's engine pages; `pageSize` and `page` are for a table over `rows`"); - } - if (page != nullptr && size == nullptr) { - refuse(pointerAppend(node.path, "page"), - "`page` picks a page of `pageSize` rows; give the table `pageSize`"); - } - if (size != nullptr && size->kind == ExprKind::Literal && !size->literal.isNull()) { - std::int64_t const* const rows = size->literal.asInt(); - if (rows == nullptr || *rows < 1) { - refuse(pointerAppend(node.path, "pageSize"), "a page holds a positive whole number of rows"); - } - } - } - - // The keys of a model-backed table that a table over `rows` would accept and ignore. - static void checkRowsTableKeys(DocNode const& node) { - if (!node.prop("rows")) { - return; - } - if (node.prop("filters") != nullptr) { - refuse(pointerAppend(node.path, "filters"), - "`filters` belongs to a model-backed table; filter `rows` with `filter`"); - } - if (node.prop("highlightKey") != nullptr) { - refuse(pointerAppend(node.path, "highlightKey"), "`highlightKey` links a model-backed table to a chart"); - } - } - - // The select column draws a `multiple` table's selection, so it needs a literal `multiple`; its header's name - // needs the column. - static void checkSelectColumn(DocNode const& node) { - bool const drawn = node.flag("selectColumn"); - if (drawn) { - ExprPtr const mode = node.prop("selectionMode"); - std::string const* const literal = - mode != nullptr && mode->kind == ExprKind::Literal ? mode->literal.asString() : nullptr; - if (literal == nullptr || *literal != "multiple") { - refuse(pointerAppend(node.path, "selectColumn"), - "a select column draws a table's selection of several rows; give it `selectionMode` " - "`multiple`"); - } - } - if (!drawn && node.prop("selectAllLabel") != nullptr) { - refuse(pointerAppend(node.path, "selectAllLabel"), - "`selectAllLabel` names the select column's header " - "box; give the table `selectColumn`"); - } - } - - // A table's `selection` and `onSelectionChange` need rows the user can select, and rows the document holds: a - // model-backed table's engine owns its selection. - static void checkTableSelection(DocNode const& node) { - std::string_view key; - if (node.prop("selection") != nullptr) { - key = "selection"; - } else if (node.event("onSelectionChange") != nullptr) { - key = "onSelectionChange"; - } else { - return; - } - std::string const where = pointerAppend(node.path, key); - if (!node.name("model").empty()) { - refuse(where, "a model-backed table's engine owns its selection; `" + std::string{key} + - "` is for a table over `rows`"); - } - ExprPtr const mode = node.prop("selectionMode"); - std::string const* const literal = - mode != nullptr && mode->kind == ExprKind::Literal ? mode->literal.asString() : nullptr; - if (mode == nullptr || (literal != nullptr && *literal == "none")) { - refuse(where, "a table with `" + std::string{key} + - "` selects rows; give it `selectionMode` `single` or `multiple`"); - } - } - - // A tabs node that names its shown tab, or reports a pick, keys every tab by a unique id; a literal `selected` - // names one of them. A literal `null` is no binding. - static void checkTabIds(DocNode const& node) { - ExprPtr const selected = node.prop("selected"); - bool const bound = selected != nullptr && (selected->kind != ExprKind::Literal || !selected->literal.isNull()); - bool const keyed = bound || node.event("onChoose") != nullptr; - std::set> ids; - for (DocNodePtr const& tab : node.partList("tabs")) { - if (tab->id.empty()) { - if (keyed) { - refuse(tab->path, "a tab of a tabs node with `selected` or `onChoose` has an `id`"); - } - continue; - } - if (!ids.insert(tab->id).second) { - refuse(pointerAppend(tab->path, "id"), - "the tab id `" + tab->id + "` is used twice; each tab has its own"); - } - } - if (bound && selected->kind == ExprKind::Literal) { - std::string const* const named = selected->literal.asString(); - if (named == nullptr || !ids.contains(*named)) { - refuse(pointerAppend(node.path, "selected"), "`selected` names no tab of this node"); - } - } - } - - // A tabs node's `inset` and `pageInset` are literal spacing steps, 0 to 5: the strip and the pages are laid out - // once. - static void checkTabsInset(DocNode const& node) { - for (std::string_view const key : {"inset", "pageInset"}) { - ExprPtr const inset = node.prop(key); - if (inset == nullptr) { - continue; - } - std::int64_t const* const step = inset->kind == ExprKind::Literal ? inset->literal.asInt() : nullptr; - if (step == nullptr || *step < 0 || *step > 5) { - refuse(pointerAppend(node.path, key), - "`" + std::string{key} + "` is a literal spacing step from 0 to 5"); - } - } - } - - // A custom node names a component of the document and gives only the props it declares. - void checkCustomProps(DocNode const& node) const { - auto const found = _doc->components.find(node.name("name")); - if (found == _doc->components.end()) { - refuse(pointerAppend(node.path, "name"), - "`" + std::string{node.name("name")} + "` is not a component of this document"); - } - for (DocNodePtr const& props : node.partList("props")) { - for (auto const& [prop, value] : props->props) { - if (!found->second.props.contains(prop)) { - refuse(value->path, "the component `" + found->first + "` declares no prop `" + prop + "`"); - } - } - } - } - - // A stack's literal `padding` list is two spacing steps, vertical then horizontal, each 0 to 5; a panel's is one - // step. A computed padding is read at mount. - static void checkPadding(DocNode const& node) { - ExprPtr const padding = node.prop("padding"); - if (padding == nullptr || padding->kind != ExprKind::Literal) { - return; - } - ValueList const* const list = padding->literal.asList(); - if (list == nullptr) { - return; - } - if (node.kind == "panel") { - refuse(pointerAppend(node.path, "padding"), "a panel's `padding` is one spacing step, not a list"); - } - // The largest spacing step, as `kMaxSpacingStep` (view.hpp) names it. - static constexpr std::int64_t kMostSteps = 5; - bool const steps = list->size() == 2 && std::ranges::all_of(*list, [](Value const& step) { - std::int64_t const* const whole = step.asInt(); - return whole != nullptr && *whole >= 0 && *whole <= kMostSteps; - }); - if (!steps) { - refuse(pointerAppend(node.path, "padding"), - "a `padding` list is two spacing steps, vertical then horizontal, each from 0 to 5"); - } - } - - // The closed-set keys of a button, and the shape and style pair that cannot go together. - static void checkButtonValues(DocNode const& node) { - static constexpr std::array kEmphasis = {"normal", "primary", "danger", "ghost", - "dangerOutline"}; - checkChoice(node, "emphasis", kEmphasis); - static constexpr std::array kStyles = {"push", "item"}; - checkChoice(node, "style", kStyles); - static constexpr std::array kShapes = {"default", "round", "square"}; - checkChoice(node, "shape", kShapes); - if (node.name("shape") == "square" && node.name("style") == "item") { - refuse(pointerAppend(node.path, "shape"), - "an item fills its line, so it has no square outline; `square` is a push button's"); - } - static constexpr std::array kSizes = {"normal", "small"}; - checkChoice(node, "size", kSizes); - if (std::string_view const weight = node.name("weight"); !weight.empty() && !weightNamed(weight)) { - refuse(pointerAppend(node.path, "weight"), - "`" + std::string{weight} + "` is not a font weight name, such as `semi-bold`"); - } - checkEntryContent(node); - } - - // The keys of a kind that take one of a closed set of values, and the pairs of keys that need each other. - static void checkKindValues(DocNode const& node) { - if (node.kind == "column" || node.kind == "row" || node.kind == "panel") { - checkPadding(node); - } - if ((node.kind == "column" || node.kind == "row") && node.flag("headJoined") && !node.flag("pageEdge")) { - refuse(pointerAppend(node.path, "headJoined"), - "`headJoined` needs `pageEdge`: an inset page has a margin between it and the head"); - } - if (node.kind == "button") { - checkButtonValues(node); - } else if (node.kind == "grid") { - checkGrid(node); - } else if (node.kind == "actionBar") { - checkActionBar(node); - } else if (node.kind == "column" && node.flags.contains("wrap")) { - refuse(pointerAppend(node.path, "wrap"), "only a row wraps; a column has no lines to continue on"); - } else if (node.kind == "row" && node.flag("divided") && node.flag("wrap")) { - refuse(pointerAppend(node.path, "divided"), - "a wrapping row has no single line to rule between; `divided` is for a row that does not `wrap`"); - } else if (node.kind == "forEach") { - checkForEachWrap(node); - } else if (node.kind == "menu") { - checkMenu(node); - } else if (node.kind == "badge" && node.prop("removeLabel") != nullptr && node.event("onRemove") == nullptr) { - refuse(pointerAppend(node.path, "removeLabel"), - "`removeLabel` names a removable badge's remove control; the badge gives no `onRemove`"); - } else if (node.kind == "textInput") { - static constexpr std::array kCommit = {"change", "blur", "enter"}; - checkChoice(node, "commitOn", kCommit); - static constexpr std::array kInputEmphases = {"normal", "prominent"}; - checkChoice(node, "emphasis", kInputEmphases); - static constexpr std::array kInputAligns = {"start", "center", "end"}; - checkChoice(node, "align", kInputAligns); - checkMultilineExtras(node); - } else if (node.kind == "select") { - static constexpr std::array kStale = {"clear", "keep"}; - checkChoice(node, "onStale", kStale); - checkSelectStyle(node); - } else if (node.kind == "text") { - checkText(node); - } else if (node.kind == "banner") { - checkBanner(node); - } else if (node.kind == "badge") { - static constexpr std::array kBadgeStyles = {"filled", "outline", "quiet"}; - checkChoice(node, "style", kBadgeStyles); - static constexpr std::array kBadgeShapes = {"default", "round"}; - checkChoice(node, "shape", kBadgeShapes); - } else if (node.kind == "keyValue") { - static constexpr std::array kCaptionPlaces = {"inline", "stacked"}; - checkChoice(node, "fieldLayout", kCaptionPlaces); - checkCaptionWidth(node, node.name("fieldLayout") != "stacked"); - checkItemSpans(node.prop("items")); - } else if (node.kind == "table") { - checkCellPlace(node, "valign"); - } - if (node.kind == "form" || node.kind == "collection" || node.kind == "wizard") { - checkFormColumns(node); - static constexpr std::array kFieldLayouts = {"stacked", "inline"}; - checkChoice(node, "fieldLayout", kFieldLayouts); - checkCaptionWidth(node, node.name("fieldLayout") == "inline"); - } - static constexpr std::array kAlign = {"start", "center", "end", "stretch"}; - static constexpr std::array kJustify = {"start", "center", "end", "between"}; - checkChoice(node, "align", kAlign); - checkChoice(node, "justify", kJustify); - checkChoice(node, "alignSelf", kAlign); - checkSurfaceValues(node); - } - - // Each form field drawn by a host component. - void checkFieldComponents(DocNode const& form) const { - if (form.kind != "form") { - return; - } - for (DocNodePtr const& record : form.partList("fields")) { - for (DocNodePtr const& field : record->partList("fields")) { - if (!field->name("component").empty()) { - checkFieldComponent(*field); - } - } - } - } - - // A form field drawn by a host component: a declared one with a `value` prop and a `change` event, given only - // props it declares, and not beside a `widget`, which would choose the control too. - void checkFieldComponent(DocNode const& field) const { - std::string_view const name = field.name("component"); - std::string const where = pointerAppend(field.path, "component"); - auto const found = _doc->components.find(name); - if (found == _doc->components.end()) { - refuse(where, "`" + std::string{name} + "` is not a component of this document"); - } - Component const& component = found->second; - if (!component.props.contains("value") || !component.events.contains("change")) { - refuse(where, "the component `" + component.name + - "` draws a form field, so it declares a prop `value` and an event `change`"); - } - if (field.prop("widget") != nullptr) { - refuse(where, "`component` and `widget` both choose the field's control; give one"); - } - for (DocNodePtr const& props : field.partList("props")) { - for (auto const& [prop, value] : props->props) { - if (!component.props.contains(prop)) { - refuse(value->path, "the component `" + component.name + "` declares no prop `" + prop + "`"); - } - } - } - } - - // The document's top-level parts: a screen head's status badges, actions, menu entries and tools, and the app - // document's navigation badges. - [[nodiscard]] std::vector headParts() const { - std::vector parts = _doc->status; - parts.insert(parts.end(), _doc->actions.begin(), _doc->actions.end()); - parts.insert(parts.end(), _doc->menu.begin(), _doc->menu.end()); - parts.insert(parts.end(), _doc->tools.begin(), _doc->tools.end()); - parts.insert(parts.end(), _doc->navigation.begin(), _doc->navigation.end()); - return parts; - } - - // The head's tools: each id once, and each one its kind's. - static void checkHeadTools(std::span tools) { - std::set ids; - for (DocNodePtr const& tool : tools) { - if (!ids.insert(tool->id).second) { - refuse(pointerAppend(tool->path, "id"), - "the head tool id `" + tool->id + "` is used twice; each tool has its own"); - } - checkHeadTool(*tool); - } - } - - // One head tool: a kind of the two, only its kind's keys, a select's options in a dropdown, a literal width. - static void checkHeadTool(DocNode const& tool) { - static constexpr std::array kSearchOnly = {"value", "placeholder", "onChange", - "onSubmit"}; - static constexpr std::array kSelectOnly = {"options", "selected", "style", "onChoose"}; - std::string_view const kind = tool.name("kind"); - if (kind != "search" && kind != "select") { - refuse(pointerAppend(tool.path, "kind"), - "`" + std::string{kind} + "` is not one of the values of `kind`: search or select"); - } - bool const search = kind == "search"; - for (std::string_view const key : search ? kSelectOnly : kSearchOnly) { - if (tool.prop(key) || tool.event(key) != nullptr || !tool.name(key).empty()) { - refuse(pointerAppend(tool.path, key), - "`" + std::string{key} + "` is a " + (search ? "select" : "search") + " tool's"); - } - } - if (!search && !tool.prop("options")) { - refuse(tool.path, "a select tool has `options`"); - } - if (std::string_view const style = tool.name("style"); !style.empty() && style != "dropdown") { - refuse(pointerAppend(tool.path, "style"), - "`" + std::string{style} + "` is not one of the values of `style`: dropdown"); - } - ExprPtr const width = tool.prop("width"); - std::int64_t const* const units = width && width->kind == ExprKind::Literal - ? width->literal.asInt() - : static_cast(nullptr); - if (width && (units == nullptr || *units < 1)) { - refuse(pointerAppend(tool.path, "width"), "`width` is a literal whole number of units, 1 or more"); - } - } - - // The head menu's entries, at every level: an entry that is chosen has an id, unique across the whole menu, since - // `ScreenHead::choose` names it by that id; a separator or a submenu is never chosen and takes none. - // NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. - static void checkHeadMenu(std::span entries, std::set& ids) { - for (DocNodePtr const& entry : entries) { - bool const submenu = !entry->partList("items").empty(); - if (entry->flag("separator") || submenu) { - if (!entry->id.empty()) { - refuse(pointerAppend(entry->path, "id"), - submenu ? "a submenu is opened, not chosen, and takes no `id`" - : "a separator is a line between entries and takes no other key"); - } - checkHeadMenu(entry->partList("items"), ids); - continue; - } - if (entry->id.empty()) { - refuse(entry->path, "a head menu entry has an `id`, which choosing it names"); - } - if (!ids.insert(entry->id).second) { - refuse(pointerAppend(entry->path, "id"), - "the head menu entry id `" + entry->id + "` is used twice; each entry has its own"); - } - } - } - - // A list of `actionButton` parts: each id once, and each emphasis one of a button's. - static void checkActionButtons(std::span buttons, std::string const& path) { - static constexpr std::array kEmphasis = {"normal", "primary", "danger", "ghost", - "dangerOutline"}; - std::set ids; - for (DocNodePtr const& button : buttons) { - if (!ids.insert(button->id).second) { - refuse(pointerAppend(button->path, "id"), - "the action id `" + button->id + "` is used twice in " + path + "; each action has its own"); - } - checkChoice(*button, "emphasis", kEmphasis); - } - } - - // A literal sizing of one dimension: `"content"`, `{"fixed": n}` (n of 0 or more), `{"stretch": w}` (w of 1 or - // more) or `{"percent": n}` (n from 1 to 100). Answers the fixed amount, if it is one. - static std::optional sizingDimension(Value const& value, std::string const& path) { - static constexpr std::string_view kForms = - "`sizing` is `\"content\"`, `{\"fixed\": n}`, `{\"stretch\": w}`, `{\"percent\": n}` (n from 1 to 100), " - "or a " - "record of `width` and `height` of them"; - if (std::string const* const text = value.asString(); text != nullptr && *text == "content") { - return std::nullopt; - } - ValueRecord const* const record = value.asRecord(); - if (record != nullptr && record->size() == 1) { - auto const& [form, amount] = *record->begin(); - std::int64_t const* const units = amount.asInt(); - if (form == "fixed" && units != nullptr && *units >= 0) { - return *units; - } - if (form == "stretch" && units != nullptr && *units >= 1) { - return std::nullopt; - } - if (form == "percent" && units != nullptr && *units >= 1 && *units <= 100) { - return std::nullopt; - } - } - refuse(path, std::string{kForms}); - } - - // Whether a literal sizing dimension is `{"percent": n}`. - static bool isPercent(Value const& value) { - ValueRecord const* const record = value.asRecord(); - return record != nullptr && record->size() == 1 && record->begin()->first == "percent"; - } - - // Whether a literal `sizing` gives the node a percent width: as the single form, or as the `width` of a record. - static bool hasPercentWidth(DocNode const& node) { - ExprPtr const sizing = node.prop("sizing"); - if (sizing == nullptr || sizing->kind != ExprKind::Literal) { - return false; - } - ValueRecord const* const record = sizing->literal.asRecord(); - if (record != nullptr && (record->contains("width") || record->contains("height"))) { - auto const found = record->find("width"); - return found != record->end() && isPercent(found->second); - } - return isPercent(sizing->literal); - } - - // A table column's or a grid track's literal `width` is no share: a track is sized by the grid, a column by its - // table. - static void checkNoPercentWidth(DocNode const& node) { - ExprPtr const width = node.prop("width"); - if (width != nullptr && width->kind == ExprKind::Literal && isPercent(width->literal)) { - refuse(width->path, std::string{kPercentPlaces}); - } - } - - // What a percent sizes: a width along a row or a horizontal splitter's pane. - static constexpr std::string_view kPercentPlaces = - "`percent` sizes a width along a row or a horizontal splitter; nothing here takes a share"; - - // A node's size keys: each bound a literal integer of 0 or more, a minimum no more than its maximum, no bound on - // an overlay or a custom node; and a literal `sizing` one of the forms the interpreter reads, with a fixed amount - // inside its dimension's bounds. A sizing that is not literal is read at mount. - static void checkLayoutKeys(DocNode const& node) { checkSizing(node, literalBounds(node)); } - - // The size bounds a node gives, `minWidth`, `maxWidth`, `minHeight` and `maxHeight` in that order: literal - // integers of 0 or more, no minimum above its maximum, none on an overlay or a custom node. - static std::array, 4> literalBounds(DocNode const& node) { - static constexpr std::array kBounds = {"minWidth", "maxWidth", "minHeight", "maxHeight"}; - std::array, 4> bounds{}; - for (std::size_t index = 0; index < kBounds.size(); ++index) { - std::string_view const key = kBounds.at(index); - ExprPtr const bound = node.prop(key); - if (bound == nullptr) { - continue; - } - if (node.kind == "dialog" || node.kind == "drawer") { - refuse(bound->path, "an overlay is sized by the frontend, not by its container"); - } - if (node.kind == "custom") { - refuse(bound->path, - "a custom node carries no common properties, so it takes no `" + std::string{key} + "`"); - } - std::int64_t const* const units = - bound->kind == ExprKind::Literal ? bound->literal.asInt() : static_cast(nullptr); - if (units == nullptr || *units < 0) { - refuse(bound->path, "`" + std::string{key} + "` is a literal integer of 0 or more, in backend units"); - } - bounds.at(index) = *units; - } - for (std::size_t axis = 0; axis < 2; ++axis) { - auto const& minimum = bounds.at(2 * axis); - auto const& maximum = bounds.at((2 * axis) + 1); - if (minimum && maximum && *minimum > *maximum) { - refuse(pointerAppend(node.path, kBounds.at(2 * axis)), - "`" + std::string{kBounds.at(2 * axis)} + "` is more than `" + - std::string{kBounds.at((2 * axis) + 1)} + "`"); - } - } - return bounds; - } - - // Whether a literal sizing dimension's value is `{"stretch": w}` (as opposed to `"content"` or `{"fixed": n}`, - // which both `sizingDimension` reports the same way -- as "no fixed amount"). An overlay is sized by the - // frontend, not by its container, so stretching it would silently change how every *other* sibling in its own - // parent layout is justified; checked ahead of `sizingDimension` itself, which does not distinguish the two. - static bool isStretch(Value const& value) { - ValueRecord const* const record = value.asRecord(); - return record != nullptr && record->size() == 1 && record->begin()->first == "stretch"; - } - - // An overlay (`dialog`/`drawer`) refuses a literal `sizing` that stretches either dimension, single-value or - // record form: an overlay is sized by the frontend, not by its container, so stretching it would silently change - // how every *other* sibling in its own parent layout is justified. - static void checkOverlaySizing(DocNode const& node, ExprPtr const& sizing) { - if (node.kind != "dialog" && node.kind != "drawer") { - return; - } - ValueRecord const* const record = sizing->literal.asRecord(); - bool const stretches = - isStretch(sizing->literal) || - (record != nullptr && (record->contains("width") || record->contains("height")) && - std::ranges::any_of(*record, [](auto const& entry) { return isStretch(entry.second); })); - if (stretches) { - refuse(sizing->path, - "an overlay is sized by the frontend, not by its container; give it `{\"fixed\": n}` instead " - "of `{\"stretch\": w}`"); - } - } - - // A literal `sizing` gives a percent as neither a height nor the width of an overlay. - static void checkPercentSizing(DocNode const& node, ExprPtr const& sizing) { - ValueRecord const* const record = sizing->literal.asRecord(); - if (record != nullptr && record->contains("height") && isPercent(record->at("height"))) { - refuse(sizing->path, std::string{kPercentPlaces}); - } - if (hasPercentWidth(node) && (node.kind == "dialog" || node.kind == "drawer")) { - refuse(sizing->path, std::string{kPercentPlaces}); - } - } - - // A literal `sizing` is one of its forms, and a fixed amount lies inside its dimension's @p bounds. - static void checkSizing(DocNode const& node, std::array, 4> const& bounds) { - ExprPtr const sizing = node.prop("sizing"); - if (sizing == nullptr || sizing->kind != ExprKind::Literal) { - return; - } - checkOverlaySizing(node, sizing); - checkPercentSizing(node, sizing); - std::optional width; - std::optional height; - ValueRecord const* const record = sizing->literal.asRecord(); - if (record != nullptr && (record->contains("width") || record->contains("height"))) { - for (auto const& [dimension, value] : *record) { - if (dimension == "width") { - width = sizingDimension(value, sizing->path); - } else if (dimension == "height") { - height = sizingDimension(value, sizing->path); - } else { - refuse(sizing->path, "a `sizing` record has `width` and `height`; `" + dimension + "` is neither"); - } - } - } else { - width = sizingDimension(sizing->literal, sizing->path); - } - for (auto const& [fixed, axis] : {std::pair{width, std::size_t{0}}, std::pair{height, std::size_t{1}}}) { - auto const& minimum = bounds.at(2 * axis); - auto const& maximum = bounds.at((2 * axis) + 1); - if (fixed && (*fixed < minimum.value_or(*fixed) || *fixed > maximum.value_or(*fixed))) { - refuse(sizing->path, std::string{"a fixed size has no room to bound: the "} + - (axis == 0 ? "width" : "height") + " is fixed outside its bounds"); - } - } - } - - // A text's or a table column's literal `role` is one of the roles (`title` is `heading`'s alias); a computed one - // is read at mount, and one of no known name is reported there. - static void checkTextRole(DocNode const& node) { - ExprPtr const role = node.prop("role"); - if (role == nullptr || role->kind != ExprKind::Literal) { - return; - } - static constexpr std::array kRoles = { - "normal", "muted", "heading", "title", "section", "error", "success", - "mono", "display", "small", "overline", "caption", "label", "headline"}; - std::string const* const name = role->literal.asString(); - if (name == nullptr) { - refuse(pointerAppend(node.path, "role"), "`role` is a name"); - } - if (!listed(kRoles, *name)) { - refuse(pointerAppend(node.path, "role"), "`" + *name + "` is not one of the values of `role`"); - } - } - - // A dialog's, drawer's or form's error policy, submit mode and description spans. - static void checkSurfaceValues(DocNode const& node) { - if (node.kind != "dialog" && node.kind != "drawer" && node.kind != "form") { - return; - } - static constexpr std::array kPolicies = {"touched", "submit", "always"}; - checkChoice(node, "showErrors", kPolicies); - // Absent keeps the schema's own mode, so a misspelt mode would silently do the same. - static constexpr std::array kSubmitModes = {"explicit", "auto"}; - checkChoice(node, "submit", kSubmitModes); - checkSpans(node.prop("descriptionSpans")); - } - - // A text's role and spans; a text carries no description, the line itself is the text. - static void checkText(DocNode const& node) { - checkTextRole(node); - static constexpr std::array kTextAligns = {"start", "center", "end"}; - checkChoice(node, "align", kTextAligns); - checkSpans(node.prop("spans")); - if (node.prop("description") != nullptr) { - refuse(pointerAppend(node.path, "description"), "a text is not described; put the line in the text"); - } - if (node.prop("labelHint") != nullptr) { - refuse(pointerAppend(node.path, "labelHint"), "a text has no caption to hint after; put it in the text"); - } - } - - // A banner's action: its style is one of three; the link style places the action in the message's runs, and a - // stretched action is a button on a line of its own, so it needs an action and is no link. - static void checkBanner(DocNode const& node) { - static constexpr std::array kStyles = {"ghost", "button", "link"}; - checkChoice(node, "actionStyle", kStyles); - bool const link = node.name("actionStyle") == "link"; - checkSpans(node.prop("spans"), link); - if (node.flag("actionStretch")) { - if (link) { - refuse(pointerAppend(node.path, "actionStretch"), - "`actionStretch` puts a button on a line of its own; a `link` action sits in the message"); - } - if (!node.parts.contains("action")) { - refuse(pointerAppend(node.path, "actionStretch"), "`actionStretch` stretches the banner's `action`"); - } - } - } - - // What an `action` run is told where the loader refuses it. - static constexpr std::string_view kActionRunPlaces = - "an `action` run is the link of a banner whose `actionStyle` is " - "\"link\"; at most one run of its spans takes it"; - - // A span list written out: each literal run a string, each record run a `text` with at most the flags `strong` - // and `mono`, each literal flag a boolean. A computed list, or a computed element, is checked as it is drawn. A - // run may carry `action` where @p actionAllowed, once at most. - static void checkSpans(ExprPtr const& spans, bool actionAllowed = false) { - if (spans == nullptr) { - return; - } - int actions = 0; - if (spans->kind == ExprKind::Literal) { - ValueList const* const runs = spans->literal.asList(); - if (runs == nullptr) { - refuse(spans->path, "`spans` is a list of runs"); - } - for (Value const& run : *runs) { - checkLiteralRun(run, spans->path, actionAllowed, actions); - } - return; - } - if (spans->kind != ExprKind::List) { - return; - } - for (ExprPtr const& run : spans->args) { - if (run->kind == ExprKind::Literal) { - checkLiteralRun(run->literal, run->path, actionAllowed, actions); - } else if (run->kind == ExprKind::Object) { - checkRunRecord(*run, actionAllowed, actions); - } - } - } - - // A button's `children`: only on a list entry, and display kinds only, at any depth, so the entry stays one - // control with one activation. A list of what is allowed keeps a kind added later out until it is judged. - static void checkEntryContent(DocNode const& button) { - auto const found = button.children.find("children"); - if (found == button.children.end() || found->second.empty()) { - return; - } - if (button.name("style") != "item") { - refuse(pointerAppend(button.path, "children"), - "only a list entry holds content; a push button has a label"); - } - for (DocNodePtr const& child : found->second) { - checkReadOnlyContent(*child); - } - } - - // NOLINTNEXTLINE(misc-no-recursion): an entry's content is a tree of nodes. - static void checkReadOnlyContent(DocNode const& node) { - static constexpr std::array kDisplay = {"text", "badge", "keyValue", "progress", - "steps", "busy", "spacer", "column", - "row", "grid", "forEach", "switch"}; - static constexpr std::string_view kReason = - "an entry's content is read-only; put the control beside the entry"; - if (!listed(kDisplay, node.kind)) { - refuse(node.path, std::string{kReason}); - } - for (std::string_view const key : {std::string_view{"autofocus"}}) { - if (node.prop(key) != nullptr) { - refuse(pointerAppend(node.path, key), std::string{kReason}); - } - } - if (!node.keys.empty()) { - refuse(pointerAppend(node.path, "keys"), std::string{kReason}); - } - for (std::string_view const part : {std::string_view{"drag"}, std::string_view{"drop"}}) { - if (!node.partList(part).empty()) { - refuse(pointerAppend(node.path, part), std::string{kReason}); - } - } - for (auto const& [key, nodes] : node.children) { - for (DocNodePtr const& child : nodes) { - checkReadOnlyContent(*child); - } - } - for (auto const& [key, parts] : node.parts) { - for (DocNodePtr const& part : parts) { - for (auto const& [childKey, nodes] : part->children) { - for (DocNodePtr const& child : nodes) { - checkReadOnlyContent(*child); - } - } - } - } - } - - // A select's style written as a constant: one of the three it may be. A computed one is read as it is drawn. - static void checkSelectStyle(DocNode const& node) { - ExprPtr const style = node.prop("style"); - if (style == nullptr || style->kind != ExprKind::Literal) { - return; - } - static constexpr std::array kStyles = {"dropdown", "radio", "segmented"}; - std::string const* const name = style->literal.asString(); - if (name == nullptr) { - refuse(pointerAppend(node.path, "style"), "`style` is a name"); - } - if (!listed(kStyles, *name)) { - refuse(pointerAppend(node.path, "style"), "`" + *name + "` is not one of the values of `style`"); - } - } - - // A literal multiline text input with a unit or an icon: a text area holds no number and draws no icon. - static void checkMultilineExtras(DocNode const& node) { - ExprPtr const mode = node.prop("mode"); - std::string const* const name = - mode != nullptr && mode->kind == ExprKind::Literal ? mode->literal.asString() : nullptr; - if (name == nullptr || *name != "multiline") { - return; - } - for (std::string_view const key : {std::string_view{"unit"}, std::string_view{"icon"}, - std::string_view{"prefix"}, std::string_view{"decimals"}}) { - if (node.prop(key) != nullptr) { - refuse(pointerAppend(node.path, key), "a multiline input shows no " + std::string{key}); - } - } - if (!node.name("align").empty()) { - refuse(pointerAppend(node.path, "align"), "a multiline input's text starts at the leading edge"); - } - if (!node.name("emphasis").empty() && node.name("emphasis") != "normal") { - refuse(pointerAppend(node.path, "emphasis"), "a multiline input's size is its own; it takes no emphasis"); - } - } - - // The spans of each key-value item written as an `obj` in a `list`. - static void checkItemSpans(ExprPtr const& items) { - if (items == nullptr || items->kind != ExprKind::List) { - return; - } - for (ExprPtr const& item : items->args) { - if (item->kind != ExprKind::Object) { - continue; - } - for (auto const& [key, value] : item->fields) { - if (key == "spans") { - checkSpans(value); - } - } - } - } - - // A literal run's tone: one of the tone names, or null for none. - static void checkLiteralRunTone(Value const& tone, std::string const& path) { - std::string const* const name = tone.asString(); - if (tone.isNull()) { - return; - } - if (name == nullptr || - (*name != "neutral" && *name != "info" && *name != "ok" && *name != "warn" && *name != "err")) { - refuse(path, "a run's `tone` is neutral, info, ok, warn or err"); - } - } - - // A run marked `action`: allowed in a link banner's spans, once. - static void checkActionRun(std::string const& path, bool actionAllowed, int& actions) { - if (!actionAllowed || ++actions > 1) { - refuse(path, std::string{kActionRunPlaces}); - } - } - - // A literal run: a string, or a record of a string `text` and boolean flags. - static void checkLiteralRun(Value const& run, std::string const& path, bool actionAllowed, int& actions) { - if (run.asString() != nullptr) { - return; - } - ValueRecord const* const record = run.asRecord(); - if (record == nullptr) { - refuse(path, "a run is a string or a record with `text`"); - } - if (!record->contains("text")) { - refuse(path, "a run's record gives its `text`"); - } - for (auto const& [key, value] : *record) { - if (key != "text" && key != "strong" && key != "mono" && key != "tone" && key != "action") { - refuse(path, "a run takes `text`, `strong`, `mono` and `tone`, not `" + key + "`"); - } - if (key == "tone") { - checkLiteralRunTone(value, path); - } else if (key != "text" && value.asBool() == nullptr) { - refuse(path, "a run's `" + key + "` is true or false"); - } - if (key == "action" && value.asBool() != nullptr && *value.asBool()) { - checkActionRun(path, actionAllowed, actions); - } - } - } - - // A run written as an `obj`: a `text`, and flags that are booleans when written as constants. - static void checkRunRecord(Expr const& run, bool actionAllowed, int& actions) { - bool hasText = false; - for (auto const& [key, value] : run.fields) { - if (key == "text") { - hasText = true; - } else if (key == "tone") { - if (value->kind == ExprKind::Literal) { - checkLiteralRunTone(value->literal, value->path); - } - } else if (key != "strong" && key != "mono" && key != "action") { - refuse(value->path, "a run takes `text`, `strong`, `mono` and `tone`, not `" + key + "`"); - } else if (value->kind == ExprKind::Literal && value->literal.asBool() == nullptr) { - refuse(value->path, "a run's `" + key + "` is true or false"); - } else if (key == "action" && value->kind == ExprKind::Literal && *value->literal.asBool()) { - checkActionRun(value->path, actionAllowed, actions); - } - } - if (!hasText) { - refuse(run.path, "a run's record gives its `text`"); - } - } - - // A table cell's place across its column and down its row: `stretch`, which a stack takes, is no place for a - // cell. - static constexpr std::array kCellPlaces = {"start", "center", "end"}; - - // A table column's closed sets: its default cell's text role, and its cells' places. - static void checkColumnPart(DocNode const& node) { - checkTextRole(node); - checkCellPlace(node, "align"); - checkCellPlace(node, "valign"); - } - - // Only a horizontal `forEach` wraps and only a vertical one is divided; a literal `axis` that says otherwise is - // refused here, and a computed one is read when the screen lowers. - static void checkForEachWrap(DocNode const& node) { - ExprPtr const axis = node.prop("axis"); - if (axis == nullptr || axis->kind != ExprKind::Literal) { - return; - } - std::string const* const named = axis->literal.asString(); - bool const horizontal = named != nullptr && *named == "horizontal"; - if (node.flag("wrap") && !horizontal) { - refuse(pointerAppend(node.path, "wrap"), - "`wrap` fills lines along a row; this `forEach`'s `axis` is not \"horizontal\""); - } - if (node.flag("divided") && horizontal) { - refuse(pointerAppend(node.path, "divided"), - "`divided` draws rules between rows of a column; this `forEach`'s `axis` is \"horizontal\""); - } - } - - // An action bar's gap is the theme's, and a horizontal `forEach` directly in it is part of that row. - static void checkActionBar(DocNode const& node) { - if (node.prop("gap") != nullptr) { - refuse(pointerAppend(node.path, "gap"), kActionBarGapRefusal); - } - // A horizontal `forEach` directly in the bar is part of its row of actions, so it takes the same gap. - for (DocNodePtr const& child : node.nodes("children")) { - if (child->kind != "forEach" || child->prop("gap") == nullptr) { - continue; - } - ExprPtr const axis = child->prop("axis"); - if (axis != nullptr && axis->kind == ExprKind::Literal) { - std::string const* const named = axis->literal.asString(); - if (named != nullptr && *named == "horizontal") { - refuse(pointerAppend(child->path, "gap"), kActionBarGapRefusal); - } - } - } - } - - // A grid's `minColumnWidth`: a literal number of units that has columns to drop, and no tracks, which size their - // own columns. Where it could do nothing, it is refused rather than ignored. - static void checkMinColumnWidth(DocNode const& node) { - ExprPtr const least = node.prop("minColumnWidth"); - if (least == nullptr) { - return; - } - std::int64_t const* const units = - least->kind == ExprKind::Literal ? least->literal.asInt() : static_cast(nullptr); - if (units == nullptr) { - refuse(least->path, "`minColumnWidth` is a literal integer"); - } - if (*units < 1 || *units > 64) { - refuse(least->path, "`minColumnWidth` is 1 to 64 units"); - } - if (node.parts.contains("tracks")) { - refuse(least->path, "a grid with tracks sizes its own columns; `minColumnWidth` is for equal columns"); - } - ExprPtr const columns = node.prop("columns"); - if (columns == nullptr) { - refuse(least->path, - "`minColumnWidth` needs `columns`: it drops columns from that count as the grid narrows"); - } - if (columns->kind == ExprKind::Literal) { - std::int64_t const* const count = columns->literal.asInt(); - if (count != nullptr && *count <= 1) { - refuse(least->path, "`minColumnWidth` has nothing to drop from one column"); - } - } - } - - static void checkGrid(DocNode const& node) { - if (!node.name("justify").empty()) { - refuse(pointerAppend(node.path, "justify"), - "a grid's columns are sized by their count or tracks; there is no spare length to justify"); - } - if (node.prop("selected") != nullptr) { - refuse(pointerAppend(node.path, "selected"), - "a grid is not an entry of a list; `selected` marks a column or a row"); - } - checkMinColumnWidth(node); - auto const tracks = node.parts.find("tracks"); - if (tracks == node.parts.end()) { - return; - } - if (node.prop("columns") != nullptr) { - refuse(pointerAppend(node.path, "tracks"), - "a grid takes `columns` or `tracks`, not both; with `tracks`, the column count is their number"); - } - if (tracks->second.empty()) { - refuse(pointerAppend(node.path, "tracks"), "`tracks` lists at least one track"); - } - } - - // A menu's style, and its trigger's keys, which only a button-style menu has. An icon-only trigger needs a name - // for assistive technology, so a button-style menu has a `label` or an `a11y` name. - static void checkMenu(DocNode const& node) { - static constexpr std::array kStyles = {"bar", "button"}; - checkChoice(node, "style", kStyles); - static constexpr std::array kEmphasis = {"normal", "primary", "danger", "ghost"}; - checkChoice(node, "emphasis", kEmphasis); - if (node.name("style") != "button") { - for (std::string_view const key : {"label", "icon"}) { - if (node.prop(key) != nullptr) { - refuse( - pointerAppend(node.path, key), - "`" + std::string{key} + "` is a button-style menu's trigger; give the menu `style: button`"); - } - } - if (!node.name("emphasis").empty()) { - refuse(pointerAppend(node.path, "emphasis"), - "`emphasis` is a button-style menu's trigger; give the menu `style: button`"); - } - return; - } - auto const a11y = node.partList("a11y"); - bool const named = !a11y.empty() && a11y.front()->prop("name") != nullptr; - if (node.prop("label") == nullptr && !named) { - refuse(node.path, - "a button-style menu has a `label` or an `a11y` name, so its trigger has a name for " - "assistive technology"); - } - } - - // A separator is a line between entries: `true`, and nothing else beside it. - // Whether a part kind is a menu entry: a `menu` node's or a screen head's. - [[nodiscard]] static bool isMenuEntry(std::string_view kind) { - return kind == "menuItem" || kind == "headMenuItem"; - } - - static void checkMenuItem(DocNode const& node) { - if (!node.flags.contains("separator")) { - return; - } - if (!node.flag("separator")) { - refuse(pointerAppend(node.path, "separator"), "`separator` is `true`; leave it out for an entry"); - } - bool const alone = node.props.empty() && node.events.empty() && node.parts.empty() && node.names.empty() && - node.keys.empty() && node.flags.size() == 1; - if (!alone) { - refuse(node.path, "a separator is a line between entries and takes no other key"); - } - } - - // A cell place, which names the three it may be. - static void checkCellPlace(DocNode const& node, std::string_view key) { - std::string_view const value = node.name(key); - if (!value.empty() && !listed(kCellPlaces, value)) { - refuse(pointerAppend(node.path, key), "`" + std::string{value} + "` is not one of the values of `" + - std::string{key} + "`: start, center or end"); - } - } - - // A form's `columns`: a literal integer, 1 to 12, the `x-colspan` convention's full row. - static void checkFormColumns(DocNode const& node) { - ExprPtr const columns = node.prop("columns"); - if (columns == nullptr) { - return; - } - std::int64_t const* const count = - columns->kind == ExprKind::Literal ? columns->literal.asInt() : static_cast(nullptr); - if (count == nullptr) { - refuse(columns->path, "`columns` is a literal integer"); - } - if (*count < 1 || *count > 12) { - refuse(columns->path, "`columns` is 1 to 12; a form lays its fields in at least one column"); - } - } - - // A `captionWidth`: a literal integer, 1 to 64, which needs a caption column, so inline captions. - static void checkCaptionWidth(DocNode const& node, bool inlineCaptions) { - ExprPtr const width = node.prop("captionWidth"); - if (width == nullptr) { - return; - } - std::int64_t const* const units = - width->kind == ExprKind::Literal ? width->literal.asInt() : static_cast(nullptr); - if (units == nullptr) { - refuse(width->path, "`captionWidth` is a literal integer"); - } - if (*units < 1 || *units > 64) { - refuse(width->path, "`captionWidth` is 1 to 64 units"); - } - if (!inlineCaptions) { - refuse(width->path, "`captionWidth` needs inline captions"); - } - } - - static void checkChoice(DocNode const& node, std::string_view key, std::span choices) { - std::string_view const value = node.name(key); - if (!value.empty() && !listed(choices, value)) { - refuse(pointerAppend(node.path, key), - "`" + std::string{value} + "` is not one of the values of `" + std::string{key} + "`"); - } - } - - void checkCommands(Commands const& commands, CheckContext const& context, bool sequence = false) { - CheckContext current = context; - current.commands = true; - for (Command const& cmd : commands) { - checkCommand(cmd, current); - if (sequence && cmd.kind == CommandKind::Run && !cmd.binding.empty() && !cmd.extra) { - current.bindings.emplace_back(cmd.binding, Type::any()); - } - } - } - - // NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per command of ui/1. - void checkCommand(Command const& cmd, CheckContext const& context) { - std::string const where = cmd.path; - switch (cmd.kind) { - case CommandKind::Set: - checkSet(cmd, context); - break; - case CommandKind::Reset: { - NameEntry const& entry = require(context, cmd.target, where, - {NameCategory::State, NameCategory::Element}, "state or a dialog"); - if (entry.category == NameCategory::Element && entry.element->kind != "dialog" && - entry.element->kind != "drawer") { - refuse(where, "`reset` restores state, or the state of a dialog; `" + cmd.target + "` is a " + - entry.element->kind); - } - break; - } - case CommandKind::Run: { - static_cast(require(context, cmd.target, where, {NameCategory::Mutation}, "a mutation")); - CheckContext body = context; - if (cmd.extra) { - checkExpr(*cmd.extra, context); - if (!cmd.binding.empty()) { - body.bindings.emplace_back(cmd.binding, Type::any()); - } - } - if (cmd.value) { - checkExpr(*cmd.value, body); - } - break; - } - case CommandKind::Refetch: - static_cast(require(context, cmd.target, where, {NameCategory::Query}, "a query")); - break; - case CommandKind::Open: - case CommandKind::Close: - if (cmd.kind == CommandKind::Close && cmd.target == "self") { - break; - } - checkDialog(cmd, context); - break; - case CommandKind::Focus: - checkFocus(cmd, context); - break; - case CommandKind::ResetPrefs: - if (cmd.target != "all" && !_doc->customize.contains(cmd.target)) { - refuse(where, "`" + cmd.target + "` is not a customization point of this document"); - } - break; - case CommandKind::If: - checkCondition(*cmd.value, context, "the condition of `if`"); - checkCommands(cmd.commands, context); - checkCommands(cmd.alternative, context); - break; - case CommandKind::Seq: - checkCommands(cmd.commands, context, true); - break; - case CommandKind::All: - case CommandKind::Navigate: - if (cmd.value) { - checkExpr(*cmd.value, context); - } - if (cmd.extra) { - checkExpr(*cmd.extra, context); - } - checkCommands(cmd.commands, context); - checkCommands(cmd.alternative, context); - break; - case CommandKind::CancelClose: - if (!context.onClose) { - refuse(where, "`cancelClose` is valid only in `onClose`"); - } - break; - case CommandKind::Retry: - if (!context.boundaryError) { - refuse(where, "`retry` is valid only inside a boundary's `error`"); - } - break; - case CommandKind::SignIn: - static_cast(require(context, cmd.target, where, {NameCategory::Mutation}, "a mutation")); - break; - case CommandKind::Upload: - static_cast(require(context, cmd.target, where, {NameCategory::Mutation}, "a mutation")); - checkExpr(*cmd.value, context); - break; - case CommandKind::Download: - checkExpr(*cmd.value, context); - if (cmd.extra) { - checkExpr(*cmd.extra, context); - } - if (cmd.mediaType) { - checkExpr(*cmd.mediaType, context); - } - if (cmd.option == "preview") { - static_cast(require(context, cmd.target, where, {NameCategory::State}, "state")); - } - break; - case CommandKind::Return: - case CommandKind::Host: - case CommandKind::Notify: - case CommandKind::SwitchBackend: - case CommandKind::SetLocale: - case CommandKind::SetContext: - case CommandKind::SignOut: - default: - if (cmd.value) { - checkExpr(*cmd.value, context); - } - break; - } - } - - static void checkDialog(Command const& cmd, CheckContext const& context) { - NameEntry const& entry = require(context, cmd.target, cmd.path, {NameCategory::Element}, "a dialog"); - if (entry.element->kind != "dialog" && entry.element->kind != "drawer") { - refuse(cmd.path, "`" + cmd.target + "` is a " + entry.element->kind + ", not a dialog or drawer"); - } - } - - void checkSet(Command const& cmd, CheckContext const& context) { - auto const segments = splitPath(cmd.target); - std::string const& head = segments->front(); - Type const value = checkExpr(*cmd.value, context); - if (head == "app") { - return; - } - NameEntry& entry = - require(context, head, cmd.path, {NameCategory::State, NameCategory::Element}, "state or an input"); - if (entry.category == NameCategory::Element) { - KindSpec const* const spec = findKind(entry.element->kind, false); - if ((spec->flags & kWritable) == 0) { - // A table's state is the document's: it binds its `selection`, `sort` or `page` to state, and the - // state is set. - std::string const hint = entry.element->kind == "table" - ? ": bind its `selection`, `sort` or `page` to state and set that" - : ""; - refuse(cmd.path, - "`set` writes state or an input's draft; `" + head + "` is a " + entry.element->kind + hint); - } - return; - } - auto const type = derivedType(entry, head); - if (type && segments->size() == 1 && !compatible(*type, value)) { - refuse(cmd.value->path, "`" + head + "` is " + type->name() + "; the value is " + value.name()); - } - } - - /// The state and elements an expression reads, through the `let` entries it reads. - void reads(Expr const& expr, ScopeInfo* scope, std::set& out, std::vector& locals, - std::set& seenLets) { - if (expr.kind == ExprKind::Ref && std::ranges::find(locals, expr.name) == locals.end()) { - NameEntry const* const entry = lookup(scope, expr.name); - if (entry != nullptr && - (entry->category == NameCategory::State || entry->category == NameCategory::Element)) { - out.insert(entry); - } else if (entry != nullptr && entry->category == NameCategory::Let && seenLets.insert(entry).second) { - std::vector inner; - reads(*entry->derivedFrom, entry->scope, out, inner, seenLets); - } - } - bool const binds = bindsElement(expr.kind); - for (std::size_t index = 0; index < expr.args.size(); ++index) { - if (binds && index == 1) { - locals.push_back(expr.name); - } - reads(*expr.args.at(index), scope, out, locals, seenLets); - if (binds && index == 1) { - locals.pop_back(); - } - } - for (auto const& [name, field] : expr.fields) { - static_cast(name); - reads(*field, scope, out, locals, seenLets); - } - } - - /// The state and elements a command list writes. - static void writes(Commands const& commands, ScopeInfo* scope, std::set& out) { - for (Command const& cmd : commands) { - if (cmd.kind == CommandKind::Set || cmd.kind == CommandKind::Reset) { - auto const segments = splitPath(cmd.target); - NameEntry const* const entry = lookup(scope, segments->front()); - if (entry != nullptr) { - out.insert(entry); - } - } - writes(cmd.commands, scope, out); - writes(cmd.alternative, scope, out); - } - } - - void checkWatchGraph() { - std::size_t const count = _watches.size(); - std::vector> observed(count); - std::vector> written(count); - for (std::size_t index = 0; index < count; ++index) { - auto const& [watch, scope] = _watches.at(index); - std::vector locals; - std::set seenLets; - reads(*watch->on, scope, observed.at(index), locals, seenLets); - writes(watch->body, scope, written.at(index)); - } - // 0 unvisited, 1 on the current path, 2 finished. - std::vector state(count, 0); - std::vector trail; - std::function visit = [&](std::size_t from) { - state.at(from) = 1; - trail.push_back(from); - for (std::size_t to = 0; to < count; ++to) { - bool edge = false; - for (NameEntry const* entry : written.at(from)) { - edge = edge || observed.at(to).contains(entry); - } - if (!edge) { - continue; - } - if (state.at(to) == 1) { - std::string cycle; - auto const start = std::ranges::find(trail, to); - for (auto step = start; step != trail.end(); ++step) { - cycle += _watches.at(*step).first->path + " → "; - } - refuse(_watches.at(to).first->path, - "the watch graph has a cycle: " + cycle + _watches.at(to).first->path); - } - if (state.at(to) == 0) { - visit(to); - } - } - trail.pop_back(); - state.at(from) = 2; - }; - for (std::size_t index = 0; index < count; ++index) { - if (state.at(index) == 0) { - visit(index); - } - } - } - - // The effect checks below read only what the catalog says about each action. They warn only where the - // effects certainly cover, or certainly miss, what the document declares, because a warning a document cannot - // act on would teach its author to ignore the rest. - - /// The effects as a phrase, such as "`changes T_Row`, `none`". - [[nodiscard]] static std::string describeEffects(std::vector const& effects) { - std::string out; - for (ActionEffect const& effect : effects) { - out += (out.empty() ? "`" : ", `") + effect.kind + (effect.record ? " " + *effect.record : "") + "`"; - } - return out; - } - - /// Whether an action's effects change anything; `none` alone does not. - [[nodiscard]] static bool changesData(ActionInfo const& info) { - return info.effects && - std::ranges::any_of(*info.effects, [](ActionEffect const& effect) { return effect.kind != "none"; }); - } - - void warn(LoadWarningKind kind, std::string path, std::string text) { - _warnings.push_back(LoadWarning{.kind = kind, .path = std::move(path), .text = std::move(text)}); - } - - void checkEffects() { - if (!_options->catalog.action) { - return; - } - for (auto const& entry : _mutations) { - checkMutationEffects(*entry.first); - } - for (auto const& [watch, scope] : _watches) { - checkWatchFeedback(*watch, scope); - } - } - - void checkMutationEffects(MutationDecl const& mutation) { - auto const action = _options->catalog.action(mutation.action); - if (!action) { - return; - } - if (!action->effects && !refetches(mutation.onSuccess)) { - warn(LoadWarningKind::Uncovered, mutation.path, - std::format("nothing refreshes after `{}` succeeds: `{}` declares no effects, and no `refetch` " - "follows it; declare what it changes, or `effects::none` when it changes nothing", - mutation.name, mutation.action)); - } - } - - /// Whether a command list refetches a query, which is a refresh the document declares itself. - [[nodiscard]] static bool refetches(Commands const& commands) { - return std::ranges::any_of(commands, [](Command const& cmd) { - return cmd.kind == CommandKind::Refetch || refetches(cmd.commands) || refetches(cmd.alternative); - }); - } - - // Another client's change refetches the watched query, the watch runs the mutation, and its change reaches the - // other client, which may do the same. Only `"source": "user"` keeps a refetch from running the watch. - void checkWatchFeedback(WatchDecl const& watch, ScopeInfo* scope) { - if (watch.source == WatchSource::User) { - return; - } - std::vector locals; - std::set seenLets; - auto const query = readQuery(*watch.on, scope, locals, seenLets); - if (!query) { - return; - } - if (auto const mutation = runsWriter(watch.body, scope)) { - warn(LoadWarningKind::WatchFeedback, watch.path, - std::format("the watch reads the query `{}` and runs `{}`, which changes data: another client's " - "change refetches the query and runs it again; give the watch \"source\": \"user\"", - *query, *mutation)); - } - } - - /// The first query whose value an expression reads, directly or through a `let`. - [[nodiscard]] static std::optional readQuery(Expr const& expr, ScopeInfo* scope, - std::vector& locals, - std::set& seenLets) { - if (expr.kind == ExprKind::Query) { - return expr.name; - } - if (expr.kind == ExprKind::Ref && std::ranges::find(locals, expr.name) == locals.end()) { - NameEntry const* const entry = lookup(scope, expr.name); - if (entry != nullptr && entry->category == NameCategory::Query) { - return expr.name; - } - if (entry != nullptr && entry->category == NameCategory::Let && seenLets.insert(entry).second) { - std::vector inner; - if (auto found = readQuery(*entry->derivedFrom, entry->scope, inner, seenLets)) { - return found; - } - } - } - bool const binds = bindsElement(expr.kind); - for (std::size_t index = 0; index < expr.args.size(); ++index) { - if (binds && index == 1) { - locals.push_back(expr.name); - } - auto found = readQuery(*expr.args.at(index), scope, locals, seenLets); - if (binds && index == 1) { - locals.pop_back(); - } - if (found) { - return found; - } - } - for (auto const& [name, field] : expr.fields) { - static_cast(name); - if (auto found = readQuery(*field, scope, locals, seenLets)) { - return found; - } - } - return std::nullopt; - } - - /// The first mutation a command list runs whose action changes data. - [[nodiscard]] std::optional runsWriter(Commands const& commands, ScopeInfo* scope) const { - for (Command const& cmd : commands) { - bool const runs = - cmd.kind == CommandKind::Run || cmd.kind == CommandKind::Upload || cmd.kind == CommandKind::SignIn; - NameEntry const* const entry = runs ? lookup(scope, cmd.target) : nullptr; - if (entry != nullptr && entry->mutation != nullptr) { - auto const action = _options->catalog.action(entry->mutation->action); - if (action && changesData(*action)) { - return cmd.target; - } - } - if (auto found = runsWriter(cmd.commands, scope)) { - return found; - } - if (auto found = runsWriter(cmd.alternative, scope)) { - return found; - } - } - return std::nullopt; - } - - Document const* _doc; - LoadOptions const* _options; - std::deque _scopes; - std::map _scopeOf; - std::map _innerOf; - std::map> _queries; - std::map> _elements; - std::vector> _watches; - std::vector> _mutations; - std::vector> _queryScopes; - std::vector _warnings; - std::map _dateValueKinds; - std::map> _focusTargets; - std::vector _deriving; - // NOLINTEND(misc-no-recursion) -}; - -// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of name. -inline std::expected ScopeResolver::ref(std::string_view head, - std::span path) const { - for (auto const& [name, type] : std::views::reverse(_context.bindings)) { - if (name == head) { - return typeAlong(type, head, path); - } - } - if (head == "event") { - if (!_context.commands) { - return std::unexpected(std::string{"`event` is read only inside a command list"}); - } - return Type::any(); - } - if (head == "app") { - return Type::any(); - } - if (head == "boundary") { - if (!_context.boundaryError || path.size() != 1 || path.front() != "error") { - return std::unexpected(std::string{"`boundary.error` is read only inside a boundary's `error`"}); - } - return Type::of(TypeKind::String, true); - } - NameEntry* const entry = DocumentValidator::lookup(_context.scope, head); - if (entry == nullptr) { - return std::unexpected("`" + std::string{head} + "` does not resolve in this scope"); - } - switch (entry->category) { - case NameCategory::Param: - return typeAlong(entry->type, head, path); - case NameCategory::State: - case NameCategory::Let: { - auto type = _validator.derivedType(*entry, head); - if (!type) { - return type; - } - return typeAlong(*type, head, path); - } - case NameCategory::Query: - return Type::any(); - case NameCategory::Mutation: - return std::unexpected("`" + std::string{head} + - "` is a mutation; read it with `result`, `pending` or " - "`error`"); - case NameCategory::Model: - return std::unexpected("`" + std::string{head} + "` is a model alias, not a value"); - case NameCategory::Transfer: - if (path.empty() || !listed(kTransferValues, path.front())) { - return std::unexpected("the transfer `" + std::string{head} + - "` is read as `progress`, `pending` or `error`"); - } - return Type::any(); - case NameCategory::Element: - default: { - KindSpec const* const spec = findKind(entry->element->kind, false); - if (path.empty()) { - return std::unexpected("the element `" + std::string{head} + - "` is read through one of its values, " - "such as `" + - std::string{head} + ".visible`"); - } - std::string const& value = path.front(); - bool const open = (spec->flags & kOpenValues) != 0; - bool const known = listed(kAnyValues, value) || listed(spec->values, value) || open; - if (!known) { - return std::unexpected("the " + entry->element->kind + " `" + std::string{head} + "` has no value `" + - value + "`"); - } - bool const field = open && !listed(kAnyValues, value) && !listed(spec->values, value); - Type const type = field ? Type::any() : elementValueType(value); - return typeAlong(type, value, path.subspan(1)); - } - } -} - -inline std::expected ScopeResolver::row(std::span path) const { - static_cast(path); - for (ScopeInfo const* scope = _context.scope; scope != nullptr; scope = scope->parent) { - if (scope->row) { - return Type::any(); - } - } - return std::unexpected(std::string{"`row` is read only inside a forEach or table row"}); -} - -inline std::expected ScopeResolver::control(ExprKind form, std::string_view name) const { - if (form == ExprKind::Can && (name.starts_with("host:") || name == "context")) { - return Type::of(TypeKind::Bool); - } - NameEntry const* const entry = DocumentValidator::lookup(_context.scope, name); - bool const query = entry != nullptr && entry->category == NameCategory::Query; - bool const mutation = entry != nullptr && entry->category == NameCategory::Mutation; - if (form == ExprKind::Query && !query) { - return std::unexpected("`" + std::string{name} + "` is not a query of this scope"); - } - if (form == ExprKind::Result && !mutation) { - return std::unexpected("`" + std::string{name} + "` is not a mutation of this scope"); - } - if (!query && !mutation) { - return std::unexpected("`" + std::string{name} + "` is not a query or mutation of this scope"); - } - if (form == ExprKind::Pending || form == ExprKind::Can) { - return Type::of(TypeKind::Bool); - } - if (form == ExprKind::Error || form == ExprKind::ErrorKind) { - return Type::of(TypeKind::String, true); - } - return Type::any(); -} - -inline std::expected ScopeResolver::pref(std::string_view point, - std::span path) const { - auto const& points = _validator.document().customize; - auto const found = points.find(point); - if (found == points.end()) { - return std::unexpected("`" + std::string{point} + "` is not a customization point of this document"); - } - return typeAlong(found->second.type, point, path); -} - -} // namespace detail - -/// @brief Parses a UI document and runs its load-time validation (spec 5 §3). -/// -/// A document is refused when it does not parse, when a reference does not resolve, when a type does not check, -/// when the `let` or `watch` graph has a cycle, when an expression exceeds 256 nodes, when a node kind, command or -/// function is not in the vocabulary, when a document declares `invalidates`, `patch` or `refreshOn`, when a -/// must-understand key is unknown, or when a rule of spec 5 or spec 6 fails; the list is in -/// `docs/spec/ui/document.md`. The rules that need catalog facts run when @p options supplies them. -/// @param json The document's JSON. -/// @param options The catalog facts. -/// @return The document, with what validation found that does not refuse it in `Document::warnings`, or the first -/// refusal, naming the document id, the JSON Pointer and the reason. -[[nodiscard]] inline std::expected loadDocument(Json const& json, LoadOptions const& options = {}) { - std::string documentId; - if (auto const* const object = std::get_if(&json.data)) { - auto const* const found = object->find("id"); - if (found != object->end()) { - if (auto const* const text = std::get_if(&found->second.data)) { - documentId = *text; - } - } - } - try { - Document doc = detail::DocumentParser{}.parse(json); - detail::DocumentValidator validator{doc, options}; - validator.run(); - doc.warnings = validator.takeWarnings(); - doc.dateValueKinds = validator.takeDateValueKinds(); - doc.focusTargets = validator.takeFocusTargets(); - return doc; - } catch (detail::DocumentRefused const& refused) { - Refusal refusal = refused.refusal(); - refusal.document = documentId; - return std::unexpected(std::move(refusal)); - } -} - -/// @brief Parses JSON text as a UI document and runs its load-time validation. -/// @param text The document's JSON text. -/// @param options The catalog facts. -/// @return The document, or the refusal; text that is not JSON is refused at the root. -[[nodiscard]] inline std::expected loadDocumentText(std::string_view text, - LoadOptions const& options = {}) { - auto json = parseJson(text); - if (!json) { - return std::unexpected(Refusal{.document = {}, .path = "", .reason = std::move(json.error())}); - } - return loadDocument(*json, options); -} +/// @brief Parses JSON text as a UI document and runs its load-time validation. +/// @param text The document's JSON text. +/// @param options The catalog facts. +/// @return The document, or the refusal; text that is not JSON is refused at the root. +[[nodiscard]] MORPH_API std::expected loadDocumentText(std::string_view text, + LoadOptions const& options = {}); /// @brief The view node kinds of `ui/1`. /// @return Their `kind` spellings. -[[nodiscard]] inline std::vector nodeKinds() { - std::vector kinds; - for (detail::KindSpec const& spec : detail::kKinds) { - if ((spec.flags & detail::kPart) == 0) { - kinds.push_back(spec.kind); - } - } - return kinds; -} +[[nodiscard]] MORPH_API std::vector nodeKinds(); } // namespace morph::ui diff --git a/scripts/branch_partial_allowlist.json b/scripts/branch_partial_allowlist.json index bd28ec81b..39a1dc737 100644 --- a/scripts/branch_partial_allowlist.json +++ b/scripts/branch_partial_allowlist.json @@ -120,29 +120,29 @@ "reason": "Unreachable except via the adjacent `Error` case it deliberately shares a body with (net audit, `socket_backend.hpp` extra finding #7). `detail::ExecuteReplyKind` is a closed 3-value enum (`Value`/`Timeout`/`Error`), all three handled explicitly above this label; `default:` exists only to satisfy this project's `-Wswitch-default`, per the source's own inline comment directly below this line. Reaching it via any value other than through the `Error` case falling through would require an out-of-range `static_cast` producing a value outside the enum's domain -- undefined behavior, not a legitimate test target." }, { - "file": "include/morph/ui/document.hpp", - "line": 2281, + "file": "src/ui/document.cpp", + "line": 1538, "source": "default:", "context": "download(cmd, fields, primary, path);", "reason": "The default arm is unreachable: the switch names every enumerator of CommandKind, so no value reaches `default`. The project's strict warnings require both at once -- -Wswitch-enum wants every enumerator listed and -Wswitch-default wants a default label -- so the default shares the last enumerator's body and is never the label taken. It is DocumentParser::command's switch over the command kinds." }, { - "file": "include/morph/ui/document.hpp", - "line": 2654, + "file": "src/ui/document.cpp", + "line": 1913, "source": "default:", "context": "case Shape::Keys:", "reason": "The default arm is unreachable: the switch names every enumerator of detail::Shape, so no value reaches `default`. The project's strict warnings require both at once -- -Wswitch-enum wants every enumerator listed and -Wswitch-default wants a default label -- so the default shares the last enumerator's body and is never the label taken. It is DocumentParser::entry's switch over a key's shape." }, { - "file": "include/morph/ui/document.hpp", - "line": 5175, + "file": "src/ui/document.cpp", + "line": 4453, "source": "default:", "context": "if (cmd.value) {", "reason": "The default arm is unreachable: the switch names every enumerator of CommandKind, so no value reaches `default`. The project's strict warnings require both at once -- -Wswitch-enum wants every enumerator listed and -Wswitch-default wants a default label -- so the default shares the last enumerator's body and is never the label taken. It is DocumentValidator::checkCommand's switch." }, { - "file": "include/morph/ui/document.hpp", - "line": 5518, + "file": "src/ui/document.cpp", + "line": 4795, "source": "default: {", "reason": "The default arm is unreachable: the switch names every enumerator of NameCategory, so no value reaches `default`. The project's strict warnings require both at once -- -Wswitch-enum wants every enumerator listed and -Wswitch-default wants a default label -- so the default shares the last enumerator's body and is never the label taken. It is ScopeResolver::ref's switch over what a name declares." }, diff --git a/src/ui/document.cpp b/src/ui/document.cpp new file mode 100644 index 000000000..7711994af --- /dev/null +++ b/src/ui/document.cpp @@ -0,0 +1,4990 @@ +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace morph::ui { + +std::function(std::string_view)> documentLookup( + std::map> documents) { + return [known = std::make_shared> const>(std::move(documents))]( + std::string_view actionId) -> std::optional { + auto const found = known->find(actionId); + if (found == known->end()) { + return std::nullopt; + } + return found->second; + }; +} + +namespace detail { + +namespace { + +/// @brief The exception the loader throws inside itself; `loadDocument` turns it into its result. +class DocumentRefused : public std::runtime_error { +public: + /// @brief Wraps a refusal. + /// @param refusal The refusal. + explicit DocumentRefused(Refusal refusal) : std::runtime_error{refusal.reason}, _refusal{std::move(refusal)} {} + + /// @brief The refusal. + /// @return It. + [[nodiscard]] Refusal const& refusal() const noexcept { return _refusal; } + +private: + Refusal _refusal; +}; + +/// @brief Refuses the document. +/// @param path Where. +/// @param reason Why. +[[noreturn]] void refuse(std::string const& path, std::string reason) { + throw DocumentRefused{Refusal{.document = {}, .path = path, .reason = std::move(reason)}}; +} + +// NOLINTBEGIN(modernize-use-designated-initializers,readability-trailing-comma): the kind table reads as rows; names on every field would not. A trailing comma would put every row member on a line of its own. +/// @brief The keys every node takes. +constexpr std::array kCommonKeys = {{ + {"id", Shape::Name}, {"visible", Shape::Condition}, {"enabled", Shape::Condition}, + {"tooltip", Shape::Expr}, {"sizing", Shape::Expr}, {"minWidth", Shape::Expr}, + {"maxWidth", Shape::Expr}, {"minHeight", Shape::Expr}, {"maxHeight", Shape::Expr}, + {"alignSelf", Shape::Text}, {"bleed", Shape::Flag}, {"span", Shape::Expr}, + {"testId", Shape::Text}, {"surface", Shape::Expr}, {"autofocus", Shape::Expr}, + {"a11y", Shape::Part, "a11y"}, {"drag", Shape::Part, "drag"}, {"drop", Shape::Part, "drop"}, + {"keys", Shape::Keys}, +}}; + +/// @brief The input decorations text and the inputs take; a text refuses `description` and `labelHint`. +constexpr std::array kFieldKeys = {{ + {"readonly", Shape::Condition}, + {"required", Shape::Condition}, + {"errors", Shape::Expr}, + {"stale", Shape::Condition}, + {"description", Shape::Expr}, + {"labelHint", Shape::Expr}, + {"tone", Shape::Expr}, +}}; + +/// @brief The element values every element has. +constexpr std::array kAnyValues = {"visible", "enabled", "valid", "errors", "shownErrors"}; +/// @brief The element values of a text, date-time or slider input. +constexpr std::array kInputValues = {"value", "draft", "dirty", "focused", "touched"}; +/// @brief The element values of a checkbox. +constexpr std::array kCheckboxValues = {"checked"}; +/// @brief The element values of a select. +constexpr std::array kSelectValues = {"selected", "selectedOption"}; +/// @brief The element values of a tabs node: the id of the tab shown. +constexpr std::array kTabsValues = {"selected"}; +/// @brief The element values of a table. +constexpr std::array kTableValues = { + "selection", "activeKey", "sort", "filters", "viewCount", "sourceCount", "selectedCount", + "pending", "error", "hoveredKey", "page", "pageCount", "pageFirst", "pageLast"}; +/// @brief The element values of a dialog or drawer. +constexpr std::array kDialogValues = {"open", "ready", "submitted"}; +/// @brief The element values of a form, beside its fields. +constexpr std::array kFormValues = {"ready", "body", "submitted"}; +/// @brief The values of a transfer id. +constexpr std::array kTransferValues = {"progress", "pending", "error"}; + +/// @brief The keys of `text`. +constexpr std::array kTextKeys = { + {{"text", Shape::Expr}, {"spans", Shape::Expr}, {"role", Shape::Expr}, {"align", Shape::Text}}}; +/// @brief The keys of `button`. +constexpr std::array kButtonKeys = {{{"label", Shape::Expr}, + {"icon", Shape::Expr}, + {"emphasis", Shape::Text}, + {"style", Shape::Text}, + {"selected", Shape::Condition}, + {"onClick", Shape::Commands}, + {"onActivate", Shape::Commands}, + {"children", Shape::Nodes}, + {"shape", Shape::Text}, + {"size", Shape::Text}, + {"mono", Shape::Flag}, + {"weight", Shape::Text}}}; +/// @brief The keys of `textInput`. +constexpr std::array kTextInputKeys = {{{"value", Shape::Expr}, + {"placeholder", Shape::Expr}, + {"mode", Shape::Expr}, + {"icon", Shape::Expr}, + {"unit", Shape::Expr}, + {"decimals", Shape::Expr}, + {"prefix", Shape::Expr}, + {"emphasis", Shape::Text}, + {"mono", Shape::Flag}, + {"align", Shape::Text}, + {"commitOn", Shape::Text}, + {"label", Shape::Expr}, + {"showLabel", Shape::Flag}, + {"onChange", Shape::Commands}, + {"onCommit", Shape::Commands}, + {"onSubmit", Shape::Commands}}}; +/// @brief The keys of `checkbox`. +constexpr std::array kCheckboxKeys = { + {{"label", Shape::Expr}, {"checked", Shape::Expr}, {"onToggle", Shape::Commands}, {"onChange", Shape::Commands}}}; +/// @brief The keys of `select`. +constexpr std::array kSelectKeys = {{{"options", Shape::Expr}, + {"selected", Shape::Expr}, + {"style", Shape::Expr}, + {"label", Shape::Expr}, + {"showLabel", Shape::Flag}, + {"onStale", Shape::Text}, + {"onChoose", Shape::Commands}, + {"onChange", Shape::Commands}}}; +/// @brief The keys of `menu`; `label`, `icon` and `emphasis` are a button-style menu's trigger. +constexpr std::array kMenuKeys = {{{"items", Shape::Parts, "menuItem"}, + {"style", Shape::Text}, + {"label", Shape::Expr}, + {"icon", Shape::Expr}, + {"emphasis", Shape::Text}}}; +/// @brief The keys of a menu item part. +constexpr std::array kMenuItemKeys = {{{"label", Shape::Expr}, + {"icon", Shape::Expr}, + {"keys", Shape::Text}, + {"checked", Shape::Expr}, + {"enabled", Shape::Condition}, + {"onClick", Shape::Commands}, + {"items", Shape::Parts, "menuItem"}, + {"separator", Shape::Flag}, + {"description", Shape::Expr}, + {"visible", Shape::Condition}}}; +/// @brief The keys of a `headMenuItem` part: an entry of a screen head's own menu, a menu item with the `id` that +/// `ScreenHead::choose` takes; its submenu's entries are head menu items too. +constexpr std::array kHeadMenuItemKeys = {{{"id", Shape::Name}, + {"label", Shape::Expr}, + {"icon", Shape::Expr}, + {"keys", Shape::Text}, + {"checked", Shape::Expr}, + {"enabled", Shape::Condition}, + {"onClick", Shape::Commands}, + {"items", Shape::Parts, "headMenuItem"}, + {"separator", Shape::Flag}, + {"description", Shape::Expr}, + {"visible", Shape::Condition}}}; +/// @brief The keys of a `headTool` part: a search field or a select of a screen's head. +constexpr std::array kHeadToolKeys = {{{"id", Shape::Name, {}, kRequired}, + {"kind", Shape::Text, {}, kRequired}, + {"label", Shape::Expr, {}, kRequired}, + {"value", Shape::Expr}, + {"placeholder", Shape::Expr}, + {"onChange", Shape::Commands}, + {"onSubmit", Shape::Commands}, + {"options", Shape::Expr}, + {"selected", Shape::Expr}, + {"style", Shape::Text}, + {"onChoose", Shape::Commands}, + {"width", Shape::Expr}, + {"visible", Shape::Condition}, + {"enabled", Shape::Condition}}}; +/// @brief The keys of `column` and `row`; `wrap` is a row's, read on a column only to refuse it, and `divided` a +/// column's or a row's that does not wrap. +constexpr std::array kContainerKeys = {{{"children", Shape::Nodes}, + {"gap", Shape::Expr}, + {"padding", Shape::Expr}, + {"align", Shape::Text}, + {"justify", Shape::Text}, + {"wrap", Shape::Flag}, + {"divided", Shape::Flag}, + {"pageEdge", Shape::Flag}, + {"headJoined", Shape::Flag}, + {"selected", Shape::Condition}}}; +/// @brief The keys of `grid`; `justify` and `selected` are read only to refuse them. +constexpr std::array kGridKeys = {{{"children", Shape::Nodes}, + {"gap", Shape::Expr}, + {"columns", Shape::Expr}, + {"minColumnWidth", Shape::Expr}, + {"tracks", Shape::Parts, "track"}, + {"align", Shape::Text}, + {"justify", Shape::Text}, + {"selected", Shape::Condition}}}; +/// @brief The keys of a `grid` track part. +constexpr std::array kTrackKeys = {{{"width", Shape::Expr}, {"align", Shape::Text}}}; +/// @brief The keys of `panel`. +constexpr std::array kPanelKeys = {{{"title", Shape::Expr}, + {"gap", Shape::Expr}, + {"header", Shape::Nodes}, + {"padding", Shape::Expr}, + {"collapsible", Shape::Expr}, + {"collapsed", Shape::Expr}, + {"onToggle", Shape::Commands}, + {"children", Shape::Nodes}}}; +/// @brief The keys of `scroll`. +constexpr std::array kScrollKeys = {{{"axis", Shape::Expr}, {"children", Shape::Nodes}}}; +/// @brief The keys of `switch`. +constexpr std::array kSwitchKeys = { + {{"on", Shape::Expr, {}, kRequired}, {"cases", Shape::Parts, "case"}, {"default", Shape::Nodes}}}; +/// @brief The keys of a `switch` case part. +constexpr std::array kCaseKeys = { + {{"when", Shape::Expr, {}, kRequired}, {"children", Shape::Nodes, {}, kInner}}}; +/// @brief The keys of `tabs`. +constexpr std::array kTabsKeys = {{{"tabs", Shape::Parts, "tab"}, + {"selected", Shape::Expr}, + {"onChoose", Shape::Commands}, + {"moreLabel", Shape::Expr}, + {"inset", Shape::Expr}, + {"pageInset", Shape::Expr}, + {"stripSurface", Shape::Text}}}; +/// @brief The keys of a `tabs` page part. +constexpr std::array kTabKeys = { + {{"id", Shape::Name}, {"label", Shape::Expr}, {"children", Shape::Nodes}}}; +/// @brief The keys of `dialog` and `drawer`. +constexpr std::array kDialogKeys = {{{"open", Shape::Condition}, + {"gap", Shape::Expr}, + {"title", Shape::Expr}, + {"description", Shape::Expr}, + {"showErrors", Shape::Text}, + {"children", Shape::Nodes, {}, kInner}, + {"onDismiss", Shape::Commands}, + {"default", Shape::Commands, {}, kInner}, + {"cancel", Shape::Commands, {}, kInner}, + {"actions", Shape::Parts, "actionButton", kInner}, + {"side", Shape::Expr}, + {"sheet", Shape::Condition}, + {"dismissLabel", Shape::Expr}, + {"descriptionSpans", Shape::Expr}}}; +/// @brief The keys of `group`: a labelled set of inputs, lowered to a column of existing kinds. +constexpr std::array kGroupKeys = {{{"label", Shape::Expr}, + {"required", Shape::Condition}, + {"description", Shape::Expr}, + {"errors", Shape::Expr}, + {"gap", Shape::Expr}, + {"children", Shape::Nodes}}}; +/// @brief The keys of `busy`. +constexpr std::array kBusyKeys = {{{"active", Shape::Condition}, {"label", Shape::Expr}}}; +/// @brief The keys of `forEach`. +constexpr std::array kForEachKeys = {{{"rows", Shape::Expr, {}, kRequired}, + {"key", Shape::Expr, {}, kInner}, + {"axis", Shape::Expr}, + {"gap", Shape::Expr}, + {"wrap", Shape::Flag}, + {"divided", Shape::Flag}, + {"children", Shape::Nodes, {}, kInner}}}; +/// @brief The keys of `table`. +constexpr std::array kTableKeys = {{{"rows", Shape::Expr}, + {"key", Shape::Expr, {}, kInner}, + {"model", Shape::Name}, + {"action", Shape::Text}, + {"body", Shape::Expr}, + {"mode", Shape::Expr}, + {"columns", Shape::PartsOrExpr, "column"}, + {"showHeader", Shape::Flag}, + {"virtualizeThreshold", Shape::Expr}, + {"virtualizeOverscan", Shape::Expr}, + {"selectionMode", Shape::Expr}, + {"selection", Shape::Expr}, + {"onSelectionChange", Shape::Commands}, + {"selectColumn", Shape::Flag}, + {"selectAllLabel", Shape::Expr}, + {"rowLabel", Shape::Expr, {}, kInner}, + {"sort", Shape::Expr}, + {"onSortChange", Shape::Commands}, + {"pageSize", Shape::Expr}, + {"page", Shape::Expr}, + {"group", Shape::Part, "group"}, + {"filters", Shape::Expr}, + {"rowTone", Shape::Expr, {}, kInner}, + {"rowSpans", Shape::Expr, {}, kInner}, + {"highlightKey", Shape::Expr}, + {"onActivate", Shape::Commands, {}, kInner}, + {"valign", Shape::Text}, + {"empty", Shape::Nodes}}}; +/// @brief The keys of a `table` column part. +constexpr std::array kColumnKeys = {{{"id", Shape::Name}, + {"label", Shape::Expr}, + {"width", Shape::Expr}, + {"role", Shape::Expr}, + {"align", Shape::Text}, + {"valign", Shape::Text}, + {"sortable", Shape::Flag}, + {"wrap", Shape::Flag}, + {"shrink", Shape::Flag}, + {"sortBy", Shape::Expr, {}, kInner}, + {"cell", Shape::Nodes, {}, kInner}}}; +/// @brief The keys of a `table` group part: the value its rows are grouped by, and the heading drawn before each +/// group, both read in the row scope. +constexpr std::array kTableGroupKeys = { + {{"by", Shape::Expr, {}, kInner | kRequired}, {"heading", Shape::Nodes, {}, kInner | kRequired}}}; +/// @brief The keys of `dateTimeInput`. +constexpr std::array kDateTimeKeys = {{{"value", Shape::Expr}, + {"mode", Shape::Expr}, + {"label", Shape::Expr}, + {"showLabel", Shape::Flag}, + {"onChange", Shape::Commands}, + {"onCommit", Shape::Commands}}}; +/// @brief The keys of `slider`. +constexpr std::array kSliderKeys = {{{"value", Shape::Expr}, + {"min", Shape::Expr}, + {"max", Shape::Expr}, + {"step", Shape::Expr}, + {"label", Shape::Expr}, + {"onChange", Shape::Commands}, + {"onCommit", Shape::Commands}}}; +/// @brief The keys of `filePicker`. +constexpr std::array kFilePickerKeys = {{{"accept", Shape::Expr}, + {"multiple", Shape::Expr}, + {"mode", Shape::Expr}, + {"label", Shape::Expr}, + {"onPick", Shape::Commands}}}; +/// @brief The keys of `banner`. +constexpr std::array kBannerKeys = {{{"tone", Shape::Expr}, + {"text", Shape::Expr}, + {"spans", Shape::Expr}, + {"dismissible", Shape::Expr}, + {"action", Shape::Part, "action"}, + {"actionStyle", Shape::Text}, + {"actionStretch", Shape::Flag}, + {"onDismiss", Shape::Commands}}}; +/// @brief The keys of an `action` part. +constexpr std::array kActionKeys = {{{"label", Shape::Expr}, {"onClick", Shape::Commands}}}; +/// @brief The keys of an `actionButton` part: a button a screen's head or an overlay's footer shows. +constexpr std::array kActionButtonKeys = {{{"id", Shape::Name, {}, kRequired}, + {"label", Shape::Expr, {}, kRequired}, + {"icon", Shape::Expr}, + {"iconOnly", Shape::Condition}, + {"emphasis", Shape::Text}, + {"enabled", Shape::Condition}, + {"visible", Shape::Condition}, + {"onClick", Shape::Commands}}}; +/// @brief The keys of a `headBadge` part: a status badge of a screen's head. +constexpr std::array kHeadBadgeKeys = { + {{"tone", Shape::Expr}, {"text", Shape::Expr}, {"icon", Shape::Expr}, {"visible", Shape::Condition}}}; +/// @brief The keys of a `navigationBadge` part: a count the app document puts on a navigator entry. `screen` is the +/// screen id the entry opens, a literal; the rest are read in the app scope. +constexpr std::array kNavigationBadgeKeys = {{{"screen", Shape::Text, {}, kRequired}, + {"text", Shape::Expr}, + {"tone", Shape::Expr}, + {"visible", Shape::Condition}}}; +/// @brief The keys of `badge`. +constexpr std::array kBadgeKeys = {{{"tone", Shape::Expr}, + {"text", Shape::Expr}, + {"icon", Shape::Expr}, + {"style", Shape::Text}, + {"onRemove", Shape::Commands}, + {"removeLabel", Shape::Expr}, + {"shape", Shape::Text}, + {"mono", Shape::Flag}}}; +/// @brief The keys of `progress`. +constexpr std::array kProgressKeys = {{{"value", Shape::Expr}, {"label", Shape::Expr}}}; +/// @brief The keys of `steps`. +constexpr std::array kStepsKeys = { + {{"items", Shape::Expr}, {"current", Shape::Expr}, {"labelled", Shape::Condition}}}; +/// @brief The keys of `keyValue`. +constexpr std::array kKeyValueKeys = { + {{"items", Shape::Expr}, {"fieldLayout", Shape::Text}, {"captionWidth", Shape::Expr}}}; +/// @brief The keys of `emptyState`. +constexpr std::array kEmptyStateKeys = { + {{"title", Shape::Expr}, {"text", Shape::Expr}, {"icon", Shape::Expr}, {"action", Shape::Part, "action"}}}; +/// @brief The keys of `chart`. +constexpr std::array kChartKeys = {{{"summary", Shape::Expr, {}, kRequired}, + {"series", Shape::Parts, "series", kRequired}, + {"lines", Shape::Parts, "line"}, + {"yMin", Shape::Expr}, + {"yMax", Shape::Expr}, + {"yPlaces", Shape::Expr}, + {"yLabel", Shape::Expr}}}; +/// @brief The keys of a chart's `series` part. The keys read per point are evaluated in the part's row scope, with +/// `row` the point's element. +constexpr std::array kSeriesKeys = {{{"points", Shape::Expr, {}, kRequired}, + {"y", Shape::Expr, {}, kRequired | kInner}, + {"x", Shape::Expr, {}, kInner}, + {"xLabel", Shape::Expr, {}, kInner}, + {"tone", Shape::Expr, {}, kInner}, + {"note", Shape::Expr, {}, kInner}, + {"label", Shape::Expr}, + {"joined", Shape::Flag}, + {"style", Shape::Text}}}; +/// @brief The keys of a chart's reference `line` part. +constexpr std::array kLineKeys = { + {{"value", Shape::Expr, {}, kRequired}, {"label", Shape::Expr}, {"tone", Shape::Expr}, {"style", Shape::Text}}}; +/// @brief The keys of `splitter`. +constexpr std::array kSplitterKeys = { + {{"orientation", Shape::Expr}, {"sizes", Shape::Expr}, {"children", Shape::Nodes}}}; +/// @brief The keys of `collapsible`. +constexpr std::array kCollapsibleKeys = {{{"title", Shape::Expr}, + {"gap", Shape::Expr}, + {"open", Shape::Condition}, + {"header", Shape::Nodes}, + {"children", Shape::Nodes}, + {"onToggle", Shape::Commands}}}; +/// @brief The keys of `actionBar`; `gap` is read only to refuse it: its gap is the theme's. +constexpr std::array kActionBarKeys = {{{"children", Shape::Nodes}, + {"align", Shape::Text}, + {"justify", Shape::Text}, + {"gap", Shape::Expr}, + {"wrap", Shape::Flag}}}; +/// @brief The keys of `dropZone`. +constexpr std::array kDropZoneKeys = { + {{"accept", Shape::Expr}, {"multiple", Shape::Expr}, {"children", Shape::Nodes}, {"onDrop", Shape::Commands}}}; +/// @brief The keys of `page`: its sheet's size and margins as literal micrometres. +constexpr std::array kPageKeys = {{{"width", Shape::Expr, {}, kRequired}, + {"height", Shape::Expr, {}, kRequired}, + {"margins", Shape::Expr}, + {"children", Shape::Nodes}}}; +/// @brief The keys of `pageRegion`: its anchor and place as literal micrometres. +constexpr std::array kPageRegionKeys = {{{"anchor", Shape::Text, {}, kRequired}, + {"x", Shape::Expr}, + {"y", Shape::Expr}, + {"width", Shape::Expr}, + {"height", Shape::Expr}, + {"children", Shape::Nodes}}}; +/// @brief The keys of `localeScope`. +constexpr std::array kLocaleScopeKeys = { + {{"locale", Shape::Expr, {}, kRequired}, {"children", Shape::Nodes}}}; +/// @brief The keys of `customize`. +constexpr std::array kCustomizeKeys = {{{"point", Shape::Name, {}, kRequired}}}; +/// @brief The keys of `boundary`. +constexpr std::array kBoundaryKeys = { + {{"loading", Shape::Nodes}, {"error", Shape::Nodes, {}, kBoundaryError}, {"children", Shape::Nodes}}}; +/// @brief The keys of `form`. +constexpr std::array kFormKeys = {{{"model", Shape::Name, {}, kRequired}, + {"action", Shape::Text, {}, kRequired}, + {"prefill", Shape::Expr}, + {"key", Shape::Expr}, + {"submit", Shape::Text}, + {"showErrors", Shape::Text}, + {"fields", Shape::ExprRecord, "fields"}, + {"onSubmit", Shape::Commands}, + {"onSuccess", Shape::Commands}, + {"onError", Shape::Commands}, + {"title", Shape::Expr}, + {"submitLabel", Shape::Expr}, + {"showStatus", Shape::Flag}, + {"columns", Shape::Expr}, + {"fieldLayout", Shape::Text}, + {"captionWidth", Shape::Expr}}}; +/// @brief The keys of `collection` and `wizard`: the model and action, and the presentation keys that reach every +/// form the view draws. +constexpr std::array kCollectionKeys = {{{"model", Shape::Name, {}, kRequired}, + {"action", Shape::Text, {}, kRequired}, + {"title", Shape::Expr}, + {"submitLabel", Shape::Expr}, + {"showStatus", Shape::Flag}, + {"columns", Shape::Expr}, + {"fieldLayout", Shape::Text}, + {"captionWidth", Shape::Expr}}}; +/// @brief The keys of `custom`. +constexpr std::array kCustomKeys = { + {{"name", Shape::Text, {}, kRequired}, {"props", Shape::ExprRecord}, {"on", Shape::CommandRecord}}}; +/// @brief The keys of an `a11y` part. +constexpr std::array kA11yKeys = {{{"name", Shape::Expr}, {"role", Shape::Text}}}; +/// @brief The keys of a `drag` part. +constexpr std::array kDragKeys = {{{"payload", Shape::Expr, {}, kRequired}}}; +/// @brief The keys of a `drop` part. +constexpr std::array kDropKeys = {{{"accepts", Shape::Expr}, {"onDrop", Shape::Commands}}}; + +/// @brief The view node kinds of `ui/1` and the part kinds inside them. +constexpr std::array kKinds = {{ + {"text", kTextKeys, kField}, + {"button", kButtonKeys}, + {"textInput", kTextInputKeys, kField | kWritable, kInputValues}, + {"checkbox", kCheckboxKeys, kField | kWritable, kCheckboxValues}, + {"select", kSelectKeys, kField | kWritable, kSelectValues}, + {"menu", kMenuKeys}, + {"column", kContainerKeys}, + {"row", kContainerKeys}, + {"group", kGroupKeys}, + {"grid", kGridKeys}, + {"spacer", {}}, + {"panel", kPanelKeys}, + {"scroll", kScrollKeys}, + {"switch", kSwitchKeys}, + {"tabs", kTabsKeys, 0, kTabsValues}, + {"dialog", kDialogKeys, kScope, kDialogValues}, + {"drawer", kDialogKeys, kScope, kDialogValues}, + {"busy", kBusyKeys}, + {"forEach", kForEachKeys, kScope | kRowScope}, + {"table", kTableKeys, kScope | kRowScope, kTableValues}, + {"dateTimeInput", kDateTimeKeys, kField | kWritable, kInputValues}, + {"slider", kSliderKeys, kField | kWritable, kInputValues}, + {"filePicker", kFilePickerKeys, kField}, + {"banner", kBannerKeys}, + {"badge", kBadgeKeys}, + {"progress", kProgressKeys}, + {"steps", kStepsKeys}, + {"keyValue", kKeyValueKeys}, + {"emptyState", kEmptyStateKeys}, + {"chart", kChartKeys}, + {"splitter", kSplitterKeys}, + {"collapsible", kCollapsibleKeys}, + {"dropZone", kDropZoneKeys}, + {"actionBar", kActionBarKeys}, + {"page", kPageKeys}, + {"pageRegion", kPageRegionKeys}, + {"localeScope", kLocaleScopeKeys}, + {"customize", kCustomizeKeys}, + {"boundary", kBoundaryKeys}, + {"form", kFormKeys, kOpenValues, kFormValues}, + {"collection", kCollectionKeys}, + {"wizard", kCollectionKeys}, + {"custom", kCustomKeys}, + {"menuItem", kMenuItemKeys, kPart}, + {"case", kCaseKeys, kPart | kScope}, + {"tab", kTabKeys, kPart}, + {"column", kColumnKeys, kPart}, + {"group", kTableGroupKeys, kPart}, + {"track", kTrackKeys, kPart}, + {"action", kActionKeys, kPart}, + {"a11y", kA11yKeys, kPart}, + {"drag", kDragKeys, kPart}, + {"drop", kDropKeys, kPart}, + {"actionButton", kActionButtonKeys, kPart}, + {"headBadge", kHeadBadgeKeys, kPart}, + {"headMenuItem", kHeadMenuItemKeys, kPart}, + {"headTool", kHeadToolKeys, kPart}, + {"navigationBadge", kNavigationBadgeKeys, kPart}, + {"fields", {}, kPart}, + {"series", kSeriesKeys, kPart | kRowScope}, + {"line", kLineKeys, kPart}, +}}; +// NOLINTEND(modernize-use-designated-initializers,readability-trailing-comma) + +/// @brief A literal length of a page node: an integer count of micrometres. +/// @param expr The key's expression. +/// @param key The key, for the refusal. +/// @return The length. +[[nodiscard]] Mm pageLengthOf(ExprPtr const& expr, std::string_view key) { + std::int64_t const* const count = expr->kind == ExprKind::Literal ? expr->literal.asInt() : nullptr; + if (count == nullptr || *count < 0 || *count > std::numeric_limits::max()) { + refuse(expr->path, "`" + std::string{key} + "` is a literal integer count of micrometres, 0 or more"); + } + return Mm::fromMicrometres(static_cast(*count)); +} + +/// @brief Refuses a must-understand key (`!name`) the client does not know; other unknown keys are ignored. +/// @param object The JSON object. +/// @param path Its JSON Pointer. +void refuseMustUnderstand(Json::object_t const& object, std::string const& path) { + for (auto const& [key, value] : object) { + static_cast(value); + if (key.starts_with('!')) { + refuse(pointerAppend(path, key), "the must-understand key `" + key + "` is not part of ui/1"); + } + } +} + +/// @brief Parses a key chord, and refuses one the workspace shell reserves. +/// @param chord The chord, such as `Ctrl+Shift+K`. +/// @param path Its JSON Pointer. +// NOLINTNEXTLINE(readability-function-cognitive-complexity): a chord's grammar, modifiers then one key name. +void checkChord(std::string const& chord, std::string const& path) { + static constexpr std::array kModifiers = {"Ctrl", "Shift", "Alt", "Meta"}; + static constexpr std::array kNamedKeys = { + "Enter", "Esc", "Tab", "Up", "Down", "Left", "Right", "Space", "Delete", + }; + std::vector parts; + std::size_t start = 0; + for (std::size_t plus = chord.find('+'); plus != std::string::npos; plus = chord.find('+', start)) { + parts.push_back(std::string_view{chord}.substr(start, plus - start)); + start = plus + 1; + } + std::string_view const key = std::string_view{chord}.substr(start); + std::set modifiers; + for (std::string_view const modifier : parts) { + if (!listed(kModifiers, modifier) || !modifiers.insert(modifier).second) { + refuse(path, "`" + chord + "` is not a chord: modifiers are Ctrl, Shift, Alt and Meta, once each"); + } + } + bool const letterOrDigit = + key.size() == 1 && ((key.front() >= 'A' && key.front() <= 'Z') || (key.front() >= 'a' && key.front() <= 'z') || + (key.front() >= '0' && key.front() <= '9')); + bool function = key.size() >= 2 && key.size() <= 3 && key.front() == 'F'; + int number = 0; + for (char const chr : key.substr(function ? 1 : key.size())) { + function = function && chr >= '0' && chr <= '9'; + number = (number * 10) + (chr - '0'); + } + function = function && number >= 1 && number <= 24; + if (!letterOrDigit && !function && !listed(kNamedKeys, key)) { + refuse(path, "`" + chord + "` does not end in a key name"); + } + bool const ctrlOnly = modifiers.size() == 1 && modifiers.contains("Ctrl"); + bool const ctrlShift = modifiers.size() == 2 && modifiers.contains("Ctrl") && modifiers.contains("Shift"); + bool const reserved = (key == "Tab" && (ctrlOnly || ctrlShift)) || + (ctrlOnly && (key == "W" || key == "w" || key == "K" || key == "k")); + if (reserved) { + refuse(path, "`" + chord + "` is reserved for the workspace shell"); + } +} + +// NOLINTBEGIN(misc-no-recursion): a document is a tree of nodes and command lists, and parsing descends it. +/// @brief Turns the JSON of a document into its model, refusing what does not parse. +class DocumentParser { +public: + /// @brief Parses the whole document. + /// @param json The document. + /// @return The model, not yet checked against its names. + [[nodiscard]] Document parse(Json const& json) { + auto const* const object = std::get_if(&json.data); + if (object == nullptr) { + refuse("", "a document is a JSON object"); + } + refuseMustUnderstand(*object, ""); + Document doc; + doc.vocab = text(*object, "vocab", "", true); + if (doc.vocab != kVocabulary) { + refuse("/vocab", "the vocabulary `" + doc.vocab + "` is not supported; this client reads ui/1"); + } + doc.id = text(*object, "id", "", true); + if (doc.id.empty()) { + refuse("/id", "a document has a non-empty id"); + } + doc.title = optionalExpr(*object, "title", ""); + doc.identity = optionalExpr(*object, "identity", ""); + doc.dirty = optionalExpr(*object, "dirty", ""); + doc.titleSpans = optionalExpr(*object, "titleSpans", ""); + doc.eyebrow = optionalExpr(*object, "eyebrow", ""); + doc.eyebrowSpans = optionalExpr(*object, "eyebrowSpans", ""); + doc.subtitle = optionalExpr(*object, "subtitle", ""); + doc.subtitleSpans = optionalExpr(*object, "subtitleSpans", ""); + doc.leadPlacement = optionalExpr(*object, "leadPlacement", ""); + checkLeadPlacementLiteral(doc.leadPlacement); + doc.titleRole = optionalExpr(*object, "titleRole", ""); + checkTitleRoleLiteral(doc.titleRole); + doc.headSurface = optionalExpr(*object, "headSurface", ""); + doc.pageSurface = optionalExpr(*object, "pageSurface", ""); + doc.status = topParts(*object, "status", "headBadge"); + doc.actions = topParts(*object, "actions", "actionButton"); + doc.menu = topParts(*object, "menu", "headMenuItem"); + doc.menuLabel = optionalExpr(*object, "menuLabel", ""); + doc.tools = topParts(*object, "tools", "headTool"); + doc.navigation = navigation(*object, doc.id); + if (doc.id == "app") { + refuseScreenHead(*object); + } + static constexpr std::array kPrincipalPlacements = {"sidebar", "head"}; + doc.principalPlacement = choiceOf(*object, "principalPlacement", "", kPrincipalPlacements); + if (doc.id != "app" && member(*object, "principalPlacement") != nullptr) { + refuse("/principalPlacement", "`principalPlacement` is the app document's; a screen has none"); + } + doc.showErrors = showErrors(*object, ""); + datePatterns(*object, doc); + if (Json const* const params = member(*object, "params")) { + for (auto const& [name, type] : objectOf(*params, "/params", "`params` maps names to types")) { + std::string const path = pointerAppend("/params", name); + checkName(name, path); + doc.params.emplace_back(name, typeOf(type, path)); + } + } + doc.scope = scope(*object, ""); + shellParts(*object, doc); + for (std::string_view const key : {"onMount", "onUnmount", "onClose", "onSave", "onBackendChange"}) { + if (Json const* const commands = member(*object, key)) { + doc.lifecycle.emplace(std::string{key}, commandList(*commands, pointerAppend("", key))); + } + } + if (Json const* const keys = member(*object, "keys")) { + doc.keys = keyBindings(*keys, "/keys"); + } + if (Json const* const prefetch = member(*object, "prefetch")) { + doc.prefetch = nameList(*prefetch, "/prefetch"); + } + if (Json const* const components = member(*object, "components")) { + for (auto const& [name, entry] : objectOf(*components, "/components", "`components` is an object")) { + doc.components.emplace(name, component(name, entry, pointerAppend("/components", name))); + } + } + if (Json const* const points = member(*object, "customize")) { + for (auto const& [name, entry] : objectOf(*points, "/customize", "`customize` is an object")) { + doc.customize.emplace(name, point(name, entry, pointerAppend("/customize", name), doc.id == "app")); + } + } + if (Json const* const view = member(*object, "view")) { + doc.view = node(*view, "/view"); + } else if (doc.id != "app") { + refuse("", "a screen has a `view`"); + } + return doc; + } + +private: + // The app document's `formatting`: a record of the date pattern and the date-and-time pattern, each checked. + static void datePatterns(Json::object_t const& object, Document& doc) { + Json const* const formatting = member(object, "formatting"); + if (formatting == nullptr) { + return; + } + if (doc.id != "app") { + refuse("/formatting", "`formatting` is the application's; only the app document declares it"); + } + for (auto const& [key, value] : objectOf(*formatting, "/formatting", "`formatting` is a record")) { + std::string const path = pointerAppend("/formatting", key); + if (key != "date" && key != "dateTime") { + refuse(path, "`formatting` takes `date` and `dateTime`"); + } + std::string const* const pattern = std::get_if(&value.data); + if (pattern == nullptr) { + refuse(path, "a date pattern is a string, such as `dd-MMM-yyyy`"); + } + if (auto const checked = checkDatePattern(*pattern, key == "dateTime"); !checked) { + refuse(path, checked.error()); + } + (key == "date" ? doc.datePattern : doc.dateTimePattern) = *pattern; + } + } + + [[nodiscard]] static Json const* member(Json::object_t const& object, std::string_view key) { + auto const* const found = object.find(key); + return found == object.end() ? nullptr : &found->second; + } + + [[nodiscard]] static Json::object_t const& objectOf(Json const& json, std::string const& path, char const* what) { + auto const* const object = std::get_if(&json.data); + if (object == nullptr) { + refuse(path, what); + } + return *object; + } + + static void checkName(std::string const& name, std::string const& path) { + if (!isName(name)) { + refuse(path, "`" + name + "` is not a name: names match [A-Za-z_][A-Za-z0-9_]*"); + } + } + + [[nodiscard]] static std::string text(Json::object_t const& object, std::string_view key, std::string const& path, + bool required) { + Json const* const value = member(object, key); + std::string const keyPath = pointerAppend(path, key); + if (value == nullptr) { + if (required) { + refuse(path, "`" + std::string{key} + "` is required"); + } + return {}; + } + auto const* const string = std::get_if(&value->data); + if (string == nullptr) { + refuse(keyPath, "`" + std::string{key} + "` is a string"); + } + return *string; + } + + [[nodiscard]] static std::string choiceOf(Json::object_t const& object, std::string_view key, + std::string const& path, std::span choices) { + std::string value = text(object, key, path, false); + if (!value.empty() && !listed(choices, value)) { + refuse(pointerAppend(path, key), "`" + value + "` is not one of the values of `" + std::string{key} + "`"); + } + return value; + } + + [[nodiscard]] static std::string showErrors(Json::object_t const& object, std::string const& path) { + static constexpr std::array kPolicies = {"touched", "submit", "always"}; + return choiceOf(object, "showErrors", path, kPolicies); + } + + [[nodiscard]] static std::int64_t integer(Json::object_t const& object, std::string_view key, + std::string const& path) { + Json const* const value = member(object, key); + if (value == nullptr) { + return 0; + } + auto const number = detail::jsonInt(*value); + if (!number || *number < 0) { + refuse(pointerAppend(path, key), "`" + std::string{key} + "` is a non-negative integer"); + } + return *number; + } + + [[nodiscard]] static bool flag(Json::object_t const& object, std::string_view key, std::string const& path) { + Json const* const value = member(object, key); + if (value == nullptr) { + return false; + } + bool const* const set = std::get_if(&value->data); + if (set == nullptr) { + refuse(pointerAppend(path, key), "`" + std::string{key} + "` is a bool"); + } + return *set; + } + + [[nodiscard]] static Type typeOf(Json const& json, std::string const& path) { + auto const* const spelled = std::get_if(&json.data); + if (spelled == nullptr) { + refuse(path, "a type is written as a string, such as `int?`"); + } + auto type = parseType(*spelled); + if (!type) { + refuse(path, type.error()); + } + return *type; + } + + [[nodiscard]] static std::vector nameList(Json const& json, std::string const& path) { + auto const* const array = std::get_if(&json.data); + if (array == nullptr) { + refuse(path, "a list of names is an array of strings"); + } + std::vector names; + for (std::size_t index = 0; index < array->size(); ++index) { + auto const* const name = std::get_if(&array->at(index).data); + if (name == nullptr || name->empty()) { + refuse(pointerAppend(path, index), "a list of names is an array of strings"); + } + names.push_back(*name); + } + return names; + } + + [[nodiscard]] static ExprPtr expr(Json const& json, std::string const& path) { + auto parsed = parseExpression(json, path); + if (!parsed) { + throw DocumentRefused{std::move(parsed.error())}; + } + return std::move(*parsed); + } + + [[nodiscard]] static ExprPtr optionalExpr(Json::object_t const& object, std::string_view key, + std::string const& path) { + Json const* const value = member(object, key); + return value == nullptr ? nullptr : expr(*value, pointerAppend(path, key)); + } + + // The head belongs to a screen's tab; the app document has no view and so no head. + static void refuseScreenHead(Json::object_t const& object) { + for (std::string_view const key : { + "titleSpans", + "eyebrow", + "eyebrowSpans", + "subtitle", + "subtitleSpans", + "leadPlacement", + "titleRole", + "headSurface", + "pageSurface", + "status", + "actions", + "menu", + "menuLabel", + "tools", + }) { + if (member(object, key) != nullptr) { + refuse(pointerAppend("", key), "`" + std::string{key} + "` is a screen's; the app document has none"); + } + } + } + + // A `leadPlacement` written as a literal is one of the three places; a computed one is read at run time. + static void checkLeadPlacementLiteral(ExprPtr const& placement) { + if (placement == nullptr || placement->kind != ExprKind::Literal) { + return; + } + std::string const* const name = placement->literal.asString(); + if (name == nullptr || (*name != "below" && *name != "inline" && *name != "end")) { + refuse(placement->path, "`leadPlacement` is `below`, `inline` or `end`"); + } + } + + // A `titleRole` written as a literal is one of the two roles a head's title takes; a computed one is read at run + // time. + static void checkTitleRoleLiteral(ExprPtr const& role) { + if (role == nullptr || role->kind != ExprKind::Literal) { + return; + } + std::string const* const name = role->literal.asString(); + if (name == nullptr || (*name != "heading" && *name != "headline")) { + refuse(role->path, "`titleRole` is `heading` or `headline`"); + } + } + + // The app document's `navigation` badges, each naming its screen; a screen declares none. + [[nodiscard]] std::vector navigation(Json::object_t const& object, std::string_view documentId) { + std::vector badges = topParts(object, "navigation", "navigationBadge"); + if (documentId != "app" && !badges.empty()) { + refuse("/navigation", "`navigation` is the app document's; a screen has none"); + } + for (DocNodePtr const& badge : badges) { + if (badge->name("screen").empty()) { + refuse(pointerAppend(badge->path, "screen"), "a navigation badge names the screen of its entry"); + } + } + return badges; + } + + // A top-level list of parts: the screen head's `status` and `actions`. + // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the document key, then its part kind, at every call. + [[nodiscard]] std::vector topParts(Json::object_t const& object, std::string_view key, + std::string_view kind) { + std::vector parts; + Json const* const value = member(object, key); + if (value == nullptr) { + return parts; + } + std::string const path = pointerAppend("", key); + auto const* const array = std::get_if(&value->data); + if (array == nullptr) { + refuse(path, "`" + std::string{key} + "` is an array"); + } + for (std::size_t index = 0; index < array->size(); ++index) { + parts.push_back(part(array->at(index), kind, pointerAppend(path, index))); + } + return parts; + } + + /// @brief Reads the app document's `shell` member, checks it, and appends the queries and state it lowers to. + /// @param object The document's JSON object. + /// @param doc The document being built; its scope receives the lowered declarations. + void shellParts(Json::object_t const& object, Document& doc) { + Json const* const declared = member(object, "shell"); + if (declared == nullptr) { + return; + } + if (doc.id != "app") { + refuse("/shell", "`shell` is the app document's; a screen has none"); + } + ShellParts parts; + auto const text = glz::write_json(*declared); + if (!text || glz::read_json(parts, *text)) { + refuse("/shell", + "`shell` holds the parts: context, modules, search, inbox, principal, brand, help, searchHint"); + } + checkShellParts(parts); + auto const checkNames = [](auto const& declarations) { + for (auto const& entry : declarations) { + if (shell_names::reserved(entry.name)) { + refuse(entry.path, "`" + entry.name + "` is reserved: the shell's parts declare it"); + } + } + }; + checkNames(doc.scope.models); + checkNames(doc.scope.state); + checkNames(doc.scope.lets); + checkNames(doc.scope.queries); + checkNames(doc.scope.mutations); + auto lowered = parseJson(lowerShellParts(parts)); + auto const* const loweredObject = lowered ? std::get_if(&lowered->data) : nullptr; + if (loweredObject == nullptr) { + refuse("/shell", "the shell's parts do not lower"); + } + ScopeDecl extra = scope(*loweredObject, "/shell"); + auto const append = [](auto& into, auto& from) { + into.insert(into.end(), std::make_move_iterator(from.begin()), std::make_move_iterator(from.end())); + }; + append(doc.scope.models, extra.models); + append(doc.scope.state, extra.state); + append(doc.scope.queries, extra.queries); + append(doc.scope.mutations, extra.mutations); + doc.shell = std::move(parts); + } + + /// @brief Refuses a declaration that cannot be read: a repeated module, an empty required field, a repeated tag. + /// @param parts The parts. + static void checkShellParts(ShellParts const& parts) { + auto required = [](std::string const& value, std::string const& path) { + if (value.empty()) { + refuse(path, "the shell's part needs this name"); + } + }; + auto const distinct = [](auto const& list, std::string const& path, auto key) { + std::set seen; + for (auto const& entry : list) { + if (!seen.insert(key(entry)).second) { + refuse(path, "the shell's parts list `" + key(entry) + "` twice"); + } + } + }; + if (parts.context) { + required(parts.context->model, "/shell/context/model"); + required(parts.context->action, "/shell/context/action"); + required(parts.context->optionsField, "/shell/context/optionsField"); + required(parts.context->labelField, "/shell/context/labelField"); + required(parts.context->valueField, "/shell/context/valueField"); + } + auto const count = [&](ModuleCount const& entry, std::string const& path) { + required(entry.model, path + "/model"); + required(entry.action, path + "/action"); + required(entry.countField, path + "/countField"); + }; + for (std::size_t index = 0; index < parts.modules.size(); ++index) { + count(parts.modules.at(index), "/shell/modules/" + std::to_string(index)); + } + distinct(parts.modules, "/shell/modules", [](ModuleCount const& entry) { return entry.module; }); + for (std::size_t index = 0; index < parts.search.size(); ++index) { + std::string const path = "/shell/search/" + std::to_string(index); + required(parts.search.at(index).model, path + "/model"); + required(parts.search.at(index).action, path + "/action"); + required(parts.search.at(index).queryField, path + "/queryField"); + required(parts.search.at(index).resultsField, path + "/resultsField"); + } + distinct(parts.search, "/shell/search", [](SearchSource const& entry) { return entry.module; }); + if (parts.inbox) { + required(parts.inbox->screen, "/shell/inbox/screen"); + if (parts.inbox->sources.empty()) { + refuse("/shell/inbox/sources", "an inbox sums at least one source"); + } + for (std::size_t index = 0; index < parts.inbox->sources.size(); ++index) { + count(parts.inbox->sources.at(index), "/shell/inbox/sources/" + std::to_string(index)); + } + } + if (parts.principal) { + PrincipalMenu const& menu = *parts.principal; + required(menu.model, "/shell/principal/model"); + required(menu.action, "/shell/principal/action"); + required(menu.nameField, "/shell/principal/nameField"); + distinct(menu.locales, "/shell/principal/locales", [](std::string const& tag) { return tag; }); + distinct(menu.formats, "/shell/principal/formats", [](std::string const& tag) { return tag; }); + } + if (parts.brand) { + required(parts.brand->title, "/shell/brand/title"); + } + if (parts.help) { + HelpEntry const& help = *parts.help; + if (help.screen.empty() == help.action.empty()) { + refuse("/shell/help", "the help button opens a screen or runs an action: name one of the two"); + } + if (!help.action.empty()) { + required(help.model, "/shell/help/model"); + } else if (!help.model.empty()) { + refuse("/shell/help/model", "a model belongs to an action; the help button opens a screen"); + } + } + } + + // NOLINTNEXTLINE(readability-function-cognitive-complexity): one branch per kind of declaration. + [[nodiscard]] ScopeDecl scope(Json::object_t const& object, std::string const& path) { + ScopeDecl decl; + if (Json const* const models = member(object, "models")) { + std::string const where = pointerAppend(path, "models"); + for (auto const& [name, entry] : objectOf(*models, where, "`models` maps aliases to models")) { + decl.models.push_back(model(name, entry, pointerAppend(where, name))); + } + } + if (Json const* const state = member(object, "state")) { + std::string const where = pointerAppend(path, "state"); + for (auto const& [name, entry] : objectOf(*state, where, "`state` maps names to declarations")) { + std::string const entryPath = pointerAppend(where, name); + checkName(name, entryPath); + auto const& fields = objectOf(entry, entryPath, R"(a state declaration is {"init": e, "type": T})"); + refuseMustUnderstand(fields, entryPath); + StateDecl stateDecl{ + .name = name, + .path = entryPath, + .type = Type::any(), + .typeDeclared = false, + .init = nullptr, + }; + if (Json const* const type = member(fields, "type")) { + stateDecl.type = typeOf(*type, pointerAppend(entryPath, "type")); + stateDecl.typeDeclared = true; + } + stateDecl.init = optionalExpr(fields, "init", entryPath); + decl.state.push_back(std::move(stateDecl)); + } + } + if (Json const* const lets = member(object, "let")) { + std::string const where = pointerAppend(path, "let"); + for (auto const& [name, entry] : objectOf(*lets, where, "`let` maps names to expressions")) { + std::string const entryPath = pointerAppend(where, name); + checkName(name, entryPath); + decl.lets.push_back(LetDecl{.name = name, .path = entryPath, .value = expr(entry, entryPath)}); + } + } + if (Json const* const queries = member(object, "queries")) { + std::string const where = pointerAppend(path, "queries"); + for (auto const& [name, entry] : objectOf(*queries, where, "`queries` maps names to queries")) { + decl.queries.push_back(query(name, entry, pointerAppend(where, name))); + } + } + if (Json const* const mutations = member(object, "mutations")) { + std::string const where = pointerAppend(path, "mutations"); + for (auto const& [name, entry] : objectOf(*mutations, where, "`mutations` maps names to mutations")) { + decl.mutations.push_back(mutation(name, entry, pointerAppend(where, name))); + } + } + if (Json const* const watches = member(object, "watch")) { + std::string const where = pointerAppend(path, "watch"); + auto const* const array = std::get_if(&watches->data); + if (array == nullptr) { + refuse(where, "`watch` is an array"); + } + for (std::size_t index = 0; index < array->size(); ++index) { + decl.watches.push_back(watch(array->at(index), pointerAppend(where, index))); + } + } + if (Json const* const checks = member(object, "checks")) { + std::string const where = pointerAppend(path, "checks"); + auto const* const array = std::get_if(&checks->data); + if (array == nullptr) { + refuse(where, "`checks` is an array"); + } + for (std::size_t index = 0; index < array->size(); ++index) { + decl.checks.push_back(check(array->at(index), pointerAppend(where, index))); + } + } + return decl; + } + + [[nodiscard]] static ModelDecl model(std::string const& name, Json const& json, std::string const& path) { + checkName(name, path); + auto const& fields = objectOf(json, path, R"(a model alias is {"type": ..., "instance": ...})"); + refuseMustUnderstand(fields, path); + ModelDecl decl{ + .name = name, + .path = path, + .type = text(fields, "type", path, true), + .instance = {}, + .key = nullptr, + .borrowedFrom = {}, + }; + Json const* const instance = member(fields, "instance"); + if (instance == nullptr) { + return decl; + } + std::string const where = pointerAppend(path, "instance"); + auto const* const word = std::get_if(&instance->data); + if (word != nullptr && (*word == "private" || *word == "shared")) { + decl.instance = *word == "private" ? InstanceMode::Private : InstanceMode::Shared; + return decl; + } + if (auto const* const object = std::get_if(&instance->data)) { + if (Json const* const from = member(*object, "from")) { + auto const* const alias = std::get_if(&from->data); + if (alias == nullptr || !isName(*alias) || object->size() != 1) { + refuse(where, R"(a borrowed instance is {"from": alias})"); + } + decl.instance = InstanceMode::Borrowed; + decl.borrowedFrom = *alias; + return decl; + } + } + decl.instance = InstanceMode::Keyed; + decl.key = expr(*instance, where); + return decl; + } + + /// @brief Refuses @p key of @p fields: a refresh key, which a document does not declare. + /// @param fields The declaration's fields. + /// @param path The declaration's JSON Pointer. + /// @param key The refresh key: `invalidates`, `patch` or `refreshOn`. + static void refuseRefreshKey(Json::object_t const& fields, std::string const& path, std::string_view key) { + if (member(fields, key) != nullptr) { + refuse(pointerAppend(path, key), + std::format("a document does not declare `{}`: an action's effects say what it changes, and every " + "query holding a changed record refreshes; a refresh no action declares is a `refetch` " + "command", + key)); + } + } + + [[nodiscard]] static QueryDecl query(std::string const& name, Json const& json, std::string const& path) { + checkName(name, path); + auto const& fields = objectOf(json, path, "a query is an object"); + refuseMustUnderstand(fields, path); + QueryDecl decl; + decl.name = name; + decl.path = path; + decl.model = text(fields, "model", path, true); + std::string const action = text(fields, "action", path, false); + std::string const evaluate = text(fields, "evaluate", path, false); + if (action.empty() == evaluate.empty()) { + refuse(path, "a query names exactly one of `action` and `evaluate`"); + } + decl.action = action.empty() ? evaluate : action; + decl.evaluate = !evaluate.empty(); + decl.body = optionalExpr(fields, "body", path); + decl.when = optionalExpr(fields, "when", path); + decl.debounce = integer(fields, "debounce", path); + decl.refreshEvery = integer(fields, "refreshEvery", path); + decl.staleTime = integer(fields, "staleTime", path); + refuseRefreshKey(fields, path, "refreshOn"); + return decl; + } + + /// @brief Parses an `optimistic` write: `{"query": q, "at"?: m, "key": e, "with": e}`. + /// @param json The write's JSON. + /// @param path Its JSON Pointer. + /// @return The write. + [[nodiscard]] static OptimisticDecl optimistic(Json const& json, std::string const& path) { + static constexpr char const* shape = R"(an optimistic write is {"query": q, "at"?: m, "key": e, "with": e})"; + auto const& fields = objectOf(json, path, shape); + refuseMustUnderstand(fields, path); + Json const* const key = member(fields, "key"); + Json const* const with = member(fields, "with"); + if (key == nullptr || with == nullptr) { + refuse(path, shape); + } + std::string listMember = text(fields, "at", path, false); + if (member(fields, "at") != nullptr && listMember.empty()) { + refuse(pointerAppend(path, "at"), "`at` names the member of the query's record that holds the list"); + } + return OptimisticDecl{ + .query = text(fields, "query", path, true), + .at = std::move(listMember), + .key = expr(*key, pointerAppend(path, "key")), + .with = expr(*with, pointerAppend(path, "with")), + }; + } + + [[nodiscard]] MutationDecl mutation(std::string const& name, Json const& json, std::string const& path) { + checkName(name, path); + auto const& fields = objectOf(json, path, "a mutation is an object"); + refuseMustUnderstand(fields, path); + MutationDecl decl; + decl.name = name; + decl.path = path; + decl.model = text(fields, "model", path, true); + decl.action = text(fields, "action", path, true); + decl.body = optionalExpr(fields, "body", path); + static constexpr std::array kModes = {"exclusive", "serial", "latest", "parallel"}; + std::string const mode = choiceOf(fields, "concurrency", path, kModes); + if (mode == "serial") { + decl.concurrency = Concurrency::Serial; + } else if (mode == "latest") { + decl.concurrency = Concurrency::Latest; + } else if (mode == "parallel") { + decl.concurrency = Concurrency::Parallel; + } + decl.serialKey = optionalExpr(fields, "serialKey", path); + if (decl.serialKey && decl.concurrency != Concurrency::Serial) { + refuse(pointerAppend(path, "serialKey"), "`serialKey` applies to `serial` concurrency only"); + } + refuseRefreshKey(fields, path, "invalidates"); + refuseRefreshKey(fields, path, "patch"); + if (Json const* const value = member(fields, "optimistic")) { + decl.optimistic = optimistic(*value, pointerAppend(path, "optimistic")); + } + if (Json const* const commands = member(fields, "onSuccess")) { + decl.onSuccess = commandList(*commands, pointerAppend(path, "onSuccess")); + } + if (Json const* const commands = member(fields, "onError")) { + decl.onError = commandList(*commands, pointerAppend(path, "onError")); + } + static constexpr std::array kOffline = {"queue"}; + decl.offlineQueue = !choiceOf(fields, "offline", path, kOffline).empty(); + return decl; + } + + [[nodiscard]] WatchDecl watch(Json const& json, std::string const& path) { + auto const& fields = objectOf(json, path, R"(a watch is {"on": e, "do": [...]})"); + refuseMustUnderstand(fields, path); + Json const* const watched = member(fields, "on"); + Json const* const body = member(fields, "do"); + if (watched == nullptr || body == nullptr) { + refuse(path, R"(a watch is {"on": e, "do": [...]})"); + } + static constexpr std::array kSources = {"any", "user"}; + return WatchDecl{ + .path = path, + .on = expr(*watched, pointerAppend(path, "on")), + .source = choiceOf(fields, "source", path, kSources) == "user" ? WatchSource::User : WatchSource::Any, + .body = commandList(*body, pointerAppend(path, "do")), + }; + } + + [[nodiscard]] static CheckDecl check(Json const& json, std::string const& path) { + auto const& fields = objectOf(json, path, R"(a check is {"id": ..., "assert": e, ...})"); + refuseMustUnderstand(fields, path); + Json const* const assertion = member(fields, "assert"); + if (assertion == nullptr) { + refuse(path, "a check has an `assert`"); + } + CheckDecl decl; + decl.id = text(fields, "id", path, false); + decl.path = path; + decl.assertion = expr(*assertion, pointerAppend(path, "assert")); + decl.message = optionalExpr(fields, "message", path); + if (Json const* const targets = member(fields, "targets")) { + decl.targets = nameList(*targets, pointerAppend(path, "targets")); + } + decl.blocking = flag(fields, "blocking", path); + return decl; + } + + struct CommandSpec { + std::string_view key; + CommandKind kind; + std::array companions; + }; + + // NOLINTBEGIN(modernize-use-designated-initializers,readability-trailing-comma): one row per command reads as a table. A trailing comma would put every row member on a line of its own. + static constexpr std::array kCommands = {{ + {"set", CommandKind::Set, {"value"}}, + {"reset", CommandKind::Reset, {}}, + {"run", CommandKind::Run, {"body", "as", "each"}}, + {"refetch", CommandKind::Refetch, {}}, + {"open", CommandKind::Open, {}}, + {"close", CommandKind::Close, {}}, + {"navigate", CommandKind::Navigate, {"params", "as", "onResult", "onCancel"}}, + {"return", CommandKind::Return, {}}, + {"focus", CommandKind::Focus, {"row"}}, + {"host", CommandKind::Host, {"args"}}, + {"switchBackend", CommandKind::SwitchBackend, {}}, + {"resetPrefs", CommandKind::ResetPrefs, {}}, + {"setLocale", CommandKind::SetLocale, {}}, + {"setContext", CommandKind::SetContext, {}}, + {"notify", CommandKind::Notify, {"role"}}, + {"seq", CommandKind::Seq, {}}, + {"all", CommandKind::All, {}}, + {"if", CommandKind::If, {}}, + {"cancelClose", CommandKind::CancelClose, {}}, + {"retry", CommandKind::Retry, {}}, + {"signIn", CommandKind::SignIn, {}}, + {"signOut", CommandKind::SignOut, {}}, + {"upload", CommandKind::Upload, {"to", "as", "id", "into", "nameAs", "typeAs"}}, + {"download", CommandKind::Download, {"save", "name", "to", "as", "from", "type"}}, + }}; + // NOLINTEND(modernize-use-designated-initializers,readability-trailing-comma) + + [[nodiscard]] Commands commandList(Json const& json, std::string const& path) { + Commands commands; + if (auto const* const array = std::get_if(&json.data)) { + for (std::size_t index = 0; index < array->size(); ++index) { + commands.push_back(command(array->at(index), pointerAppend(path, index))); + } + return commands; + } + commands.push_back(command(json, path)); + return commands; + } + + [[nodiscard]] static std::string nameOf(Json const& json, std::string const& path, char const* what, + bool dotted = false) { + auto const* const name = std::get_if(&json.data); + bool valid = name != nullptr && !name->empty(); + if (valid && dotted) { + auto const segments = splitPath(*name); + valid = segments.has_value() && isName(segments->front()); + } else if (valid) { + valid = isName(*name); + } + if (!valid) { + refuse(path, what); + } + return *name; + } + + [[nodiscard]] static std::string nonEmpty(Json const& json, std::string const& path, char const* what) { + auto const* const name = std::get_if(&json.data); + if (name == nullptr || name->empty()) { + refuse(path, what); + } + return *name; + } + + static void requireTrue(Json const& json, std::string const& path, std::string_view key) { + bool const* const value = std::get_if(&json.data); + if (value == nullptr || !*value) { + refuse(path, "`" + std::string{key} + "` is written `true`"); + } + } + + // NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per command of ui/1. + [[nodiscard]] Command command(Json const& json, std::string const& path) { + auto const& fields = objectOf(json, path, R"(a command is an object such as {"set": ..., "value": ...})"); + CommandSpec const* chosen = nullptr; + for (auto const& [key, value] : fields) { + static_cast(value); + for (CommandSpec const& spec : kCommands) { + if (spec.key == key) { + if (chosen != nullptr) { + refuse(path, + "a command has one kind; found `" + std::string{chosen->key} + "` and `" + key + "`"); + } + chosen = &spec; + } + } + } + if (chosen == nullptr) { + refuse(path, "not a command of ui/1"); + } + refuseMustUnderstand(fields, path); + Command cmd; + cmd.kind = chosen->kind; + cmd.path = path; + Json const& primary = *member(fields, chosen->key); + std::string const where = pointerAppend(path, chosen->key); + switch (chosen->kind) { + case CommandKind::Set: { + cmd.target = nameOf(primary, where, "`set` names state or an element as `name.path`", true); + Json const* const value = member(fields, "value"); + if (value == nullptr) { + refuse(path, "`set` needs a `value`"); + } + cmd.value = expr(*value, pointerAppend(path, "value")); + break; + } + case CommandKind::Run: + cmd.target = nameOf(primary, where, "`run` names a mutation"); + cmd.value = optionalExpr(fields, "body", path); + cmd.extra = optionalExpr(fields, "each", path); + if (Json const* const binding = member(fields, "as")) { + cmd.binding = nameOf(*binding, pointerAppend(path, "as"), "`as` is a name"); + } + break; + case CommandKind::Reset: + case CommandKind::Refetch: + case CommandKind::Open: + cmd.target = nameOf(primary, where, "the command names a declaration or an element"); + break; + case CommandKind::Focus: + cmd.target = nameOf(primary, where, "the command names a declaration or an element"); + cmd.extra = optionalExpr(fields, "row", path); + break; + case CommandKind::Close: + cmd.target = nameOf(primary, where, "`close` names a dialog, or `self`"); + break; + case CommandKind::Navigate: + navigate(cmd, fields, primary, path); + break; + case CommandKind::Return: + case CommandKind::SetContext: + cmd.value = expr(primary, where); + break; + case CommandKind::Host: + cmd.target = nonEmpty(primary, where, "`host` names a registered command"); + cmd.value = optionalExpr(fields, "args", path); + break; + case CommandKind::SwitchBackend: + case CommandKind::SetLocale: + cmd.target = nonEmpty(primary, where, "the command takes a non-empty string"); + break; + case CommandKind::ResetPrefs: + cmd.target = nameOf(primary, where, "`resetPrefs` names a customization point, or `all`"); + break; + case CommandKind::Notify: { + cmd.value = expr(primary, where); + static constexpr std::array kRoles = {"info", "success", "warning", "error"}; + cmd.option = choiceOf(fields, "role", path, kRoles); + break; + } + case CommandKind::Seq: + case CommandKind::All: { + if (!std::holds_alternative(primary.data)) { + refuse(where, "`" + std::string{chosen->key} + "` takes an array of commands"); + } + cmd.commands = commandList(primary, where); + break; + } + case CommandKind::If: { + auto const* const array = std::get_if(&primary.data); + if (array == nullptr || array->size() < 2 || array->size() > 3) { + refuse(where, "`if` takes [condition, [then...], [else...]]"); + } + cmd.value = expr(array->at(0), pointerAppend(where, std::size_t{0})); + cmd.commands = commandList(array->at(1), pointerAppend(where, 1)); + if (array->size() == 3) { + cmd.alternative = commandList(array->at(2), pointerAppend(where, 2)); + } + break; + } + case CommandKind::CancelClose: + case CommandKind::Retry: + case CommandKind::SignOut: + requireTrue(primary, where, chosen->key); + break; + case CommandKind::SignIn: { + auto const* const object = std::get_if(&primary.data); + Json const* const from = object == nullptr ? nullptr : member(*object, "from"); + if (from == nullptr) { + refuse(where, R"(`signIn` is {"from": mutation})"); + } + cmd.target = nameOf(*from, pointerAppend(where, "from"), "`signIn` names its mutation"); + break; + } + case CommandKind::Upload: { + cmd.value = expr(primary, where); + Json const* const destination = member(fields, "to"); + if (destination == nullptr) { + refuse(path, "`upload` names its mutation with `to`"); + } + cmd.target = nameOf(*destination, pointerAppend(path, "to"), "`to` names a mutation"); + if (Json const* const binding = member(fields, "as")) { + cmd.binding = nameOf(*binding, pointerAppend(path, "as"), "`as` is a name"); + } + if (Json const* const transfer = member(fields, "id")) { + cmd.transfer = nameOf(*transfer, pointerAppend(path, "id"), "`id` is a name"); + } + static constexpr std::array kInto = {"ref", "bytes"}; + cmd.bytes = choiceOf(fields, "into", path, kInto) == "bytes"; + for (auto const& [key, slot] : {std::pair{"nameAs", &cmd.nameAs}, std::pair{"typeAs", &cmd.typeAs}}) { + if (Json const* const name = member(fields, key)) { + if (!cmd.bytes) { + refuse(pointerAppend(path, key), + "`" + std::string{key} + + R"(` names a body member for inline bytes; give `"into": "bytes"`)"); + } + *slot = nameOf(*name, pointerAppend(path, key), "a body member is a name"); + } + } + break; + } + case CommandKind::Download: + default: + download(cmd, fields, primary, path); + break; + } + return cmd; + } + + void navigate(Command& cmd, Json::object_t const& fields, Json const& primary, std::string const& path) { + std::string const where = pointerAppend(path, "navigate"); + if (auto const* const route = std::get_if(&primary.data)) { + Json const* const value = member(*route, "route"); + if (value == nullptr || route->size() != 1) { + refuse(where, R"(`navigate` names a screen, or is {"route": e})"); + } + cmd.extra = expr(*value, pointerAppend(where, "route")); + } else { + cmd.target = nonEmpty(primary, where, R"(`navigate` names a screen, or is {"route": e})"); + } + cmd.value = optionalExpr(fields, "params", path); + static constexpr std::array kModes = {"tab", "dialog", "drawer", "window"}; + cmd.option = choiceOf(fields, "as", path, kModes); + if (Json const* const result = member(fields, "onResult")) { + cmd.commands = commandList(*result, pointerAppend(path, "onResult")); + } + if (Json const* const cancel = member(fields, "onCancel")) { + cmd.alternative = commandList(*cancel, pointerAppend(path, "onCancel")); + } + } + + static void download(Command& cmd, Json::object_t const& fields, Json const& primary, std::string const& path) { + cmd.value = expr(primary, pointerAppend(path, "download")); + static constexpr std::array kFrom = {"ref", "bytes"}; + cmd.bytes = choiceOf(fields, "from", path, kFrom) == "bytes"; + if (cmd.bytes) { + // Inline bytes carry no name or type of their own, so the document gives the name. + if (member(fields, "name") == nullptr) { + refuse(path, "a download from bytes names its file with `name`"); + } + cmd.extra = optionalExpr(fields, "name", path); + cmd.mediaType = optionalExpr(fields, "type", path); + } else if (member(fields, "type") != nullptr) { + refuse(pointerAppend(path, "type"), R"(`type` is the media type of inline bytes; give `"from": "bytes"`)"); + } + std::string const save = text(fields, "save", path, false); + std::string const destination = text(fields, "to", path, false); + if (save == "dialog" && destination.empty()) { + cmd.option = "dialog"; + cmd.extra = optionalExpr(fields, "name", path); + return; + } + if (destination == "preview" && save.empty()) { + Json const* const binding = member(fields, "as"); + if (binding == nullptr) { + refuse(path, "a download to preview binds a state with `as`"); + } + cmd.option = "preview"; + cmd.target = nameOf(*binding, pointerAppend(path, "as"), "`as` names a state"); + return; + } + refuse(path, R"(`download` takes `"save": "dialog"` or `"to": "preview"`)"); + } + + [[nodiscard]] std::map> keyBindings(Json const& json, std::string const& path) { + std::map> keys; + for (auto const& [chord, commands] : objectOf(json, path, "`keys` maps chords to commands")) { + std::string const where = pointerAppend(path, chord); + checkChord(chord, where); + keys.emplace(chord, commandList(commands, where)); + } + return keys; + } + + // NOLINTNEXTLINE(readability-function-cognitive-complexity): a component's rules, one after another. + [[nodiscard]] Component component(std::string const& name, Json const& json, std::string const& path) { + checkName(name, path); + auto const& fields = objectOf(json, path, "a component is an object"); + refuseMustUnderstand(fields, path); + Component decl; + decl.name = name; + decl.path = path; + decl.qml = text(fields, "qml", path, false); + decl.host = text(fields, "host", path, false); + if (decl.qml.empty() == decl.host.empty()) { + refuse(path, "a component names exactly one of `qml` and `host`"); + } + if (!decl.qml.empty()) { + bool hash = decl.qml.size() == 71 && decl.qml.starts_with("sha256:"); + for (char const chr : std::string_view{decl.qml}.substr(std::min(7, decl.qml.size()))) { + hash = hash && ((chr >= '0' && chr <= '9') || (chr >= 'a' && chr <= 'f')); + } + if (!hash) { + refuse(pointerAppend(path, "qml"), "`qml` is a content hash `sha256:<64 hex digits>`"); + } + } else { + Json const* const version = member(fields, "version"); + auto const number = version == nullptr ? std::nullopt : detail::jsonInt(*version); + if (!number) { + refuse(path, "a host component has an integer `version`"); + } + decl.version = *number; + } + static constexpr std::array kPropTypes = { + "string", "bool", "int", "exact", "number", "json", + }; + if (Json const* const props = member(fields, "props")) { + std::string const where = pointerAppend(path, "props"); + for (auto const& [prop, type] : objectOf(*props, where, "`props` maps names to prop types")) { + auto const* const spelled = std::get_if(&type.data); + if (spelled == nullptr || !listed(kPropTypes, *spelled)) { + refuse(pointerAppend(where, prop), "a prop type is string, bool, int, exact, number or json"); + } + decl.props.emplace(prop, *spelled); + } + } + if (Json const* const events = member(fields, "events")) { + std::string const where = pointerAppend(path, "events"); + for (auto const& [event, type] : objectOf(*events, where, "`events` maps names to payload types")) { + decl.events.emplace(event, typeOf(type, pointerAppend(where, event))); + } + } + Json const* const fallback = member(fields, "fallback"); + if (fallback == nullptr) { + refuse(path, "a component names a `fallback` of built-in nodes"); + } + decl.fallback = node(*fallback, pointerAppend(path, "fallback")); + return decl; + } + + [[nodiscard]] static CustomizePoint point(std::string const& name, Json const& json, std::string const& path, + bool appDocument) { + checkName(name, path); + auto const& fields = objectOf(json, path, "a customization point is an object"); + refuseMustUnderstand(fields, path); + static constexpr std::array kPointKinds = { + "columns", "choice", "value", "layout", "saved", "pins", "arrange", + }; + CustomizePoint decl; + decl.name = name; + decl.path = path; + decl.kind = text(fields, "kind", path, true); + if (!listed(kPointKinds, decl.kind)) { + refuse(pointerAppend(path, "kind"), "`" + decl.kind + "` is not a kind of customization point"); + } + if (decl.kind == "pins" && !appDocument) { + refuse(pointerAppend(path, "kind"), "a `pins` point belongs to the app document"); + } + // The container an `arrange` point orders is a screen's, and the app document has no view. + if (decl.kind == "arrange" && appDocument) { + refuse(pointerAppend(path, "kind"), "an `arrange` point belongs to the screen whose container it orders"); + } + decl.of = text(fields, "of", path, decl.kind == "columns" || decl.kind == "arrange"); + Json const* const fallback = member(fields, "default"); + if (decl.kind == "choice") { + Json const* const options = member(fields, "options"); + if (options == nullptr) { + refuse(path, "a `choice` point lists its `options`"); + } + decl.options = nameList(*options, pointerAppend(path, "options")); + if (fallback != nullptr) { + auto const* const chosen = std::get_if(&fallback->data); + if (chosen == nullptr || std::ranges::find(decl.options, *chosen) == decl.options.end()) { + refuse(pointerAppend(path, "default"), "the default of a `choice` is one of its options"); + } + decl.defaultValue = *chosen; + } + decl.type = Type::of(TypeKind::String); + } else if (decl.kind == "value") { + Json const* const type = member(fields, "type"); + if (type == nullptr) { + refuse(path, "a `value` point declares its `type`"); + } + decl.type = typeOf(*type, pointerAppend(path, "type")); + if (fallback != nullptr) { + auto value = valueFromJson(*fallback, decl.type); + if (!value) { + refuse(pointerAppend(path, "default"), + "the default does not have the point's type: " + value.error()); + } + decl.defaultValue = std::move(*value); + } + } + return decl; + } + + [[nodiscard]] DocNodePtr node(Json const& json, std::string const& path) { + auto const* const object = std::get_if(&json.data); + if (object == nullptr) { + refuse(path, "a node is an object with a `kind`"); + } + std::string const kind = text(*object, "kind", path, true); + KindSpec const* const spec = findKind(kind, false); + if (spec == nullptr) { + refuse(pointerAppend(path, "kind"), "the node kind `" + kind + "` is not in ui/1"); + } + auto made = std::make_shared(); + made->kind = kind; + made->path = path; + refuseMustUnderstand(*object, path); + fill(*made, *object, *spec, path); + return made; + } + + void fill(DocNode& made, Json::object_t const& object, KindSpec const& spec, std::string const& path) { + bool const isPart = (spec.flags & kPart) != 0; + auto const apply = [&](KeySpec const& key) { + Json const* const value = member(object, key.key); + if (value == nullptr) { + if ((key.flags & kRequired) != 0) { + refuse(path, "`" + std::string{key.key} + "` is required on `" + std::string{spec.kind} + "`"); + } + return; + } + entry(made, key, *value, pointerAppend(path, key.key)); + }; + if (!isPart) { + for (KeySpec const& key : kCommonKeys) { + apply(key); + } + if ((spec.flags & kField) != 0) { + for (KeySpec const& key : kFieldKeys) { + apply(key); + } + } + } + for (KeySpec const& key : spec.keys) { + apply(key); + } + if ((spec.flags & kScope) != 0) { + if (Json const* const declarations = member(object, "scope")) { + std::string const where = pointerAppend(path, "scope"); + auto const& fields = objectOf(*declarations, where, "`scope` holds a scope's declarations"); + refuseMustUnderstand(fields, where); + made.scope = scope(fields, where); + } else { + made.scope = ScopeDecl{}; + } + } + if (made.kind == "fields") { + for (auto const& [field, overlay] : object) { + made.parts["fields"].push_back(fieldOverlay(field, overlay, pointerAppend(path, field))); + } + } + } + + // One field overlay of a form's `fields`: expressions by key, and the host `component` that draws the field with + // its `props`. + [[nodiscard]] static DocNodePtr fieldOverlay(std::string const& field, Json const& overlay, + std::string const& where) { + auto const& settings = objectOf(overlay, where, "a field overlay is an object"); + auto part = std::make_shared(); + part->kind = "field"; + part->id = field; + part->path = where; + for (auto const& [key, value] : settings) { + std::string const keyPath = pointerAppend(where, key); + if (key == "component") { + // The host component that draws the field, and the props it is given beside the field's. + auto const* const name = std::get_if(&value.data); + if (name == nullptr || !isName(*name)) { + refuse(keyPath, "`component` is a name"); + } + part->names.emplace(key, *name); + } else if (key == "props") { + auto record = std::make_shared(); + record->kind = "props"; + record->path = keyPath; + for (auto const& [prop, propValue] : objectOf(value, keyPath, "`props` is a record of expressions")) { + record->props.emplace(prop, expr(propValue, pointerAppend(keyPath, prop))); + } + part->parts["props"].push_back(std::move(record)); + } else { + part->props.emplace(key, expr(value, keyPath)); + } + } + return part; + } + + [[nodiscard]] DocNodePtr part(Json const& json, std::string_view kind, std::string const& path) { + KindSpec const* const spec = findKind(kind, true); + auto const& object = objectOf(json, path, "a part of a node is an object"); + refuseMustUnderstand(object, path); + auto made = std::make_shared(); + made->kind = std::string{kind}; + made->path = path; + fill(*made, object, *spec, path); + if (kind == "actionButton" && made->prop("iconOnly") != nullptr && made->prop("icon") == nullptr) { + refuse(pointerAppend(path, "iconOnly"), "an icon-only action names its `icon`"); + } + return made; + } + + // NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per shape a key takes. + void entry(DocNode& made, KeySpec const& key, Json const& value, std::string const& path) { + std::string const name{key.key}; + switch (key.shape) { + case Shape::Expr: + case Shape::Condition: + made.props.emplace(name, expr(value, path)); + break; + case Shape::Commands: + made.events.emplace(name, commandList(value, path)); + break; + case Shape::Nodes: { + std::vector nodes; + if (auto const* const array = std::get_if(&value.data)) { + for (std::size_t index = 0; index < array->size(); ++index) { + nodes.push_back(node(array->at(index), pointerAppend(path, index))); + } + } else { + nodes.push_back(node(value, path)); + } + made.children.emplace(name, std::move(nodes)); + break; + } + case Shape::Text: + case Shape::Name: { + auto const* const string = std::get_if(&value.data); + if (string == nullptr || (key.shape == Shape::Name && !isName(*string))) { + refuse(path, "`" + name + "` is " + (key.shape == Shape::Name ? "a name" : "a string")); + } + if (name == "id") { + made.id = *string; + } else { + made.names.emplace(name, *string); + } + break; + } + case Shape::Part: + made.parts[name].push_back(part(value, key.part, path)); + break; + case Shape::Parts: + case Shape::PartsOrExpr: { + auto const* const array = std::get_if(&value.data); + if (array == nullptr && key.shape == Shape::PartsOrExpr) { + made.props.emplace(name, expr(value, path)); + break; + } + if (array == nullptr) { + refuse(path, "`" + name + "` is an array"); + } + auto& list = made.parts[name]; + for (std::size_t index = 0; index < array->size(); ++index) { + list.push_back(part(array->at(index), key.part, pointerAppend(path, index))); + } + break; + } + case Shape::ExprRecord: { + if (!key.part.empty()) { + made.parts[name].push_back(part(value, key.part, path)); + break; + } + auto record = std::make_shared(); + record->kind = name; + record->path = path; + for (auto const& [field, fieldValue] : objectOf(value, path, "a record of expressions")) { + record->props.emplace(field, expr(fieldValue, pointerAppend(path, field))); + } + made.parts[name].push_back(std::move(record)); + break; + } + case Shape::CommandRecord: + for (auto const& [event, commands] : objectOf(value, path, "a record of command lists")) { + made.events.emplace(std::format("{}.{}", name, event), + commandList(commands, pointerAppend(path, event))); + } + break; + case Shape::Flag: { + auto const* const flag = std::get_if(&value.data); + if (flag == nullptr) { + refuse(path, "`" + name + "` is a literal `true` or `false`"); + } + made.flags.emplace(name, *flag); + break; + } + case Shape::Keys: + default: + made.keys = keyBindings(value, path); + break; + } + } + // NOLINTEND(misc-no-recursion) +}; + +struct ScopeInfo; + +/// @brief One declared name of a scope. +struct NameEntry { + /// @brief What it declares. + NameCategory category = NameCategory::Param; + /// @brief The declaration's JSON Pointer. + std::string path; + /// @brief The scope that declares it. + ScopeInfo* scope = nullptr; + /// @brief The type of a param, of typed state, and of state or a `let` once derived. + Type type; + /// @brief The model of a `Model` entry. + ModelDecl const* model = nullptr; + /// @brief The expression a state or `let` type is derived from; `nullptr` when the type is declared. + ExprPtr derivedFrom; + /// @brief The query of a `Query` entry. + QueryDecl const* query = nullptr; + /// @brief The mutation of a `Mutation` entry. + MutationDecl const* mutation = nullptr; + /// @brief The element of an `Element` entry. + DocNode const* element = nullptr; + /// @brief 0 before its type is derived, 1 while it is, 2 after. + int visit = 0; +}; + +/// @brief One scope during validation: its names and its parent. +struct ScopeInfo { + /// @brief The enclosing scope; `nullptr` for a screen or a component fallback. + ScopeInfo* parent = nullptr; + /// @brief The scopes it encloses directly, in document order. + std::vector children; + /// @brief Whether it is a `forEach` or `table` row scope. + bool row = false; + /// @brief The `switch` whose case it is; `nullptr` for any other scope. + DocNode const* switchNode = nullptr; + /// @brief Whether it is the screen's own scope. + bool screen = false; + /// @brief The names it declares. + std::map> names; +}; + +/// @brief Where an expression or command is checked: its scope and what is valid there. +struct CheckContext { + /// @brief The scope. + ScopeInfo* scope = nullptr; + /// @brief Inside a command list, where `event` is valid. + bool commands = false; + /// @brief Inside a boundary's `error`, where `boundary.error` and `retry` are valid. + bool boundaryError = false; + /// @brief Inside `onClose`, where `cancelClose` is valid. + bool onClose = false; + /// @brief Names bound here: `as` of a sequence step or `each`, `result`, `body`, `props`. + std::vector> bindings; +}; + +class DocumentValidator; + +/// @brief Resolves an expression's names against a scope chain and a context. +class ScopeResolver final : public NameResolver { +public: + /// @brief Resolves for @p validator in @p context. + /// @param validator The validator, which derives state and `let` types on demand. + /// @param context Where the expression is. + ScopeResolver(DocumentValidator& validator, CheckContext const& context) + : _validator{validator}, _context{context} {} + + /// @brief Resolves a reference. + /// @param head The first segment. + /// @param path The rest. + /// @return The type, or why it does not resolve. + [[nodiscard]] std::expected ref(std::string_view head, + std::span path) const override; + + /// @brief Resolves a row field. + /// @param path The field path. + /// @return `any` inside a row, or why there is no row. + [[nodiscard]] std::expected row(std::span path) const override; + + /// @brief Resolves a query or mutation name. + /// @param form The form. + /// @param name The name. + /// @return The type, or why it does not resolve. + [[nodiscard]] std::expected control(ExprKind form, std::string_view name) const override; + + /// @brief Resolves a customization point. + /// @param point The point. + /// @param path The rest. + /// @return The type, or why it does not resolve. + [[nodiscard]] std::expected pref(std::string_view point, + std::span path) const override; + +private: + DocumentValidator& _validator; + CheckContext const& _context; +}; + +/// @brief The type of an element value. +/// @param value The value's name. +/// @return Its type. +[[nodiscard]] Type elementValueType(std::string_view value) { + static constexpr std::array kBools = { + "visible", "enabled", "valid", "dirty", "focused", "touched", "checked", "open", "ready", "submitted", + }; + static constexpr std::array kCounts = {"viewCount", "sourceCount", "selectedCount"}; + if (listed(kBools, value) || value == "pending") { + return Type::of(TypeKind::Bool); + } + if (value == "errors" || value == "shownErrors") { + return Type::listOf(Type::of(TypeKind::String)); + } + if (listed(kCounts, value)) { + return Type::of(TypeKind::Int); + } + if (value == "error") { + return Type::of(TypeKind::String, true); + } + return Type::any(); +} + +/// @brief Whether a value of type @p actual may stand where @p declared is expected. +/// @param declared The expected type. +/// @param actual The type found. +/// @return Whether they are compatible: equal kinds, `any` on either side, an `int` for a `decimal` or `key`, a +/// `string` for a `key`. +[[nodiscard]] bool compatible(Type const& declared, Type const& actual) { + if (declared.isAny() || actual.isAny() || declared.kind == actual.kind) { + return true; + } + bool const integer = actual.kind == TypeKind::Int; + return (declared.kind == TypeKind::Decimal && integer) || + (declared.kind == TypeKind::Key && (integer || actual.kind == TypeKind::String)); +} + +// NOLINTBEGIN(misc-no-recursion): a document is a tree of scopes, nodes and command lists, and checking descends it. +/// @brief Checks a parsed document against its own names and the catalog: every load-time rule that needs more +/// than one place in the document. +class DocumentValidator { +public: + /// @brief Validates @p doc. + /// @param doc The parsed document. + /// @param options The catalog facts. + DocumentValidator(Document const& doc, LoadOptions const& options) : _doc{&doc}, _options{&options} {} + + /// @brief Runs every rule; throws `DocumentRefused` on the first refusal. + void run() { + ScopeInfo& screen = newScope(nullptr, false); + screen.screen = true; + for (auto const& [name, type] : _doc->params) { + NameEntry entry; + entry.category = NameCategory::Param; + entry.path = pointerAppend("/params", name); + entry.type = type; + add(screen, name, std::move(entry)); + } + declare(_doc->scope, screen); + for (auto const& [key, commands] : _doc->lifecycle) { + static_cast(key); + collectTransfers(commands, screen); + } + for (auto const& [chord, commands] : _doc->keys) { + static_cast(chord); + collectTransfers(commands, screen); + } + if (_doc->view) { + collect(*_doc->view, screen); + } + for (DocNodePtr const& part : headParts()) { + collectPart(*part, screen, screen, *part); + } + std::vector componentScopes; + for (auto const& [name, component] : _doc->components) { + static_cast(name); + ScopeInfo& fallbackScope = newScope(nullptr, false); + collect(*component.fallback, fallbackScope); + componentScopes.push_back(&fallbackScope); + } + + CheckContext const root{ + .scope = &screen, + .commands = false, + .boundaryError = false, + .onClose = false, + .bindings = {}, + }; + checkScope(_doc->scope, root); + if (_doc->title) { + checkExpr(*_doc->title, root); + } + if (_doc->identity) { + checkExpr(*_doc->identity, root); + } + if (_doc->dirty) { + checkCondition(*_doc->dirty, root, "`dirty`"); + } + if (_doc->titleSpans) { + checkExpr(*_doc->titleSpans, root); + checkSpans(_doc->titleSpans); + } + if (_doc->eyebrow) { + checkExpr(*_doc->eyebrow, root); + } + if (_doc->eyebrowSpans) { + checkExpr(*_doc->eyebrowSpans, root); + checkSpans(_doc->eyebrowSpans); + } + if (_doc->subtitle) { + checkExpr(*_doc->subtitle, root); + } + if (_doc->subtitleSpans) { + checkExpr(*_doc->subtitleSpans, root); + checkSpans(_doc->subtitleSpans); + } + if (_doc->leadPlacement) { + checkExpr(*_doc->leadPlacement, root); + } + if (_doc->titleRole) { + checkExpr(*_doc->titleRole, root); + } + if (_doc->headSurface) { + checkExpr(*_doc->headSurface, root); + } + if (_doc->pageSurface) { + checkExpr(*_doc->pageSurface, root); + } + if (_doc->menuLabel) { + checkExpr(*_doc->menuLabel, root); + } + for (DocNodePtr const& part : headParts()) { + checkElement(*part, root, true); + } + checkActionButtons(_doc->actions, "/actions"); + std::set menuIds; + checkHeadMenu(_doc->menu, menuIds); + checkHeadTools(_doc->tools); + for (auto const& [key, commands] : _doc->lifecycle) { + CheckContext context = root; + context.onClose = key == "onClose"; + checkCommands(commands, context); + } + for (auto const& [chord, commands] : _doc->keys) { + static_cast(chord); + checkCommands(commands, root); + } + checkPrefetch(); + if (_doc->view) { + checkNode(*_doc->view, root); + } + std::size_t index = 0; + for (auto const& [name, component] : _doc->components) { + static_cast(name); + CheckContext context{ + .scope = componentScopes.at(index++), + .commands = false, + .boundaryError = false, + .onClose = false, + .bindings = {}, + }; + context.bindings.emplace_back("props", Type::of(TypeKind::Record)); + checkNode(*component.fallback, context); + } + checkCustomizePoints(); + checkWatchGraph(); + checkEffects(); + } + + /// @brief What validation found that does not refuse the document. + /// @return The warnings, in the order found; the validator keeps none. + [[nodiscard]] std::vector takeWarnings() noexcept { return std::move(_warnings); } + + /// @brief The static type of each date input's `value` that the checker could decide. + /// @return The table, keyed by node; the validator keeps none. + [[nodiscard]] std::map takeDateValueKinds() noexcept { + return std::move(_dateValueKinds); + } + + /// @brief Where each `focus` command's target resolved, keyed by the command's JSON Pointer. + /// @return The table; the validator keeps none. + [[nodiscard]] std::map> takeFocusTargets() noexcept { + return std::move(_focusTargets); + } + + /// @brief Finds a name in a scope chain. + /// @param scope The innermost scope. + /// @param name The name. + /// @return The entry, or `nullptr`. + [[nodiscard]] static NameEntry* lookup(ScopeInfo* scope, std::string_view name) { + for (ScopeInfo* current = scope; current != nullptr; current = current->parent) { + auto const found = current->names.find(name); + if (found != current->names.end()) { + return &found->second; + } + } + return nullptr; + } + + /// @brief The type of a name whose type is derived from an expression, derived on first use. + /// @param entry The state or `let` entry. + /// @param name Its name, for the cycle's description. + /// @return The type, or the cycle it closes. + [[nodiscard]] std::expected derivedType(NameEntry& entry, std::string_view name) { + if (entry.visit == 2 || !entry.derivedFrom) { + return entry.type; + } + if (entry.visit == 1) { + std::string cycle; + auto const start = std::ranges::find(_deriving, name); + for (auto step = start; step != _deriving.end(); ++step) { + cycle += *step + " → "; + } + std::string const graph = + entry.category == NameCategory::Let ? "the let graph has a cycle: " : "the state inits form a cycle: "; + return std::unexpected(graph + cycle + std::string{name}); + } + entry.visit = 1; + _deriving.emplace_back(name); + CheckContext const context{ + .scope = entry.scope, + .commands = false, + .boundaryError = false, + .onClose = false, + .bindings = {}, + }; + Type type = checkExpr(*entry.derivedFrom, context); + _deriving.pop_back(); + entry.visit = 2; + entry.type = type; + return type; + } + + /// @brief The document. + /// @return It. + [[nodiscard]] Document const& document() const noexcept { return *_doc; } + +private: + ScopeInfo& newScope(ScopeInfo* parent, bool row) { + ScopeInfo& made = _scopes.emplace_back(); + made.parent = parent; + made.row = row; + if (parent != nullptr) { + parent->children.push_back(&made); + } + return made; + } + + static void add(ScopeInfo& scope, std::string const& name, NameEntry entry) { + static constexpr std::array kReserved = { + "event", "app", "boundary", "props", "result", "body", + }; + if (listed(kReserved, name)) { + refuse(entry.path, "`" + name + "` is reserved and cannot be declared"); + } + auto const found = scope.names.find(name); + if (found != scope.names.end()) { + refuse(entry.path, "`" + name + "` is declared twice in this scope (first at " + found->second.path + ")"); + } + entry.scope = &scope; + scope.names.emplace(name, std::move(entry)); + } + + /// Checks a model alias against the catalog's facts, when there is a catalog. + void checkCatalog(ModelDecl const& model) { + if (!_options->catalog.model) { + return; + } + auto const info = _options->catalog.model(model.type); + if (!info) { + refuse(pointerAppend(model.path, "type"), "the model type `" + model.type + "` is not in the catalog"); + } + if (model.instance == InstanceMode::Shared && !info->stateless) { + refuse(pointerAppend(model.path, "instance"), + "the model type `" + model.type + + "` keeps state, so `shared` names no instance: it needs a key, or `private`"); + } + if (model.instance == InstanceMode::Keyed && !info->keyed) { + refuse(pointerAppend(model.path, "instance"), + "the model type `" + model.type + "` is not keyed, so its instance is not an expression"); + } + } + + void declare(ScopeDecl const& decl, ScopeInfo& scope) { + for (ModelDecl const& model : decl.models) { + if (scope.row && model.instance == InstanceMode::Default) { + refuse(model.path, "a model alias in a row scope names its `instance`"); + } + if (!scope.screen && model.instance == InstanceMode::Borrowed) { + refuse(model.path, "only a screen's own aliases borrow the opener's instance"); + } + checkCatalog(model); + NameEntry entry; + entry.category = NameCategory::Model; + entry.path = model.path; + entry.model = &model; + add(scope, model.name, std::move(entry)); + } + for (StateDecl const& state : decl.state) { + NameEntry entry; + entry.category = NameCategory::State; + entry.path = state.path; + entry.type = state.type; + entry.derivedFrom = state.typeDeclared ? nullptr : state.init; + add(scope, state.name, std::move(entry)); + } + for (LetDecl const& let : decl.lets) { + NameEntry entry; + entry.category = NameCategory::Let; + entry.path = let.path; + entry.derivedFrom = let.value; + add(scope, let.name, std::move(entry)); + } + for (QueryDecl const& query : decl.queries) { + NameEntry entry; + entry.category = NameCategory::Query; + entry.path = query.path; + entry.query = &query; + add(scope, query.name, std::move(entry)); + _queries.emplace(query.name, &query); + _queryScopes.emplace_back(&query, &scope); + } + for (MutationDecl const& mutation : decl.mutations) { + NameEntry entry; + entry.category = NameCategory::Mutation; + entry.path = mutation.path; + entry.mutation = &mutation; + add(scope, mutation.name, std::move(entry)); + _mutations.emplace_back(&mutation, &scope); + collectTransfers(mutation.onSuccess, scope); + collectTransfers(mutation.onError, scope); + } + for (WatchDecl const& watch : decl.watches) { + _watches.emplace_back(&watch, &scope); + collectTransfers(watch.body, scope); + } + } + + void collectTransfers(Commands const& commands, ScopeInfo& scope) { + for (Command const& cmd : commands) { + if (cmd.kind == CommandKind::Upload && !cmd.transfer.empty()) { + NameEntry entry; + entry.category = NameCategory::Transfer; + entry.path = pointerAppend(cmd.path, "id"); + add(scope, cmd.transfer, std::move(entry)); + } + collectTransfers(cmd.commands, scope); + collectTransfers(cmd.alternative, scope); + } + } + + void collect(DocNode const& node, ScopeInfo& scope) { collectIn(node, scope); } + + void collectIn(DocNode const& node, ScopeInfo& scope) { + KindSpec const* const spec = findKind(node.kind, false); + if (!node.id.empty()) { + NameEntry entry; + entry.category = NameCategory::Element; + entry.path = pointerAppend(node.path, "id"); + entry.element = &node; + add(scope, node.id, std::move(entry)); + _elements.emplace(node.id, &node); + } + ScopeInfo* inner = &scope; + if (spec != nullptr && (spec->flags & kScope) != 0) { + inner = &newScope(&scope, (spec->flags & kRowScope) != 0); + _scopeOf.emplace(&node, inner); + // NOLINTNEXTLINE(bugprone-unchecked-optional-access): the parser gives every scope-creating node a scope. + declare(*node.scope, *inner); + } + _innerOf.emplace(&node, inner); + for (auto const& [key, commands] : node.events) { + collectTransfers(commands, isInner(spec, key) ? *inner : scope); + } + for (auto const& [chord, commands] : node.keys) { + static_cast(chord); + collectTransfers(commands, scope); + } + for (auto const& [key, nodes] : node.children) { + for (DocNodePtr const& child : nodes) { + collectIn(*child, isInner(spec, key) ? *inner : scope); + } + } + for (auto const& [key, parts] : node.parts) { + for (DocNodePtr const& child : parts) { + collectPart(*child, isInner(spec, key) ? *inner : scope, *inner, node); + } + } + } + + void collectPart(DocNode const& part, ScopeInfo& outer, ScopeInfo& ownerInner, DocNode const& owner) { + KindSpec const* const spec = findKind(part.kind, true); + ScopeInfo* inner = &ownerInner; + if (spec != nullptr && (spec->flags & kScope) != 0) { + inner = &newScope(&outer, false); + inner->switchNode = owner.kind == "switch" ? &owner : nullptr; + _scopeOf.emplace(&part, inner); + // NOLINTNEXTLINE(bugprone-unchecked-optional-access): the parser gives every switch case a scope. + declare(*part.scope, *inner); + } else if (spec != nullptr && (spec->flags & kRowScope) != 0) { + inner = &newScope(&outer, true); + } + _innerOf.emplace(&part, inner); + for (auto const& [key, commands] : part.events) { + collectTransfers(commands, outer); + } + for (auto const& [key, nodes] : part.children) { + for (DocNodePtr const& child : nodes) { + collectIn(*child, isInner(spec, key) ? *inner : outer); + } + } + for (auto const& [key, parts] : part.parts) { + static_cast(key); + for (DocNodePtr const& child : parts) { + collectPart(*child, outer, ownerInner, part); + } + } + } + + [[nodiscard]] static bool isInner(KindSpec const* spec, std::string_view key) { + if (spec == nullptr) { + return false; + } + auto const found = std::ranges::find(spec->keys, key, &KeySpec::key); + return found != spec->keys.end() && (found->flags & kInner) != 0; + } + + /// The flags of a child-node key. The parser fills `children` only from a kind's own keys, so the kind and the key + /// are always found. + [[nodiscard]] static std::uint8_t keyFlags(KindSpec const& spec, std::string_view key) { + return std::ranges::find(spec.keys, key, &KeySpec::key)->flags; + } + + [[nodiscard]] static bool isCondition(KindSpec const* spec, std::string_view key) { + auto const shapeOf = [key](std::span keys) { + auto const found = std::ranges::find(keys, key, &KeySpec::key); + return found == keys.end() ? Shape::Expr : found->shape; + }; + return (spec != nullptr && shapeOf(spec->keys) == Shape::Condition) || + shapeOf(kCommonKeys) == Shape::Condition || shapeOf(kFieldKeys) == Shape::Condition; + } + + Type checkExpr(Expr const& expr, CheckContext const& context) { + ScopeResolver const resolver{*this, context}; + auto checked = checkExpression(expr, resolver); + if (!checked) { + throw DocumentRefused{std::move(checked.error())}; + } + return std::move(*checked); + } + + void checkCondition(Expr const& expr, CheckContext const& context, std::string_view what) { + Type const type = checkExpr(expr, context); + if (!compatible(Type::of(TypeKind::Bool), type)) { + refuse(expr.path, std::string{what} + " is " + type.name() + "; expected bool"); + } + } + + // A date input shows a timestamp or an ISO-8601 date or date-time string; any other type it can never show. + void checkDateValue(DocNode const& node, Expr const& expr, Type const& type) { + if (type.kind == TypeKind::String || type.kind == TypeKind::Timestamp) { + _dateValueKinds.insert_or_assign(&node, type.kind); + } else if (type.kind != TypeKind::Any && type.kind != TypeKind::Key) { + refuse(expr.path, + "`dateTimeInput` shows a timestamp or an ISO-8601 date or date-time string; `value` is " + + type.name()); + } + } + + [[nodiscard]] static NameEntry& require(CheckContext const& context, std::string const& name, + std::string const& path, std::initializer_list categories, + std::string_view what) { + NameEntry* const entry = lookup(context.scope, name); + if (entry == nullptr || std::ranges::find(categories, entry->category) == categories.end()) { + refuse(path, "`" + name + "` is not " + std::string{what} + " of this scope"); + } + return *entry; + } + + // How many row scopes enclose @p scope, itself included, up to its screen or component fallback. + [[nodiscard]] static std::size_t rowDepth(ScopeInfo const* scope) { + std::size_t rows = 0; + for (; scope != nullptr; scope = scope->parent) { + rows += scope->row ? 1U : 0U; + } + return rows; + } + + // The element @p name declares in @p scope itself, or nothing. + [[nodiscard]] static NameEntry const* elementIn(ScopeInfo const& scope, std::string_view name) { + auto const found = scope.names.find(name); + return found != scope.names.end() && found->second.category == NameCategory::Element ? &found->second + : nullptr; + } + + // The elements named @p name in the switch cases below @p scope, at any depth through cases only. + // NOLINTNEXTLINE(misc-no-recursion): the scope tree, walked down through switch cases. + static void elementsInCases(ScopeInfo const& scope, std::string_view name, std::vector& out) { + for (ScopeInfo const* const child : scope.children) { + if (child->switchNode == nullptr) { + continue; + } + if (NameEntry const* const entry = elementIn(*child, name)) { + out.push_back(entry); + } + elementsInCases(*child, name, out); + } + } + + // The row scopes directly below @p scope, or below it through switch cases, that declare the element @p name. + // NOLINTNEXTLINE(misc-no-recursion): the scope tree, walked down through switch cases. + static void rowScopesBelow(ScopeInfo const& scope, std::string_view name, std::vector& out) { + for (ScopeInfo const* const child : scope.children) { + if (child->row) { + if (elementIn(*child, name) != nullptr && std::ranges::find(out, child) == out.end()) { + out.push_back(child); + } + } else if (child->switchNode != nullptr) { + rowScopesBelow(*child, name, out); + } + } + } + + // A `focus` target resolves to declarations. Without `row`: the element the scope chain names, else those in the + // switch cases below the chain, which must all be cases of one switch (at most one case is mounted). With `row`: + // the one row scope that declares it among the chain's and those below the chain through switch cases. + void checkFocus(Command const& cmd, CheckContext const& context) { + FocusTarget target{.candidates = {}, .row = cmd.extra != nullptr}; + if (cmd.extra) { + checkExpr(*cmd.extra, context); + std::vector found; + for (ScopeInfo const* scope = context.scope; scope != nullptr; scope = scope->parent) { + if (scope->row && elementIn(*scope, cmd.target) != nullptr && + std::ranges::find(found, scope) == found.end()) { + found.push_back(scope); + } + rowScopesBelow(*scope, cmd.target, found); + } + if (found.empty()) { + refuse(pointerAppend(cmd.path, "row"), "`row` names a row of a `forEach` or table; `" + cmd.target + + "` is not an element of a row scope this command reaches"); + } + if (found.size() > 1) { + refuse(cmd.path, "`" + cmd.target + "` is declared in two row scopes this command reaches, at " + + elementIn(*found.at(0), cmd.target)->path + " and " + + elementIn(*found.at(1), cmd.target)->path); + } + target.candidates.push_back(FocusCandidate{ + .path = elementIn(*found.front(), cmd.target)->element->path, + .rows = rowDepth(found.front()), + }); + } else if (lookup(context.scope, cmd.target) != nullptr) { + NameEntry const& entry = require(context, cmd.target, cmd.path, {NameCategory::Element}, "an element"); + target.candidates.push_back(FocusCandidate{.path = entry.element->path, .rows = rowDepth(entry.scope)}); + } else { + std::vector inCases; + for (ScopeInfo const* scope = context.scope; scope != nullptr; scope = scope->parent) { + elementsInCases(*scope, cmd.target, inCases); + } + if (inCases.empty()) { + static_cast(require(context, cmd.target, cmd.path, {NameCategory::Element}, "an element")); + } + for (NameEntry const* const entry : inCases) { + if (entry->scope->switchNode != inCases.front()->scope->switchNode) { + refuse(cmd.path, "`" + cmd.target + "` is declared in the cases of two switches, at " + + inCases.front()->path + " and " + entry->path + + "; both may be mounted, so a focus cannot choose"); + } + target.candidates.push_back( + FocusCandidate{.path = entry->element->path, .rows = rowDepth(entry->scope)}); + } + } + _focusTargets.insert_or_assign(cmd.path, std::move(target)); + } + + // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the alias, then the action it runs, as a query reads. + std::optional checkModelAction(CheckContext const& context, std::string const& alias, + std::string const& action, std::string const& path) { + std::string const modelPath = pointerAppend(path, "model"); + NameEntry const& model = require(context, alias, modelPath, {NameCategory::Model}, "a model alias"); + if (!_options->catalog.action) { + return std::nullopt; + } + auto const info = _options->catalog.action(action); + if (!info) { + refuse(path, "the action `" + action + "` is not in the catalog"); + } + if (info->modelType != model.model->type) { + refuse(path, "the action `" + action + "` belongs to `" + info->modelType + "`, not `" + + model.model->type + "`"); + } + return info; + } + + void checkScope(ScopeDecl const& decl, CheckContext const& context) { + for (ModelDecl const& model : decl.models) { + if (model.key) { + checkExpr(*model.key, context); + } + } + for (StateDecl const& state : decl.state) { + if (!state.init) { + continue; + } + Type const type = checkExpr(*state.init, context); + bool const literalFits = state.init->kind != ExprKind::Literal || state.type.admits(state.init->literal); + if (!literalFits || !compatible(state.type, type)) { + refuse(state.init->path, + "the init of `" + state.name + "` does not have its type " + state.type.name()); + } + // The type is derived now, so a state no expression reads is still checked. + auto const derived = derivedType(*lookup(context.scope, state.name), state.name); + static_cast(derived); + } + for (LetDecl const& let : decl.lets) { + auto const type = derivedType(*lookup(context.scope, let.name), let.name); + static_cast(type); + } + for (QueryDecl const& query : decl.queries) { + checkQuery(query, context); + } + for (MutationDecl const& mutation : decl.mutations) { + checkMutation(mutation, context); + } + for (WatchDecl const& watch : decl.watches) { + checkExpr(*watch.on, context); + checkCommands(watch.body, context); + } + for (CheckDecl const& check : decl.checks) { + checkCondition(*check.assertion, context, "the `assert` of a check"); + if (check.message) { + checkExpr(*check.message, context); + } + for (std::size_t index = 0; index < check.targets.size(); ++index) { + static_cast(require(context, check.targets.at(index), + pointerAppend(pointerAppend(check.path, "targets"), index), + {NameCategory::Element}, "an element")); + } + } + } + + void checkQuery(QueryDecl const& query, CheckContext const& context) { + auto const action = checkModelAction(context, query.model, query.action, query.path); + // An evaluation runs no handler, so only a call can change anything. + if (action && action->effects && !query.evaluate) { + refuse(query.path, std::format("a query reads, so its action declares no effects; `{}` declares {}, " + "so it runs as a mutation", + query.action, describeEffects(*action->effects))); + } + if (query.body) { + checkExpr(*query.body, context); + } + if (query.when) { + checkCondition(*query.when, context, "`when`"); + } + } + + void checkMutation(MutationDecl const& mutation, CheckContext const& context) { + auto const action = checkModelAction(context, mutation.model, mutation.action, mutation.path); + if (mutation.body) { + checkExpr(*mutation.body, context); + } + if (mutation.serialKey) { + CheckContext keyContext = context; + keyContext.bindings.emplace_back("body", Type::any()); + checkExpr(*mutation.serialKey, keyContext); + } + if (mutation.optimistic) { + OptimisticDecl const& decl = *mutation.optimistic; + std::string const path = pointerAppend(mutation.path, "optimistic"); + auto const target = _queries.find(decl.query); + if (target == _queries.end()) { + refuse(pointerAppend(path, "query"), "`" + decl.query + "` is not a query of this document"); + } + CheckContext bodyContext = context; + bodyContext.bindings.emplace_back("body", Type::any()); + checkExpr(*decl.key, bodyContext); + checkExpr(*decl.with, bodyContext); + checkPatchAt(decl.query, decl.at, *target->second, path); + checkOptimistic(decl, *target->second); + } + if (mutation.offlineQueue && action) { + if (action->credential || !action->secretFields.empty()) { + refuse(pointerAppend(mutation.path, "offline"), + "a mutation that sends a credential or returns a secret is never queued offline"); + } + } + checkCommands(mutation.onSuccess, context); + checkCommands(mutation.onError, context); + } + + // Only a catalog that knows the result is a record can say a patch misses its list; otherwise the interpreter + // reports the miss when the patch runs. + // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the query's name, then the member holding the list. + void checkPatchAt(std::string const& queryName, std::string const& listMember, QueryDecl const& query, + std::string const& path) { + if (!_options->catalog.action) { + return; + } + auto const info = _options->catalog.action(query.action); + if (!info || !info->listFields) { + return; + } + if (listMember.empty()) { + refuse(path, std::format("`{}` answers a record, so a patch of `{}` names the member holding its list " + "with `at`", + query.action, queryName)); + } + if (std::ranges::find(*info->listFields, listMember) == info->listFields->end()) { + refuse(pointerAppend(path, "at"), + std::format("the result of `{}` has no list member `{}`", query.action, listMember)); + } + } + + void checkOptimistic(OptimisticDecl const& decl, QueryDecl const& query) { + if (!_options->catalog.action || decl.with->kind != ExprKind::Object) { + return; + } + auto const info = _options->catalog.action(query.action); + if (!info) { + return; + } + for (auto const& [field, value] : decl.with->fields) { + if (std::ranges::find(info->calculatedFields, field) != info->calculatedFields.end()) { + refuse(value->path, + std::format("`{}` is calculated by the server and is never written optimistically", field)); + } + } + } + + void checkPrefetch() { + for (std::size_t index = 0; index < _doc->prefetch.size(); ++index) { + std::string const& name = _doc->prefetch.at(index); + std::string const path = pointerAppend("/prefetch", index); + auto const found = std::ranges::find(_doc->scope.queries, name, &QueryDecl::name); + if (found == _doc->scope.queries.end()) { + refuse(path, "`" + name + "` is not a query of the screen"); + } + if (found->body && !readsOnlyParams(*found->body)) { + refuse(path, "the body of `" + name + "` reads more than the screen's params, so it cannot prefetch"); + } + } + } + + [[nodiscard]] bool readsOnlyParams(Expr const& expr) const { + if (expr.kind == ExprKind::Ref) { + return std::ranges::find(_doc->params, expr.name, &std::pair::first) != + _doc->params.end(); + } + if (expr.kind != ExprKind::Literal && expr.kind != ExprKind::Call && expr.kind != ExprKind::If && + expr.kind != ExprKind::Object && expr.kind != ExprKind::List && expr.kind != ExprKind::Get) { + return false; + } + bool only = true; + for (ExprPtr const& arg : expr.args) { + only = only && readsOnlyParams(*arg); + } + for (auto const& [name, field] : expr.fields) { + static_cast(name); + only = only && readsOnlyParams(*field); + } + return only; + } + + void checkCustomizePoints() { + std::set> arranged; + for (auto const& [name, point] : _doc->customize) { + static_cast(name); + if (point.kind == "columns" && _doc->view) { + auto const found = _elements.find(point.of); + if (found == _elements.end() || found->second->kind != "table") { + refuse(pointerAppend(point.path, "of"), + "a `columns` point names a table; `" + point.of + "` is not one"); + } + } + if (point.kind == "arrange") { + checkArranged(point, arranged); + } + } + } + + // The stored order names children by id, so the container is a stack whose every child has one, and one point + // orders it: two would each claim the order. + void checkArranged(CustomizePoint const& point, std::set>& arranged) { + auto const found = _elements.find(point.of); + if (found == _elements.end() || (found->second->kind != "column" && found->second->kind != "row") || + found->second->nodes("children").empty()) { + refuse(pointerAppend(point.path, "of"), + "an `arrange` point names a column or row of this screen that has children; `" + point.of + + "` is not one"); + } + for (DocNodePtr const& child : found->second->nodes("children")) { + if (child->id.empty()) { + refuse(pointerAppend(point.path, "of"), + "an `arrange` point orders its container's children by id; a child of `" + point.of + + "` has none"); + } + } + // An arranged container is drawn as a keyed list, which places its children as a list does. + std::string const asList = + "an arranged `" + found->second->kind + "` is drawn as a list, which takes no `align` or `justify`"; + for (std::string_view const key : {"align", "justify"}) { + if (!found->second->name(key).empty()) { + refuse(pointerAppend(found->second->path, key), asList); + } + } + if (!arranged.insert(point.of).second) { + refuse(pointerAppend(point.path, "of"), "`" + point.of + "` is arranged by another point"); + } + } + + [[nodiscard]] CheckContext innerContext(DocNode const& node, CheckContext const& context) const { + CheckContext inner = context; + inner.scope = _innerOf.at(&node); + return inner; + } + + void checkNode(DocNode const& node, CheckContext const& context) { + if (node.kind == "pageRegion") { + refuse(node.path, "a page region belongs in a page"); + } + if (!node.name("alignSelf").empty()) { + refuse(pointerAppend(node.path, "alignSelf"), std::string{kAlignSelfPlaces}); + } + if (node.flag("bleed")) { + refuse(pointerAppend(node.path, "bleed"), std::string{kBleedPlaces}); + } + checkElement(node, context, false); + } + + // What `alignSelf` places a node in. + static constexpr std::string_view kAlignSelfPlaces = "`alignSelf` places a node in its row, column or grid"; + + // What `bleed` reaches past: the horizontal padding of the stack, panel or tab page that holds the node. + static constexpr std::string_view kBleedPlaces = "`bleed` is a child's of a column, a panel or a tab"; + + // Whether the nodes under @p key of @p parent may be sized by a share of its width: a row that does not wrap, a + // splitter that is not literally vertical, and a `forEach` that is literally horizontal and does not wrap (its + // rows are the children of a row). + static bool takesPercent(DocNode const& parent, std::string_view key) { + // The content of a switch case or of an overlay is mounted into a holder that fills its slot: the interpreter + // reports a share there and makes the node fill, so the loader leaves it to the interpreter. + if (parent.kind == "case" || parent.kind == "switch" || parent.kind == "dialog" || parent.kind == "drawer") { + return true; + } + if (key != "children") { + return false; + } + if (parent.kind == "row") { + return !parent.flag("wrap"); + } + if (parent.kind == "splitter") { + ExprPtr const orientation = parent.prop("orientation"); + if (orientation != nullptr && orientation->kind == ExprKind::Literal) { + std::string const* const named = orientation->literal.asString(); + return named == nullptr || *named != "vertical"; + } + return true; + } + if (parent.kind == "forEach") { + ExprPtr const axis = parent.prop("axis"); + if (axis == nullptr || axis->kind != ExprKind::Literal) { + return false; + } + std::string const* const named = axis->literal.asString(); + return named != nullptr && *named == "horizontal" && !parent.flag("wrap"); + } + return false; + } + + // A child that places itself sits in a row, a column, a grid or a `forEach`; any other parent (a panel, a dialog, + // a tab page) has no cross axis to place it on. + static void checkPlacements(DocNode const& parent) { + bool const places = parent.kind == "row" || parent.kind == "column" || parent.kind == "grid" || + parent.kind == "forEach" || parent.kind == "actionBar"; + bool const bleeds = parent.kind == "column" || parent.kind == "panel" || parent.kind == "tab"; + for (auto const& [key, nodes] : parent.children) { + for (DocNodePtr const& child : nodes) { + if (child->kind == "pageRegion" && parent.kind != "page") { + refuse(child->path, "a page region belongs in a page"); + } + if (!child->name("alignSelf").empty() && (!places || key != "children")) { + refuse(pointerAppend(child->path, "alignSelf"), std::string{kAlignSelfPlaces}); + } + if (child->flag("bleed") && (!bleeds || key != "children")) { + refuse(pointerAppend(child->path, "bleed"), std::string{kBleedPlaces}); + } + if (hasPercentWidth(*child) && !takesPercent(parent, key)) { + refuse(pointerAppend(child->path, "sizing"), std::string{kPercentPlaces}); + } + } + } + } + + // A tab page's padding is `pageInset`, else `inset`, both literal steps. A page of no padding has nothing for a + // child's `bleed` to reach past, so the document is refused rather than the flag silently doing nothing; a step + // that is computed is left to the mount. Any node that is not a `tabs` is passed over. + static void checkTabBleed(DocNode const& tabs) { + if (tabs.kind != "tabs") { + return; + } + auto const step = [&tabs](std::string_view key) -> std::optional { + ExprPtr const expr = tabs.prop(key); + if (expr == nullptr) { + return std::nullopt; + } + std::int64_t const* const literal = expr->kind == ExprKind::Literal ? expr->literal.asInt() : nullptr; + return literal != nullptr ? std::optional{*literal} : std::optional{-1}; + }; + auto const page = step("pageInset"); + auto const outer = step("inset"); + std::int64_t const effective = page.value_or(outer.value_or(0)); + if (effective != 0) { + return; + } + for (DocNodePtr const& tab : tabs.partList("tabs")) { + auto const found = tab->children.find("children"); + if (found == tab->children.end()) { + continue; + } + for (DocNodePtr const& child : found->second) { + if (child->flag("bleed")) { + refuse(pointerAppend(child->path, "bleed"), + "`bleed` reaches past the padding of the tab page, and this page has none: give the tabs " + "a `pageInset`, or an `inset`, above 0"); + } + } + } + } + + void checkElement(DocNode const& node, CheckContext const& outer, bool part) { + KindSpec const* const spec = findKind(node.kind, part); + CheckContext const inner = innerContext(node, outer); + if (auto const found = _scopeOf.find(&node); found != _scopeOf.end()) { + // NOLINTNEXTLINE(bugprone-unchecked-optional-access): a node or case with a scope of its own has its declarations. + checkScope(*node.scope, inner); + } + checkProps(node, spec, inner, outer); + for (auto const& [key, commands] : node.events) { + if (node.kind == "custom") { + checkCustomEvent(node, key.substr(3), node.path); + } + checkCommands(commands, isInner(spec, key) ? inner : outer); + } + for (auto const& [chord, commands] : node.keys) { + static_cast(chord); + checkCommands(commands, outer); + } + for (auto const& [key, nodes] : node.children) { + CheckContext context = isInner(spec, key) ? inner : outer; + context.boundaryError = (keyFlags(*spec, key) & kBoundaryError) != 0 || context.boundaryError; + for (DocNodePtr const& child : nodes) { + checkElement(*child, context, false); + } + } + for (auto const& [key, parts] : node.parts) { + CheckContext const& context = isInner(spec, key) ? inner : outer; + for (DocNodePtr const& child : parts) { + checkElement(*child, context, true); + } + } + checkPlacements(node); + checkTabBleed(node); + if (part) { + checkPartNode(node); + } else { + checkFlags(node); + checkLayoutKeys(node); + checkKindRules(node, outer); + // An overlay's footer actions; a form's field components. + checkActionButtons(node.partList("actions"), pointerAppend(node.path, "actions")); + checkFieldComponents(node); + } + } + + static void checkPartNode(DocNode const& node) { + if (node.kind == "column" || node.kind == "track") { + checkNoPercentWidth(node); + } + if (node.kind == "column") { + checkColumnPart(node); + } else if (node.kind == "track") { + checkCellPlace(node, "align"); + } else if (isMenuEntry(node.kind)) { + checkMenuItem(node); + } + } + + void checkProps(DocNode const& node, KindSpec const* spec, CheckContext const& inner, CheckContext const& outer) { + for (auto const& [key, expr] : node.props) { + CheckContext const& context = isInner(spec, key) ? inner : outer; + if (isCondition(spec, key)) { + checkCondition(*expr, context, "`" + key + "`"); + continue; + } + Type const type = checkExpr(*expr, context); + if (node.kind == "dateTimeInput" && key == "value") { + checkDateValue(node, *expr, type); + } + } + } + + void checkCustomEvent(DocNode const& node, std::string const& event, std::string const& path) { + auto const found = _doc->components.find(node.name("name")); + if (found != _doc->components.end() && !found->second.events.contains(event)) { + refuse(pointerAppend(pointerAppend(path, "on"), event), + "the component `" + found->second.name + "` declares no event `" + event + "`"); + } + } + + // What a chart's literal keys may be, and the shape of its series and lines. A computed `tone` or `yMin` is + // checked when it is evaluated, and reported then. + // NOLINTNEXTLINE(readability-function-cognitive-complexity): one check per chart key, in the order the keys are read. + static void checkChart(DocNode const& node) { + static constexpr std::size_t kMaxSeries = 4; + static constexpr std::size_t kMaxLines = 16; + std::span const series = node.partList("series"); + std::string const seriesPath = pointerAppend(node.path, "series"); + if (series.empty() || series.size() > kMaxSeries) { + refuse(seriesPath, "a chart draws 1 to 4 series"); + } + if (node.partList("lines").size() > kMaxLines) { + refuse(pointerAppend(node.path, "lines"), "a chart draws at most 16 reference lines"); + } + bool const positioned = series.front()->prop("x") != nullptr; + for (DocNodePtr const& part : series) { + DocNode const& one = *part; + if (series.size() > 1 && one.prop("label") == nullptr) { + refuse(one.path, "each of two or more series has a `label`, its name in the legend"); + } + if ((one.prop("x") != nullptr) != positioned) { + refuse(one.path, "`x` is on every series of a chart or on none"); + } + checkChartTone(one); + std::string_view const style = one.name("style"); + if (!style.empty() && style != "line" && style != "bars") { + refuse(pointerAppend(one.path, "style"), "a series `style` is `line` or `bars`"); + } + if (style == "bars" && one.flag("joined")) { + refuse(pointerAppend(one.path, "joined"), "a `bars` series is not joined"); + } + } + for (DocNodePtr const& line : node.partList("lines")) { + checkChartTone(*line); + std::string_view const style = line->name("style"); + if (!style.empty() && style != "solid" && style != "dashed" && style != "dotted") { + refuse(pointerAppend(line->path, "style"), "`style` is `solid`, `dashed` or `dotted`"); + } + } + if (ExprPtr const places = node.prop("yPlaces")) { + std::int64_t const* const literal = places->kind == ExprKind::Literal ? places->literal.asInt() : nullptr; + if (literal == nullptr || *literal < 0 || std::cmp_greater(*literal, math::kMaxDecimalPlaces)) { + refuse(places->path, "`yPlaces` is a literal integer from 0 to 18"); + } + } + ExprPtr const low = node.prop("yMin"); + ExprPtr const high = node.prop("yMax"); + if (low && high && low->kind == ExprKind::Literal && high->kind == ExprKind::Literal) { + std::optional const lowNumber = numeric(low->literal); + std::optional const highNumber = numeric(high->literal); + if (lowNumber && highNumber && highNumber->value < lowNumber->value) { + refuse(low->path, "`yMin` is above `yMax`"); + } + } + } + + // A literal `tone` of a chart's series or line names one of the five tones; `null` marks nothing. + static void checkChartTone(DocNode const& part) { + ExprPtr const tone = part.prop("tone"); + if (!tone || tone->kind != ExprKind::Literal || tone->literal.isNull()) { + return; + } + static constexpr std::array kTones = {"neutral", "info", "ok", "warn", "err"}; + std::string const* const name = tone->literal.asString(); + if (name == nullptr || !listed(kTones, *name)) { + refuse(tone->path, "`tone` is `neutral`, `info`, `ok`, `warn` or `err`"); + } + } + + // A flag that needs a key beside it. + static void checkFlags(DocNode const& node) { + if (node.flag("showLabel") && node.prop("label") == nullptr) { + refuse(pointerAppend(node.path, "showLabel"), "`showLabel` shows the `label`, and the node gives none"); + } + } + + void checkKindRules(DocNode const& node, CheckContext const& context) { + if (node.kind == "custom") { + checkCustomProps(node); + } else if (node.kind == "tabs") { + checkTabIds(node); + checkTabsInset(node); + } else if (node.kind == "chart") { + checkChart(node); + } else if (node.kind == "page") { + checkPage(node); + } else if (node.kind == "localeScope") { + checkLocaleScope(node); + } else if (node.kind == "customize" && !_doc->customize.contains(node.name("point"))) { + refuse(pointerAppend(node.path, "point"), + "`" + std::string{node.name("point")} + "` is not a customization point of this document"); + } + checkKindValues(node); + checkSheet(node); + std::string_view const model = node.name("model"); + if (!model.empty()) { + if (node.name("action").empty()) { + refuse(node.path, "a `" + node.kind + "` with a `model` names its `action`"); + } + checkModelAction(context, std::string{model}, std::string{node.name("action")}, node.path); + } else if (node.kind == "table" && !node.prop("rows")) { + refuse(node.path, "a table takes `rows`, or a `model` and `action`"); + } + if (node.kind == "table") { + checkTableSelection(node); + checkSelectColumn(node); + checkTableSort(node); + checkTablePaging(node); + checkTableGroup(node); + checkRowsTableKeys(node); + } + } + + // Whether a node gives the common key @p key. + static bool gives(DocNode const& node, std::string_view key) { + return node.props.contains(key) || node.names.contains(key) || node.flags.contains(key) || + node.parts.contains(key) || (key == "keys" && !node.keys.empty()) || (key == "id" && !node.id.empty()); + } + + // The common keys a page node does not take, each refused where it is written. + static void refuseKeys(DocNode const& node, std::span keys, std::string_view why) { + for (std::string_view const key : keys) { + if (gives(node, key)) { + refuse(pointerAppend(node.path, key), "`" + std::string{key} + "` " + std::string{why}); + } + } + } + + // A page holds regions and nothing else, each valid on the sheet; the sheet sizes itself. + static void checkPage(DocNode const& node) { + static constexpr std::array kRefused = { + "sizing", "minWidth", "maxWidth", "minHeight", "maxHeight", "bleed", "drag", "drop", "autofocus", + }; + refuseKeys(node, kRefused, "is refused on a page: the sheet is sized by its geometry"); + if (node.name("alignSelf") == "stretch") { + refuse(pointerAppend(node.path, "alignSelf"), "a page is never stretched; `alignSelf` places the sheet"); + } + PageGeometry const page = pageGeometryOf(node); + for (DocNodePtr const& child : node.nodes("children")) { + if (child->kind != "pageRegion") { + refuse(child->path, "a page holds page regions and nothing else"); + } + static constexpr std::array kRegionRefused = { + "sizing", "minWidth", "maxWidth", "minHeight", "maxHeight", "alignSelf", + "bleed", "span", "drag", "drop", "autofocus", + }; + refuseKeys(*child, kRegionRefused, "is refused on a page region: its geometry names its size"); + static_cast(regionGeometryOf(*child, page)); + } + } + + // A scope is not a widget, so it takes none of the keys every widget takes. + static void checkLocaleScope(DocNode const& node) { + for (KeySpec const& key : kCommonKeys) { + if (gives(node, key.key)) { + refuse(pointerAppend(node.path, key.key), + "`" + std::string{key.key} + + "` is refused on a locale scope: it is not a widget; wrap it in a " + "node that has one"); + } + } + } + + // A dialog's `sheet` and the label of its dismiss control: a drawer already fills the height on a phone and takes + // neither, and a `dismissLabel` labels only a sheet's control. + static void checkSheet(DocNode const& node) { + if (node.kind == "drawer") { + for (std::string_view const key : {"sheet", "dismissLabel"}) { + if (node.prop(key)) { + refuse(pointerAppend(node.path, key), + "`" + std::string{key} + "` is a dialog's; a drawer already fills the height"); + } + } + } else if (node.kind == "dialog" && node.prop("dismissLabel") && !node.prop("sheet")) { + refuse(pointerAppend(node.path, "dismissLabel"), + "`dismissLabel` labels a sheet's dismiss control; give the dialog `sheet`"); + } + } + + // A sortable column is named by its id, which a sort key gives; `sortBy` says how a sortable column orders. A + // literal `sort` names sortable columns, each once, with a direction, and `onSortChange` needs a header that + // sorts. A model-backed table's engine sorts, so none of these belongs on one. + static void checkTableSort(DocNode const& node) { + bool const modelBacked = !node.name("model").empty(); + std::set> sortable; + for (DocNodePtr const& column : node.partList("columns")) { + bool const sorts = column->flag("sortable"); + if (sorts && modelBacked) { + refuse(pointerAppend(column->path, "sortable"), + "a model-backed table's engine sorts; `sortable` is for a table over `rows`"); + } + if (sorts && column->id.empty()) { + refuse(pointerAppend(column->path, "sortable"), "a sortable column needs an `id`, which a sort names"); + } + if (column->prop("sortBy") != nullptr && !sorts) { + refuse(pointerAppend(column->path, "sortBy"), + "`sortBy` says how a sortable column orders the rows; give the column `sortable`"); + } + if (sorts) { + sortable.insert(column->id); + } + } + if (node.event("onSortChange") != nullptr && sortable.empty()) { + refuse(pointerAppend(node.path, "onSortChange"), + "`onSortChange` runs when a header sorts the table; give a column `sortable`"); + } + ExprPtr const sort = node.prop("sort"); + if (sort != nullptr && sort->kind == ExprKind::Literal && !modelBacked && !sort->literal.isNull()) { + checkLiteralSort(sort->literal, pointerAppend(node.path, "sort"), sortable); + } + } + + // A literal sort: a list of keys, each naming one of @p sortable once, with a direction. + static void checkLiteralSort(Value const& sort, std::string const& where, + std::set> const& sortable) { + ValueList const* const keys = sort.asList(); + if (keys == nullptr) { + refuse( + where, + R"(a table's sort is a list of keys, each {"column": , "direction": "asc" or "desc"})"); + } + std::set> named; + for (Value const& key : *keys) { + Value const* const column = key.field("column"); + Value const* const direction = key.field("direction"); + std::string const* const columnId = column == nullptr ? nullptr : column->asString(); + std::string const* const way = direction == nullptr ? nullptr : direction->asString(); + if (columnId == nullptr || way == nullptr || (*way != "asc" && *way != "desc")) { + refuse(where, R"(a sort key is {"column": , "direction": "asc" or "desc"})"); + } + if (!sortable.contains(*columnId)) { + refuse(where, "the sort names `" + *columnId + "`, which is not a sortable column"); + } + if (!named.insert(*columnId).second) { + refuse(where, "the sort names `" + *columnId + "` twice"); + } + } + } + + // A table over `rows` draws its own group headings; a model-backed table's engine shapes its rows. + static void checkTableGroup(DocNode const& node) { + if (!node.name("model").empty() && !node.partList("group").empty()) { + refuse(pointerAppend(node.path, "group"), + "a model-backed table's engine shapes its rows; `group` is for a table over `rows`"); + } + } + + // A table over `rows` pages itself by `pageSize`, at `page`; a model-backed table's engine pages. + static void checkTablePaging(DocNode const& node) { + ExprPtr const size = node.prop("pageSize"); + ExprPtr const page = node.prop("page"); + if (!node.name("model").empty() && (size != nullptr || page != nullptr)) { + refuse(pointerAppend(node.path, size != nullptr ? "pageSize" : "page"), + "a model-backed table's engine pages; `pageSize` and `page` are for a table over `rows`"); + } + if (page != nullptr && size == nullptr) { + refuse(pointerAppend(node.path, "page"), + "`page` picks a page of `pageSize` rows; give the table `pageSize`"); + } + if (size != nullptr && size->kind == ExprKind::Literal && !size->literal.isNull()) { + std::int64_t const* const rows = size->literal.asInt(); + if (rows == nullptr || *rows < 1) { + refuse(pointerAppend(node.path, "pageSize"), "a page holds a positive whole number of rows"); + } + } + } + + // The keys of a model-backed table that a table over `rows` would accept and ignore. + static void checkRowsTableKeys(DocNode const& node) { + if (!node.prop("rows")) { + return; + } + if (node.prop("filters") != nullptr) { + refuse(pointerAppend(node.path, "filters"), + "`filters` belongs to a model-backed table; filter `rows` with `filter`"); + } + if (node.prop("highlightKey") != nullptr) { + refuse(pointerAppend(node.path, "highlightKey"), "`highlightKey` links a model-backed table to a chart"); + } + } + + // The select column draws a `multiple` table's selection, so it needs a literal `multiple`; its header's name + // needs the column. + static void checkSelectColumn(DocNode const& node) { + bool const drawn = node.flag("selectColumn"); + if (drawn) { + ExprPtr const mode = node.prop("selectionMode"); + std::string const* const literal = + mode != nullptr && mode->kind == ExprKind::Literal ? mode->literal.asString() : nullptr; + if (literal == nullptr || *literal != "multiple") { + refuse(pointerAppend(node.path, "selectColumn"), + "a select column draws a table's selection of several rows; give it `selectionMode` " + "`multiple`"); + } + } + if (!drawn && node.prop("selectAllLabel") != nullptr) { + refuse(pointerAppend(node.path, "selectAllLabel"), + "`selectAllLabel` names the select column's header " + "box; give the table `selectColumn`"); + } + } + + // A table's `selection` and `onSelectionChange` need rows the user can select, and rows the document holds: a + // model-backed table's engine owns its selection. + static void checkTableSelection(DocNode const& node) { + std::string_view key; + if (node.prop("selection") != nullptr) { + key = "selection"; + } else if (node.event("onSelectionChange") != nullptr) { + key = "onSelectionChange"; + } else { + return; + } + std::string const where = pointerAppend(node.path, key); + if (!node.name("model").empty()) { + refuse(where, "a model-backed table's engine owns its selection; `" + std::string{key} + + "` is for a table over `rows`"); + } + ExprPtr const mode = node.prop("selectionMode"); + std::string const* const literal = + mode != nullptr && mode->kind == ExprKind::Literal ? mode->literal.asString() : nullptr; + if (mode == nullptr || (literal != nullptr && *literal == "none")) { + refuse(where, "a table with `" + std::string{key} + + "` selects rows; give it `selectionMode` `single` or `multiple`"); + } + } + + // A tabs node that names its shown tab, or reports a pick, keys every tab by a unique id; a literal `selected` + // names one of them. A literal `null` is no binding. + static void checkTabIds(DocNode const& node) { + ExprPtr const selected = node.prop("selected"); + bool const bound = selected != nullptr && (selected->kind != ExprKind::Literal || !selected->literal.isNull()); + bool const keyed = bound || node.event("onChoose") != nullptr; + std::set> ids; + for (DocNodePtr const& tab : node.partList("tabs")) { + if (tab->id.empty()) { + if (keyed) { + refuse(tab->path, "a tab of a tabs node with `selected` or `onChoose` has an `id`"); + } + continue; + } + if (!ids.insert(tab->id).second) { + refuse(pointerAppend(tab->path, "id"), + "the tab id `" + tab->id + "` is used twice; each tab has its own"); + } + } + if (bound && selected->kind == ExprKind::Literal) { + std::string const* const named = selected->literal.asString(); + if (named == nullptr || !ids.contains(*named)) { + refuse(pointerAppend(node.path, "selected"), "`selected` names no tab of this node"); + } + } + } + + // A tabs node's `inset` and `pageInset` are literal spacing steps, 0 to 5: the strip and the pages are laid out + // once. + static void checkTabsInset(DocNode const& node) { + for (std::string_view const key : {"inset", "pageInset"}) { + ExprPtr const inset = node.prop(key); + if (inset == nullptr) { + continue; + } + std::int64_t const* const step = inset->kind == ExprKind::Literal ? inset->literal.asInt() : nullptr; + if (step == nullptr || *step < 0 || *step > 5) { + refuse(pointerAppend(node.path, key), + "`" + std::string{key} + "` is a literal spacing step from 0 to 5"); + } + } + } + + // A custom node names a component of the document and gives only the props it declares. + void checkCustomProps(DocNode const& node) const { + auto const found = _doc->components.find(node.name("name")); + if (found == _doc->components.end()) { + refuse(pointerAppend(node.path, "name"), + "`" + std::string{node.name("name")} + "` is not a component of this document"); + } + for (DocNodePtr const& props : node.partList("props")) { + for (auto const& [prop, value] : props->props) { + if (!found->second.props.contains(prop)) { + refuse(value->path, "the component `" + found->first + "` declares no prop `" + prop + "`"); + } + } + } + } + + // A stack's literal `padding` list is two spacing steps, vertical then horizontal, each 0 to 5; a panel's is one + // step. A computed padding is read at mount. + static void checkPadding(DocNode const& node) { + ExprPtr const padding = node.prop("padding"); + if (padding == nullptr || padding->kind != ExprKind::Literal) { + return; + } + ValueList const* const list = padding->literal.asList(); + if (list == nullptr) { + return; + } + if (node.kind == "panel") { + refuse(pointerAppend(node.path, "padding"), "a panel's `padding` is one spacing step, not a list"); + } + // The largest spacing step, as `kMaxSpacingStep` (view.hpp) names it. + static constexpr std::int64_t kMostSteps = 5; + bool const steps = list->size() == 2 && std::ranges::all_of(*list, [](Value const& step) { + std::int64_t const* const whole = step.asInt(); + return whole != nullptr && *whole >= 0 && *whole <= kMostSteps; + }); + if (!steps) { + refuse(pointerAppend(node.path, "padding"), + "a `padding` list is two spacing steps, vertical then horizontal, each from 0 to 5"); + } + } + + // The closed-set keys of a button, and the shape and style pair that cannot go together. + static void checkButtonValues(DocNode const& node) { + static constexpr std::array kEmphasis = { + "normal", "primary", "danger", "ghost", "dangerOutline", + }; + checkChoice(node, "emphasis", kEmphasis); + static constexpr std::array kStyles = {"push", "item"}; + checkChoice(node, "style", kStyles); + static constexpr std::array kShapes = {"default", "round", "square"}; + checkChoice(node, "shape", kShapes); + if (node.name("shape") == "square" && node.name("style") == "item") { + refuse(pointerAppend(node.path, "shape"), + "an item fills its line, so it has no square outline; `square` is a push button's"); + } + static constexpr std::array kSizes = {"normal", "small"}; + checkChoice(node, "size", kSizes); + if (std::string_view const weight = node.name("weight"); !weight.empty() && !weightNamed(weight)) { + refuse(pointerAppend(node.path, "weight"), + "`" + std::string{weight} + "` is not a font weight name, such as `semi-bold`"); + } + checkEntryContent(node); + } + + // The keys of a kind that take one of a closed set of values, and the pairs of keys that need each other. + static void checkKindValues(DocNode const& node) { + if (node.kind == "column" || node.kind == "row" || node.kind == "panel") { + checkPadding(node); + } + if ((node.kind == "column" || node.kind == "row") && node.flag("headJoined") && !node.flag("pageEdge")) { + refuse(pointerAppend(node.path, "headJoined"), + "`headJoined` needs `pageEdge`: an inset page has a margin between it and the head"); + } + if (node.kind == "button") { + checkButtonValues(node); + } else if (node.kind == "grid") { + checkGrid(node); + } else if (node.kind == "actionBar") { + checkActionBar(node); + } else if (node.kind == "column" && node.flags.contains("wrap")) { + refuse(pointerAppend(node.path, "wrap"), "only a row wraps; a column has no lines to continue on"); + } else if (node.kind == "row" && node.flag("divided") && node.flag("wrap")) { + refuse(pointerAppend(node.path, "divided"), + "a wrapping row has no single line to rule between; `divided` is for a row that does not `wrap`"); + } else if (node.kind == "forEach") { + checkForEachWrap(node); + } else if (node.kind == "menu") { + checkMenu(node); + } else if (node.kind == "badge" && node.prop("removeLabel") != nullptr && node.event("onRemove") == nullptr) { + refuse(pointerAppend(node.path, "removeLabel"), + "`removeLabel` names a removable badge's remove control; the badge gives no `onRemove`"); + } else if (node.kind == "textInput") { + static constexpr std::array kCommit = {"change", "blur", "enter"}; + checkChoice(node, "commitOn", kCommit); + static constexpr std::array kInputEmphases = {"normal", "prominent"}; + checkChoice(node, "emphasis", kInputEmphases); + static constexpr std::array kInputAligns = {"start", "center", "end"}; + checkChoice(node, "align", kInputAligns); + checkMultilineExtras(node); + } else if (node.kind == "select") { + static constexpr std::array kStale = {"clear", "keep"}; + checkChoice(node, "onStale", kStale); + checkSelectStyle(node); + } else if (node.kind == "text") { + checkText(node); + } else if (node.kind == "banner") { + checkBanner(node); + } else if (node.kind == "badge") { + static constexpr std::array kBadgeStyles = {"filled", "outline", "quiet"}; + checkChoice(node, "style", kBadgeStyles); + static constexpr std::array kBadgeShapes = {"default", "round"}; + checkChoice(node, "shape", kBadgeShapes); + } else if (node.kind == "keyValue") { + static constexpr std::array kCaptionPlaces = {"inline", "stacked"}; + checkChoice(node, "fieldLayout", kCaptionPlaces); + checkCaptionWidth(node, node.name("fieldLayout") != "stacked"); + checkItemSpans(node.prop("items")); + } else if (node.kind == "table") { + checkCellPlace(node, "valign"); + } + if (node.kind == "form" || node.kind == "collection" || node.kind == "wizard") { + checkFormColumns(node); + static constexpr std::array kFieldLayouts = {"stacked", "inline"}; + checkChoice(node, "fieldLayout", kFieldLayouts); + checkCaptionWidth(node, node.name("fieldLayout") == "inline"); + } + static constexpr std::array kAlign = {"start", "center", "end", "stretch"}; + static constexpr std::array kJustify = {"start", "center", "end", "between"}; + checkChoice(node, "align", kAlign); + checkChoice(node, "justify", kJustify); + checkChoice(node, "alignSelf", kAlign); + checkSurfaceValues(node); + } + + // Each form field drawn by a host component. + void checkFieldComponents(DocNode const& form) const { + if (form.kind != "form") { + return; + } + for (DocNodePtr const& record : form.partList("fields")) { + for (DocNodePtr const& field : record->partList("fields")) { + if (!field->name("component").empty()) { + checkFieldComponent(*field); + } + } + } + } + + // A form field drawn by a host component: a declared one with a `value` prop and a `change` event, given only + // props it declares, and not beside a `widget`, which would choose the control too. + void checkFieldComponent(DocNode const& field) const { + std::string_view const name = field.name("component"); + std::string const where = pointerAppend(field.path, "component"); + auto const found = _doc->components.find(name); + if (found == _doc->components.end()) { + refuse(where, "`" + std::string{name} + "` is not a component of this document"); + } + Component const& component = found->second; + if (!component.props.contains("value") || !component.events.contains("change")) { + refuse(where, "the component `" + component.name + + "` draws a form field, so it declares a prop `value` and an event `change`"); + } + if (field.prop("widget") != nullptr) { + refuse(where, "`component` and `widget` both choose the field's control; give one"); + } + for (DocNodePtr const& props : field.partList("props")) { + for (auto const& [prop, value] : props->props) { + if (!component.props.contains(prop)) { + refuse(value->path, "the component `" + component.name + "` declares no prop `" + prop + "`"); + } + } + } + } + + // The document's top-level parts: a screen head's status badges, actions, menu entries and tools, and the app + // document's navigation badges. + [[nodiscard]] std::vector headParts() const { + std::vector parts = _doc->status; + parts.insert(parts.end(), _doc->actions.begin(), _doc->actions.end()); + parts.insert(parts.end(), _doc->menu.begin(), _doc->menu.end()); + parts.insert(parts.end(), _doc->tools.begin(), _doc->tools.end()); + parts.insert(parts.end(), _doc->navigation.begin(), _doc->navigation.end()); + return parts; + } + + // The head's tools: each id once, and each one its kind's. + static void checkHeadTools(std::span tools) { + std::set ids; + for (DocNodePtr const& tool : tools) { + if (!ids.insert(tool->id).second) { + refuse(pointerAppend(tool->path, "id"), + "the head tool id `" + tool->id + "` is used twice; each tool has its own"); + } + checkHeadTool(*tool); + } + } + + // One head tool: a kind of the two, only its kind's keys, a select's options in a dropdown, a literal width. + static void checkHeadTool(DocNode const& tool) { + static constexpr std::array kSearchOnly = { + "value", + "placeholder", + "onChange", + "onSubmit", + }; + static constexpr std::array kSelectOnly = {"options", "selected", "style", "onChoose"}; + std::string_view const kind = tool.name("kind"); + if (kind != "search" && kind != "select") { + refuse(pointerAppend(tool.path, "kind"), + "`" + std::string{kind} + "` is not one of the values of `kind`: search or select"); + } + bool const search = kind == "search"; + for (std::string_view const key : search ? kSelectOnly : kSearchOnly) { + if (tool.prop(key) || tool.event(key) != nullptr || !tool.name(key).empty()) { + refuse(pointerAppend(tool.path, key), + "`" + std::string{key} + "` is a " + (search ? "select" : "search") + " tool's"); + } + } + if (!search && !tool.prop("options")) { + refuse(tool.path, "a select tool has `options`"); + } + if (std::string_view const style = tool.name("style"); !style.empty() && style != "dropdown") { + refuse(pointerAppend(tool.path, "style"), + "`" + std::string{style} + "` is not one of the values of `style`: dropdown"); + } + ExprPtr const width = tool.prop("width"); + std::int64_t const* const units = width && width->kind == ExprKind::Literal + ? width->literal.asInt() + : static_cast(nullptr); + if (width && (units == nullptr || *units < 1)) { + refuse(pointerAppend(tool.path, "width"), "`width` is a literal whole number of units, 1 or more"); + } + } + + // The head menu's entries, at every level: an entry that is chosen has an id, unique across the whole menu, since + // `ScreenHead::choose` names it by that id; a separator or a submenu is never chosen and takes none. + // NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. + static void checkHeadMenu(std::span entries, std::set& ids) { + for (DocNodePtr const& entry : entries) { + bool const submenu = !entry->partList("items").empty(); + if (entry->flag("separator") || submenu) { + if (!entry->id.empty()) { + refuse(pointerAppend(entry->path, "id"), + submenu ? "a submenu is opened, not chosen, and takes no `id`" + : "a separator is a line between entries and takes no other key"); + } + checkHeadMenu(entry->partList("items"), ids); + continue; + } + if (entry->id.empty()) { + refuse(entry->path, "a head menu entry has an `id`, which choosing it names"); + } + if (!ids.insert(entry->id).second) { + refuse(pointerAppend(entry->path, "id"), + "the head menu entry id `" + entry->id + "` is used twice; each entry has its own"); + } + } + } + + // A list of `actionButton` parts: each id once, and each emphasis one of a button's. + static void checkActionButtons(std::span buttons, std::string const& path) { + static constexpr std::array kEmphasis = { + "normal", "primary", "danger", "ghost", "dangerOutline", + }; + std::set ids; + for (DocNodePtr const& button : buttons) { + if (!ids.insert(button->id).second) { + refuse(pointerAppend(button->path, "id"), + "the action id `" + button->id + "` is used twice in " + path + "; each action has its own"); + } + checkChoice(*button, "emphasis", kEmphasis); + } + } + + // A literal sizing of one dimension: `"content"`, `{"fixed": n}` (n of 0 or more), `{"stretch": w}` (w of 1 or + // more) or `{"percent": n}` (n from 1 to 100). Answers the fixed amount, if it is one. + static std::optional sizingDimension(Value const& value, std::string const& path) { + static constexpr std::string_view kForms = + "`sizing` is `\"content\"`, `{\"fixed\": n}`, `{\"stretch\": w}`, `{\"percent\": n}` (n from 1 to 100), " + "or a " + "record of `width` and `height` of them"; + if (std::string const* const text = value.asString(); text != nullptr && *text == "content") { + return std::nullopt; + } + ValueRecord const* const record = value.asRecord(); + if (record != nullptr && record->size() == 1) { + auto const& [form, amount] = *record->begin(); + std::int64_t const* const units = amount.asInt(); + if (form == "fixed" && units != nullptr && *units >= 0) { + return *units; + } + if (form == "stretch" && units != nullptr && *units >= 1) { + return std::nullopt; + } + if (form == "percent" && units != nullptr && *units >= 1 && *units <= 100) { + return std::nullopt; + } + } + refuse(path, std::string{kForms}); + } + + // Whether a literal sizing dimension is `{"percent": n}`. + static bool isPercent(Value const& value) { + ValueRecord const* const record = value.asRecord(); + return record != nullptr && record->size() == 1 && record->begin()->first == "percent"; + } + + // Whether a literal `sizing` gives the node a percent width: as the single form, or as the `width` of a record. + static bool hasPercentWidth(DocNode const& node) { + ExprPtr const sizing = node.prop("sizing"); + if (sizing == nullptr || sizing->kind != ExprKind::Literal) { + return false; + } + ValueRecord const* const record = sizing->literal.asRecord(); + if (record != nullptr && (record->contains("width") || record->contains("height"))) { + auto const found = record->find("width"); + return found != record->end() && isPercent(found->second); + } + return isPercent(sizing->literal); + } + + // A table column's or a grid track's literal `width` is no share: a track is sized by the grid, a column by its + // table. + static void checkNoPercentWidth(DocNode const& node) { + ExprPtr const width = node.prop("width"); + if (width != nullptr && width->kind == ExprKind::Literal && isPercent(width->literal)) { + refuse(width->path, std::string{kPercentPlaces}); + } + } + + // What a percent sizes: a width along a row or a horizontal splitter's pane. + static constexpr std::string_view kPercentPlaces = + "`percent` sizes a width along a row or a horizontal splitter; nothing here takes a share"; + + // A node's size keys: each bound a literal integer of 0 or more, a minimum no more than its maximum, no bound on + // an overlay or a custom node; and a literal `sizing` one of the forms the interpreter reads, with a fixed amount + // inside its dimension's bounds. A sizing that is not literal is read at mount. + static void checkLayoutKeys(DocNode const& node) { checkSizing(node, literalBounds(node)); } + + // The size bounds a node gives, `minWidth`, `maxWidth`, `minHeight` and `maxHeight` in that order: literal + // integers of 0 or more, no minimum above its maximum, none on an overlay or a custom node. + static std::array, 4> literalBounds(DocNode const& node) { + static constexpr std::array kBounds = {"minWidth", "maxWidth", "minHeight", "maxHeight"}; + std::array, 4> bounds{}; + for (std::size_t index = 0; index < kBounds.size(); ++index) { + std::string_view const key = kBounds.at(index); + ExprPtr const bound = node.prop(key); + if (bound == nullptr) { + continue; + } + if (node.kind == "dialog" || node.kind == "drawer") { + refuse(bound->path, "an overlay is sized by the frontend, not by its container"); + } + if (node.kind == "custom") { + refuse(bound->path, + "a custom node carries no common properties, so it takes no `" + std::string{key} + "`"); + } + std::int64_t const* const units = + bound->kind == ExprKind::Literal ? bound->literal.asInt() : static_cast(nullptr); + if (units == nullptr || *units < 0) { + refuse(bound->path, "`" + std::string{key} + "` is a literal integer of 0 or more, in backend units"); + } + bounds.at(index) = *units; + } + for (std::size_t axis = 0; axis < 2; ++axis) { + auto const& minimum = bounds.at(2 * axis); + auto const& maximum = bounds.at((2 * axis) + 1); + if (minimum && maximum && *minimum > *maximum) { + refuse(pointerAppend(node.path, kBounds.at(2 * axis)), + "`" + std::string{kBounds.at(2 * axis)} + "` is more than `" + + std::string{kBounds.at((2 * axis) + 1)} + "`"); + } + } + return bounds; + } + + // Whether a literal sizing dimension's value is `{"stretch": w}` (as opposed to `"content"` or `{"fixed": n}`, + // which both `sizingDimension` reports the same way -- as "no fixed amount"). An overlay is sized by the + // frontend, not by its container, so stretching it would silently change how every *other* sibling in its own + // parent layout is justified; checked ahead of `sizingDimension` itself, which does not distinguish the two. + static bool isStretch(Value const& value) { + ValueRecord const* const record = value.asRecord(); + return record != nullptr && record->size() == 1 && record->begin()->first == "stretch"; + } + + // An overlay (`dialog`/`drawer`) refuses a literal `sizing` that stretches either dimension, single-value or + // record form: an overlay is sized by the frontend, not by its container, so stretching it would silently change + // how every *other* sibling in its own parent layout is justified. + static void checkOverlaySizing(DocNode const& node, ExprPtr const& sizing) { + if (node.kind != "dialog" && node.kind != "drawer") { + return; + } + ValueRecord const* const record = sizing->literal.asRecord(); + bool const stretches = + isStretch(sizing->literal) || + (record != nullptr && (record->contains("width") || record->contains("height")) && + std::ranges::any_of(*record, [](auto const& entry) { return isStretch(entry.second); })); + if (stretches) { + refuse(sizing->path, + "an overlay is sized by the frontend, not by its container; give it `{\"fixed\": n}` instead " + "of `{\"stretch\": w}`"); + } + } + + // A literal `sizing` gives a percent as neither a height nor the width of an overlay. + static void checkPercentSizing(DocNode const& node, ExprPtr const& sizing) { + ValueRecord const* const record = sizing->literal.asRecord(); + if (record != nullptr && record->contains("height") && isPercent(record->at("height"))) { + refuse(sizing->path, std::string{kPercentPlaces}); + } + if (hasPercentWidth(node) && (node.kind == "dialog" || node.kind == "drawer")) { + refuse(sizing->path, std::string{kPercentPlaces}); + } + } + + // A literal `sizing` is one of its forms, and a fixed amount lies inside its dimension's @p bounds. + static void checkSizing(DocNode const& node, std::array, 4> const& bounds) { + ExprPtr const sizing = node.prop("sizing"); + if (sizing == nullptr || sizing->kind != ExprKind::Literal) { + return; + } + checkOverlaySizing(node, sizing); + checkPercentSizing(node, sizing); + std::optional width; + std::optional height; + ValueRecord const* const record = sizing->literal.asRecord(); + if (record != nullptr && (record->contains("width") || record->contains("height"))) { + for (auto const& [dimension, value] : *record) { + if (dimension == "width") { + width = sizingDimension(value, sizing->path); + } else if (dimension == "height") { + height = sizingDimension(value, sizing->path); + } else { + refuse(sizing->path, "a `sizing` record has `width` and `height`; `" + dimension + "` is neither"); + } + } + } else { + width = sizingDimension(sizing->literal, sizing->path); + } + for (auto const& [fixed, axis] : {std::pair{width, std::size_t{0}}, std::pair{height, std::size_t{1}}}) { + auto const& minimum = bounds.at(2 * axis); + auto const& maximum = bounds.at((2 * axis) + 1); + if (fixed && (*fixed < minimum.value_or(*fixed) || *fixed > maximum.value_or(*fixed))) { + refuse(sizing->path, std::string{"a fixed size has no room to bound: the "} + + (axis == 0 ? "width" : "height") + " is fixed outside its bounds"); + } + } + } + + // A text's or a table column's literal `role` is one of the roles (`title` is `heading`'s alias); a computed one + // is read at mount, and one of no known name is reported there. + static void checkTextRole(DocNode const& node) { + ExprPtr const role = node.prop("role"); + if (role == nullptr || role->kind != ExprKind::Literal) { + return; + } + static constexpr std::array kRoles = { + "normal", "muted", "heading", "title", "section", "error", "success", + "mono", "display", "small", "overline", "caption", "label", "headline", + }; + std::string const* const name = role->literal.asString(); + if (name == nullptr) { + refuse(pointerAppend(node.path, "role"), "`role` is a name"); + } + if (!listed(kRoles, *name)) { + refuse(pointerAppend(node.path, "role"), "`" + *name + "` is not one of the values of `role`"); + } + } + + // A dialog's, drawer's or form's error policy, submit mode and description spans. + static void checkSurfaceValues(DocNode const& node) { + if (node.kind != "dialog" && node.kind != "drawer" && node.kind != "form") { + return; + } + static constexpr std::array kPolicies = {"touched", "submit", "always"}; + checkChoice(node, "showErrors", kPolicies); + // Absent keeps the schema's own mode, so a misspelt mode would silently do the same. + static constexpr std::array kSubmitModes = {"explicit", "auto"}; + checkChoice(node, "submit", kSubmitModes); + checkSpans(node.prop("descriptionSpans")); + } + + // A text's role and spans; a text carries no description, the line itself is the text. + static void checkText(DocNode const& node) { + checkTextRole(node); + static constexpr std::array kTextAligns = {"start", "center", "end"}; + checkChoice(node, "align", kTextAligns); + checkSpans(node.prop("spans")); + if (node.prop("description") != nullptr) { + refuse(pointerAppend(node.path, "description"), "a text is not described; put the line in the text"); + } + if (node.prop("labelHint") != nullptr) { + refuse(pointerAppend(node.path, "labelHint"), "a text has no caption to hint after; put it in the text"); + } + } + + // A banner's action: its style is one of three; the link style places the action in the message's runs, and a + // stretched action is a button on a line of its own, so it needs an action and is no link. + static void checkBanner(DocNode const& node) { + static constexpr std::array kStyles = {"ghost", "button", "link"}; + checkChoice(node, "actionStyle", kStyles); + bool const link = node.name("actionStyle") == "link"; + checkSpans(node.prop("spans"), link); + if (node.flag("actionStretch")) { + if (link) { + refuse(pointerAppend(node.path, "actionStretch"), + "`actionStretch` puts a button on a line of its own; a `link` action sits in the message"); + } + if (!node.parts.contains("action")) { + refuse(pointerAppend(node.path, "actionStretch"), "`actionStretch` stretches the banner's `action`"); + } + } + } + + // What an `action` run is told where the loader refuses it. + static constexpr std::string_view kActionRunPlaces = + "an `action` run is the link of a banner whose `actionStyle` is " + "\"link\"; at most one run of its spans takes it"; + + // A span list written out: each literal run a string, each record run a `text` with at most the flags `strong` + // and `mono`, each literal flag a boolean. A computed list, or a computed element, is checked as it is drawn. A + // run may carry `action` where @p actionAllowed, once at most. + static void checkSpans(ExprPtr const& spans, bool actionAllowed = false) { + if (spans == nullptr) { + return; + } + int actions = 0; + if (spans->kind == ExprKind::Literal) { + ValueList const* const runs = spans->literal.asList(); + if (runs == nullptr) { + refuse(spans->path, "`spans` is a list of runs"); + } + for (Value const& run : *runs) { + checkLiteralRun(run, spans->path, actionAllowed, actions); + } + return; + } + if (spans->kind != ExprKind::List) { + return; + } + for (ExprPtr const& run : spans->args) { + if (run->kind == ExprKind::Literal) { + checkLiteralRun(run->literal, run->path, actionAllowed, actions); + } else if (run->kind == ExprKind::Object) { + checkRunRecord(*run, actionAllowed, actions); + } + } + } + + // A button's `children`: only on a list entry, and display kinds only, at any depth, so the entry stays one + // control with one activation. A list of what is allowed keeps a kind added later out until it is judged. + static void checkEntryContent(DocNode const& button) { + auto const found = button.children.find("children"); + if (found == button.children.end() || found->second.empty()) { + return; + } + if (button.name("style") != "item") { + refuse(pointerAppend(button.path, "children"), + "only a list entry holds content; a push button has a label"); + } + for (DocNodePtr const& child : found->second) { + checkReadOnlyContent(*child); + } + } + + // NOLINTNEXTLINE(misc-no-recursion): an entry's content is a tree of nodes. + static void checkReadOnlyContent(DocNode const& node) { + static constexpr std::array kDisplay = { + "text", "badge", "keyValue", "progress", "steps", "busy", + "spacer", "column", "row", "grid", "forEach", "switch", + }; + static constexpr std::string_view kReason = + "an entry's content is read-only; put the control beside the entry"; + if (!listed(kDisplay, node.kind)) { + refuse(node.path, std::string{kReason}); + } + for (std::string_view const key : {std::string_view{"autofocus"}}) { + if (node.prop(key) != nullptr) { + refuse(pointerAppend(node.path, key), std::string{kReason}); + } + } + if (!node.keys.empty()) { + refuse(pointerAppend(node.path, "keys"), std::string{kReason}); + } + for (std::string_view const part : {std::string_view{"drag"}, std::string_view{"drop"}}) { + if (!node.partList(part).empty()) { + refuse(pointerAppend(node.path, part), std::string{kReason}); + } + } + for (auto const& [key, nodes] : node.children) { + for (DocNodePtr const& child : nodes) { + checkReadOnlyContent(*child); + } + } + for (auto const& [key, parts] : node.parts) { + for (DocNodePtr const& part : parts) { + for (auto const& [childKey, nodes] : part->children) { + for (DocNodePtr const& child : nodes) { + checkReadOnlyContent(*child); + } + } + } + } + } + + // A select's style written as a constant: one of the three it may be. A computed one is read as it is drawn. + static void checkSelectStyle(DocNode const& node) { + ExprPtr const style = node.prop("style"); + if (style == nullptr || style->kind != ExprKind::Literal) { + return; + } + static constexpr std::array kStyles = {"dropdown", "radio", "segmented"}; + std::string const* const name = style->literal.asString(); + if (name == nullptr) { + refuse(pointerAppend(node.path, "style"), "`style` is a name"); + } + if (!listed(kStyles, *name)) { + refuse(pointerAppend(node.path, "style"), "`" + *name + "` is not one of the values of `style`"); + } + } + + // A literal multiline text input with a unit or an icon: a text area holds no number and draws no icon. + static void checkMultilineExtras(DocNode const& node) { + ExprPtr const mode = node.prop("mode"); + std::string const* const name = + mode != nullptr && mode->kind == ExprKind::Literal ? mode->literal.asString() : nullptr; + if (name == nullptr || *name != "multiline") { + return; + } + for (std::string_view const key : { + std::string_view{"unit"}, + std::string_view{"icon"}, + std::string_view{"prefix"}, + std::string_view{"decimals"}, + }) { + if (node.prop(key) != nullptr) { + refuse(pointerAppend(node.path, key), "a multiline input shows no " + std::string{key}); + } + } + if (!node.name("align").empty()) { + refuse(pointerAppend(node.path, "align"), "a multiline input's text starts at the leading edge"); + } + if (!node.name("emphasis").empty() && node.name("emphasis") != "normal") { + refuse(pointerAppend(node.path, "emphasis"), "a multiline input's size is its own; it takes no emphasis"); + } + } + + // The spans of each key-value item written as an `obj` in a `list`. + static void checkItemSpans(ExprPtr const& items) { + if (items == nullptr || items->kind != ExprKind::List) { + return; + } + for (ExprPtr const& item : items->args) { + if (item->kind != ExprKind::Object) { + continue; + } + for (auto const& [key, value] : item->fields) { + if (key == "spans") { + checkSpans(value); + } + } + } + } + + // A literal run's tone: one of the tone names, or null for none. + static void checkLiteralRunTone(Value const& tone, std::string const& path) { + std::string const* const name = tone.asString(); + if (tone.isNull()) { + return; + } + if (name == nullptr || + (*name != "neutral" && *name != "info" && *name != "ok" && *name != "warn" && *name != "err")) { + refuse(path, "a run's `tone` is neutral, info, ok, warn or err"); + } + } + + // A run marked `action`: allowed in a link banner's spans, once. + static void checkActionRun(std::string const& path, bool actionAllowed, int& actions) { + if (!actionAllowed || ++actions > 1) { + refuse(path, std::string{kActionRunPlaces}); + } + } + + // A literal run: a string, or a record of a string `text` and boolean flags. + static void checkLiteralRun(Value const& run, std::string const& path, bool actionAllowed, int& actions) { + if (run.asString() != nullptr) { + return; + } + ValueRecord const* const record = run.asRecord(); + if (record == nullptr) { + refuse(path, "a run is a string or a record with `text`"); + } + if (!record->contains("text")) { + refuse(path, "a run's record gives its `text`"); + } + for (auto const& [key, value] : *record) { + if (key != "text" && key != "strong" && key != "mono" && key != "tone" && key != "action") { + refuse(path, "a run takes `text`, `strong`, `mono` and `tone`, not `" + key + "`"); + } + if (key == "tone") { + checkLiteralRunTone(value, path); + } else if (key != "text" && value.asBool() == nullptr) { + refuse(path, "a run's `" + key + "` is true or false"); + } + if (key == "action" && value.asBool() != nullptr && *value.asBool()) { + checkActionRun(path, actionAllowed, actions); + } + } + } + + // A run written as an `obj`: a `text`, and flags that are booleans when written as constants. + static void checkRunRecord(Expr const& run, bool actionAllowed, int& actions) { + bool hasText = false; + for (auto const& [key, value] : run.fields) { + if (key == "text") { + hasText = true; + } else if (key == "tone") { + if (value->kind == ExprKind::Literal) { + checkLiteralRunTone(value->literal, value->path); + } + } else if (key != "strong" && key != "mono" && key != "action") { + refuse(value->path, "a run takes `text`, `strong`, `mono` and `tone`, not `" + key + "`"); + } else if (value->kind == ExprKind::Literal && value->literal.asBool() == nullptr) { + refuse(value->path, "a run's `" + key + "` is true or false"); + } else if (key == "action" && value->kind == ExprKind::Literal && *value->literal.asBool()) { + checkActionRun(value->path, actionAllowed, actions); + } + } + if (!hasText) { + refuse(run.path, "a run's record gives its `text`"); + } + } + + // A table cell's place across its column and down its row: `stretch`, which a stack takes, is no place for a + // cell. + static constexpr std::array kCellPlaces = {"start", "center", "end"}; + + // A table column's closed sets: its default cell's text role, and its cells' places. + static void checkColumnPart(DocNode const& node) { + checkTextRole(node); + checkCellPlace(node, "align"); + checkCellPlace(node, "valign"); + } + + // Only a horizontal `forEach` wraps and only a vertical one is divided; a literal `axis` that says otherwise is + // refused here, and a computed one is read when the screen lowers. + static void checkForEachWrap(DocNode const& node) { + ExprPtr const axis = node.prop("axis"); + if (axis == nullptr || axis->kind != ExprKind::Literal) { + return; + } + std::string const* const named = axis->literal.asString(); + bool const horizontal = named != nullptr && *named == "horizontal"; + if (node.flag("wrap") && !horizontal) { + refuse(pointerAppend(node.path, "wrap"), + "`wrap` fills lines along a row; this `forEach`'s `axis` is not \"horizontal\""); + } + if (node.flag("divided") && horizontal) { + refuse(pointerAppend(node.path, "divided"), + "`divided` draws rules between rows of a column; this `forEach`'s `axis` is \"horizontal\""); + } + } + + // An action bar's gap is the theme's, and a horizontal `forEach` directly in it is part of that row. + static void checkActionBar(DocNode const& node) { + if (node.prop("gap") != nullptr) { + refuse(pointerAppend(node.path, "gap"), kActionBarGapRefusal); + } + // A horizontal `forEach` directly in the bar is part of its row of actions, so it takes the same gap. + for (DocNodePtr const& child : node.nodes("children")) { + if (child->kind != "forEach" || child->prop("gap") == nullptr) { + continue; + } + ExprPtr const axis = child->prop("axis"); + if (axis != nullptr && axis->kind == ExprKind::Literal) { + std::string const* const named = axis->literal.asString(); + if (named != nullptr && *named == "horizontal") { + refuse(pointerAppend(child->path, "gap"), kActionBarGapRefusal); + } + } + } + } + + // A grid's `minColumnWidth`: a literal number of units that has columns to drop, and no tracks, which size their + // own columns. Where it could do nothing, it is refused rather than ignored. + static void checkMinColumnWidth(DocNode const& node) { + ExprPtr const least = node.prop("minColumnWidth"); + if (least == nullptr) { + return; + } + std::int64_t const* const units = + least->kind == ExprKind::Literal ? least->literal.asInt() : static_cast(nullptr); + if (units == nullptr) { + refuse(least->path, "`minColumnWidth` is a literal integer"); + } + if (*units < 1 || *units > 64) { + refuse(least->path, "`minColumnWidth` is 1 to 64 units"); + } + if (node.parts.contains("tracks")) { + refuse(least->path, "a grid with tracks sizes its own columns; `minColumnWidth` is for equal columns"); + } + ExprPtr const columns = node.prop("columns"); + if (columns == nullptr) { + refuse(least->path, + "`minColumnWidth` needs `columns`: it drops columns from that count as the grid narrows"); + } + if (columns->kind == ExprKind::Literal) { + std::int64_t const* const count = columns->literal.asInt(); + if (count != nullptr && *count <= 1) { + refuse(least->path, "`minColumnWidth` has nothing to drop from one column"); + } + } + } + + static void checkGrid(DocNode const& node) { + if (!node.name("justify").empty()) { + refuse(pointerAppend(node.path, "justify"), + "a grid's columns are sized by their count or tracks; there is no spare length to justify"); + } + if (node.prop("selected") != nullptr) { + refuse(pointerAppend(node.path, "selected"), + "a grid is not an entry of a list; `selected` marks a column or a row"); + } + checkMinColumnWidth(node); + auto const tracks = node.parts.find("tracks"); + if (tracks == node.parts.end()) { + return; + } + if (node.prop("columns") != nullptr) { + refuse(pointerAppend(node.path, "tracks"), + "a grid takes `columns` or `tracks`, not both; with `tracks`, the column count is their number"); + } + if (tracks->second.empty()) { + refuse(pointerAppend(node.path, "tracks"), "`tracks` lists at least one track"); + } + } + + // A menu's style, and its trigger's keys, which only a button-style menu has. An icon-only trigger needs a name + // for assistive technology, so a button-style menu has a `label` or an `a11y` name. + static void checkMenu(DocNode const& node) { + static constexpr std::array kStyles = {"bar", "button"}; + checkChoice(node, "style", kStyles); + static constexpr std::array kEmphasis = {"normal", "primary", "danger", "ghost"}; + checkChoice(node, "emphasis", kEmphasis); + if (node.name("style") != "button") { + for (std::string_view const key : {"label", "icon"}) { + if (node.prop(key) != nullptr) { + refuse( + pointerAppend(node.path, key), + "`" + std::string{key} + "` is a button-style menu's trigger; give the menu `style: button`"); + } + } + if (!node.name("emphasis").empty()) { + refuse(pointerAppend(node.path, "emphasis"), + "`emphasis` is a button-style menu's trigger; give the menu `style: button`"); + } + return; + } + auto const a11y = node.partList("a11y"); + bool const named = !a11y.empty() && a11y.front()->prop("name") != nullptr; + if (node.prop("label") == nullptr && !named) { + refuse(node.path, + "a button-style menu has a `label` or an `a11y` name, so its trigger has a name for " + "assistive technology"); + } + } + + // A separator is a line between entries: `true`, and nothing else beside it. + // Whether a part kind is a menu entry: a `menu` node's or a screen head's. + [[nodiscard]] static bool isMenuEntry(std::string_view kind) { + return kind == "menuItem" || kind == "headMenuItem"; + } + + static void checkMenuItem(DocNode const& node) { + if (!node.flags.contains("separator")) { + return; + } + if (!node.flag("separator")) { + refuse(pointerAppend(node.path, "separator"), "`separator` is `true`; leave it out for an entry"); + } + bool const alone = node.props.empty() && node.events.empty() && node.parts.empty() && node.names.empty() && + node.keys.empty() && node.flags.size() == 1; + if (!alone) { + refuse(node.path, "a separator is a line between entries and takes no other key"); + } + } + + // A cell place, which names the three it may be. + static void checkCellPlace(DocNode const& node, std::string_view key) { + std::string_view const value = node.name(key); + if (!value.empty() && !listed(kCellPlaces, value)) { + refuse(pointerAppend(node.path, key), "`" + std::string{value} + "` is not one of the values of `" + + std::string{key} + "`: start, center or end"); + } + } + + // A form's `columns`: a literal integer, 1 to 12, the `x-colspan` convention's full row. + static void checkFormColumns(DocNode const& node) { + ExprPtr const columns = node.prop("columns"); + if (columns == nullptr) { + return; + } + std::int64_t const* const count = + columns->kind == ExprKind::Literal ? columns->literal.asInt() : static_cast(nullptr); + if (count == nullptr) { + refuse(columns->path, "`columns` is a literal integer"); + } + if (*count < 1 || *count > 12) { + refuse(columns->path, "`columns` is 1 to 12; a form lays its fields in at least one column"); + } + } + + // A `captionWidth`: a literal integer, 1 to 64, which needs a caption column, so inline captions. + static void checkCaptionWidth(DocNode const& node, bool inlineCaptions) { + ExprPtr const width = node.prop("captionWidth"); + if (width == nullptr) { + return; + } + std::int64_t const* const units = + width->kind == ExprKind::Literal ? width->literal.asInt() : static_cast(nullptr); + if (units == nullptr) { + refuse(width->path, "`captionWidth` is a literal integer"); + } + if (*units < 1 || *units > 64) { + refuse(width->path, "`captionWidth` is 1 to 64 units"); + } + if (!inlineCaptions) { + refuse(width->path, "`captionWidth` needs inline captions"); + } + } + + static void checkChoice(DocNode const& node, std::string_view key, std::span choices) { + std::string_view const value = node.name(key); + if (!value.empty() && !listed(choices, value)) { + refuse(pointerAppend(node.path, key), + "`" + std::string{value} + "` is not one of the values of `" + std::string{key} + "`"); + } + } + + void checkCommands(Commands const& commands, CheckContext const& context, bool sequence = false) { + CheckContext current = context; + current.commands = true; + for (Command const& cmd : commands) { + checkCommand(cmd, current); + if (sequence && cmd.kind == CommandKind::Run && !cmd.binding.empty() && !cmd.extra) { + current.bindings.emplace_back(cmd.binding, Type::any()); + } + } + } + + // NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per command of ui/1. + void checkCommand(Command const& cmd, CheckContext const& context) { + std::string const where = cmd.path; + switch (cmd.kind) { + case CommandKind::Set: + checkSet(cmd, context); + break; + case CommandKind::Reset: { + NameEntry const& entry = require(context, cmd.target, where, + {NameCategory::State, NameCategory::Element}, "state or a dialog"); + if (entry.category == NameCategory::Element && entry.element->kind != "dialog" && + entry.element->kind != "drawer") { + refuse(where, "`reset` restores state, or the state of a dialog; `" + cmd.target + "` is a " + + entry.element->kind); + } + break; + } + case CommandKind::Run: { + static_cast(require(context, cmd.target, where, {NameCategory::Mutation}, "a mutation")); + CheckContext body = context; + if (cmd.extra) { + checkExpr(*cmd.extra, context); + if (!cmd.binding.empty()) { + body.bindings.emplace_back(cmd.binding, Type::any()); + } + } + if (cmd.value) { + checkExpr(*cmd.value, body); + } + break; + } + case CommandKind::Refetch: + static_cast(require(context, cmd.target, where, {NameCategory::Query}, "a query")); + break; + case CommandKind::Open: + case CommandKind::Close: + if (cmd.kind == CommandKind::Close && cmd.target == "self") { + break; + } + checkDialog(cmd, context); + break; + case CommandKind::Focus: + checkFocus(cmd, context); + break; + case CommandKind::ResetPrefs: + if (cmd.target != "all" && !_doc->customize.contains(cmd.target)) { + refuse(where, "`" + cmd.target + "` is not a customization point of this document"); + } + break; + case CommandKind::If: + checkCondition(*cmd.value, context, "the condition of `if`"); + checkCommands(cmd.commands, context); + checkCommands(cmd.alternative, context); + break; + case CommandKind::Seq: + checkCommands(cmd.commands, context, true); + break; + case CommandKind::All: + case CommandKind::Navigate: + if (cmd.value) { + checkExpr(*cmd.value, context); + } + if (cmd.extra) { + checkExpr(*cmd.extra, context); + } + checkCommands(cmd.commands, context); + checkCommands(cmd.alternative, context); + break; + case CommandKind::CancelClose: + if (!context.onClose) { + refuse(where, "`cancelClose` is valid only in `onClose`"); + } + break; + case CommandKind::Retry: + if (!context.boundaryError) { + refuse(where, "`retry` is valid only inside a boundary's `error`"); + } + break; + case CommandKind::SignIn: + static_cast(require(context, cmd.target, where, {NameCategory::Mutation}, "a mutation")); + break; + case CommandKind::Upload: + static_cast(require(context, cmd.target, where, {NameCategory::Mutation}, "a mutation")); + checkExpr(*cmd.value, context); + break; + case CommandKind::Download: + checkExpr(*cmd.value, context); + if (cmd.extra) { + checkExpr(*cmd.extra, context); + } + if (cmd.mediaType) { + checkExpr(*cmd.mediaType, context); + } + if (cmd.option == "preview") { + static_cast(require(context, cmd.target, where, {NameCategory::State}, "state")); + } + break; + case CommandKind::Return: + case CommandKind::Host: + case CommandKind::Notify: + case CommandKind::SwitchBackend: + case CommandKind::SetLocale: + case CommandKind::SetContext: + case CommandKind::SignOut: + default: + if (cmd.value) { + checkExpr(*cmd.value, context); + } + break; + } + } + + static void checkDialog(Command const& cmd, CheckContext const& context) { + NameEntry const& entry = require(context, cmd.target, cmd.path, {NameCategory::Element}, "a dialog"); + if (entry.element->kind != "dialog" && entry.element->kind != "drawer") { + refuse(cmd.path, "`" + cmd.target + "` is a " + entry.element->kind + ", not a dialog or drawer"); + } + } + + void checkSet(Command const& cmd, CheckContext const& context) { + auto const segments = splitPath(cmd.target); + std::string const& head = segments->front(); + Type const value = checkExpr(*cmd.value, context); + if (head == "app") { + return; + } + NameEntry& entry = + require(context, head, cmd.path, {NameCategory::State, NameCategory::Element}, "state or an input"); + if (entry.category == NameCategory::Element) { + KindSpec const* const spec = findKind(entry.element->kind, false); + if ((spec->flags & kWritable) == 0) { + // A table's state is the document's: it binds its `selection`, `sort` or `page` to state, and the + // state is set. + std::string const hint = entry.element->kind == "table" + ? ": bind its `selection`, `sort` or `page` to state and set that" + : ""; + refuse(cmd.path, + "`set` writes state or an input's draft; `" + head + "` is a " + entry.element->kind + hint); + } + return; + } + auto const type = derivedType(entry, head); + if (type && segments->size() == 1 && !compatible(*type, value)) { + refuse(cmd.value->path, "`" + head + "` is " + type->name() + "; the value is " + value.name()); + } + } + + /// The state and elements an expression reads, through the `let` entries it reads. + void reads(Expr const& expr, ScopeInfo* scope, std::set& out, std::vector& locals, + std::set& seenLets) { + if (expr.kind == ExprKind::Ref && std::ranges::find(locals, expr.name) == locals.end()) { + NameEntry const* const entry = lookup(scope, expr.name); + if (entry != nullptr && + (entry->category == NameCategory::State || entry->category == NameCategory::Element)) { + out.insert(entry); + } else if (entry != nullptr && entry->category == NameCategory::Let && seenLets.insert(entry).second) { + std::vector inner; + reads(*entry->derivedFrom, entry->scope, out, inner, seenLets); + } + } + bool const binds = bindsElement(expr.kind); + for (std::size_t index = 0; index < expr.args.size(); ++index) { + if (binds && index == 1) { + locals.push_back(expr.name); + } + reads(*expr.args.at(index), scope, out, locals, seenLets); + if (binds && index == 1) { + locals.pop_back(); + } + } + for (auto const& [name, field] : expr.fields) { + static_cast(name); + reads(*field, scope, out, locals, seenLets); + } + } + + /// The state and elements a command list writes. + static void writes(Commands const& commands, ScopeInfo* scope, std::set& out) { + for (Command const& cmd : commands) { + if (cmd.kind == CommandKind::Set || cmd.kind == CommandKind::Reset) { + auto const segments = splitPath(cmd.target); + NameEntry const* const entry = lookup(scope, segments->front()); + if (entry != nullptr) { + out.insert(entry); + } + } + writes(cmd.commands, scope, out); + writes(cmd.alternative, scope, out); + } + } + + void checkWatchGraph() { + std::size_t const count = _watches.size(); + std::vector> observed(count); + std::vector> written(count); + for (std::size_t index = 0; index < count; ++index) { + auto const& [watch, scope] = _watches.at(index); + std::vector locals; + std::set seenLets; + reads(*watch->on, scope, observed.at(index), locals, seenLets); + writes(watch->body, scope, written.at(index)); + } + // 0 unvisited, 1 on the current path, 2 finished. + std::vector state(count, 0); + std::vector trail; + std::function visit = [&](std::size_t from) { + state.at(from) = 1; + trail.push_back(from); + for (std::size_t to = 0; to < count; ++to) { + bool edge = false; + for (NameEntry const* entry : written.at(from)) { + edge = edge || observed.at(to).contains(entry); + } + if (!edge) { + continue; + } + if (state.at(to) == 1) { + std::string cycle; + auto const start = std::ranges::find(trail, to); + for (auto step = start; step != trail.end(); ++step) { + cycle += _watches.at(*step).first->path + " → "; + } + refuse(_watches.at(to).first->path, + "the watch graph has a cycle: " + cycle + _watches.at(to).first->path); + } + if (state.at(to) == 0) { + visit(to); + } + } + trail.pop_back(); + state.at(from) = 2; + }; + for (std::size_t index = 0; index < count; ++index) { + if (state.at(index) == 0) { + visit(index); + } + } + } + + // The effect checks below read only what the catalog says about each action. They warn only where the + // effects certainly cover, or certainly miss, what the document declares, because a warning a document cannot + // act on would teach its author to ignore the rest. + + /// The effects as a phrase, such as "`changes T_Row`, `none`". + [[nodiscard]] static std::string describeEffects(std::vector const& effects) { + std::string out; + for (ActionEffect const& effect : effects) { + out += (out.empty() ? "`" : ", `") + effect.kind + (effect.record ? " " + *effect.record : "") + "`"; + } + return out; + } + + /// Whether an action's effects change anything; `none` alone does not. + [[nodiscard]] static bool changesData(ActionInfo const& info) { + return info.effects && + std::ranges::any_of(*info.effects, [](ActionEffect const& effect) { return effect.kind != "none"; }); + } + + void warn(LoadWarningKind kind, std::string path, std::string text) { + _warnings.push_back(LoadWarning{.kind = kind, .path = std::move(path), .text = std::move(text)}); + } + + void checkEffects() { + if (!_options->catalog.action) { + return; + } + for (auto const& entry : _mutations) { + checkMutationEffects(*entry.first); + } + for (auto const& [watch, scope] : _watches) { + checkWatchFeedback(*watch, scope); + } + } + + void checkMutationEffects(MutationDecl const& mutation) { + auto const action = _options->catalog.action(mutation.action); + if (!action) { + return; + } + if (!action->effects && !refetches(mutation.onSuccess)) { + warn(LoadWarningKind::Uncovered, mutation.path, + std::format("nothing refreshes after `{}` succeeds: `{}` declares no effects, and no `refetch` " + "follows it; declare what it changes, or `effects::none` when it changes nothing", + mutation.name, mutation.action)); + } + } + + /// Whether a command list refetches a query, which is a refresh the document declares itself. + [[nodiscard]] static bool refetches(Commands const& commands) { + return std::ranges::any_of(commands, [](Command const& cmd) { + return cmd.kind == CommandKind::Refetch || refetches(cmd.commands) || refetches(cmd.alternative); + }); + } + + // Another client's change refetches the watched query, the watch runs the mutation, and its change reaches the + // other client, which may do the same. Only `"source": "user"` keeps a refetch from running the watch. + void checkWatchFeedback(WatchDecl const& watch, ScopeInfo* scope) { + if (watch.source == WatchSource::User) { + return; + } + std::vector locals; + std::set seenLets; + auto const query = readQuery(*watch.on, scope, locals, seenLets); + if (!query) { + return; + } + if (auto const mutation = runsWriter(watch.body, scope)) { + warn(LoadWarningKind::WatchFeedback, watch.path, + std::format("the watch reads the query `{}` and runs `{}`, which changes data: another client's " + "change refetches the query and runs it again; give the watch \"source\": \"user\"", + *query, *mutation)); + } + } + + /// The first query whose value an expression reads, directly or through a `let`. + [[nodiscard]] static std::optional readQuery(Expr const& expr, ScopeInfo* scope, + std::vector& locals, + std::set& seenLets) { + if (expr.kind == ExprKind::Query) { + return expr.name; + } + if (expr.kind == ExprKind::Ref && std::ranges::find(locals, expr.name) == locals.end()) { + NameEntry const* const entry = lookup(scope, expr.name); + if (entry != nullptr && entry->category == NameCategory::Query) { + return expr.name; + } + if (entry != nullptr && entry->category == NameCategory::Let && seenLets.insert(entry).second) { + std::vector inner; + if (auto found = readQuery(*entry->derivedFrom, entry->scope, inner, seenLets)) { + return found; + } + } + } + bool const binds = bindsElement(expr.kind); + for (std::size_t index = 0; index < expr.args.size(); ++index) { + if (binds && index == 1) { + locals.push_back(expr.name); + } + auto found = readQuery(*expr.args.at(index), scope, locals, seenLets); + if (binds && index == 1) { + locals.pop_back(); + } + if (found) { + return found; + } + } + for (auto const& [name, field] : expr.fields) { + static_cast(name); + if (auto found = readQuery(*field, scope, locals, seenLets)) { + return found; + } + } + return std::nullopt; + } + + /// The first mutation a command list runs whose action changes data. + [[nodiscard]] std::optional runsWriter(Commands const& commands, ScopeInfo* scope) const { + for (Command const& cmd : commands) { + bool const runs = + cmd.kind == CommandKind::Run || cmd.kind == CommandKind::Upload || cmd.kind == CommandKind::SignIn; + NameEntry const* const entry = runs ? lookup(scope, cmd.target) : nullptr; + if (entry != nullptr && entry->mutation != nullptr) { + auto const action = _options->catalog.action(entry->mutation->action); + if (action && changesData(*action)) { + return cmd.target; + } + } + if (auto found = runsWriter(cmd.commands, scope)) { + return found; + } + if (auto found = runsWriter(cmd.alternative, scope)) { + return found; + } + } + return std::nullopt; + } + + Document const* _doc; + LoadOptions const* _options; + std::deque _scopes; + std::map _scopeOf; + std::map _innerOf; + std::map> _queries; + std::map> _elements; + std::vector> _watches; + std::vector> _mutations; + std::vector> _queryScopes; + std::vector _warnings; + std::map _dateValueKinds; + std::map> _focusTargets; + std::vector _deriving; + // NOLINTEND(misc-no-recursion) +}; + +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per kind of name. +std::expected ScopeResolver::ref(std::string_view head, std::span path) const { + for (auto const& [name, type] : std::views::reverse(_context.bindings)) { + if (name == head) { + return typeAlong(type, head, path); + } + } + if (head == "event") { + if (!_context.commands) { + return std::unexpected(std::string{"`event` is read only inside a command list"}); + } + return Type::any(); + } + if (head == "app") { + return Type::any(); + } + if (head == "boundary") { + if (!_context.boundaryError || path.size() != 1 || path.front() != "error") { + return std::unexpected(std::string{"`boundary.error` is read only inside a boundary's `error`"}); + } + return Type::of(TypeKind::String, true); + } + NameEntry* const entry = DocumentValidator::lookup(_context.scope, head); + if (entry == nullptr) { + return std::unexpected("`" + std::string{head} + "` does not resolve in this scope"); + } + switch (entry->category) { + case NameCategory::Param: + return typeAlong(entry->type, head, path); + case NameCategory::State: + case NameCategory::Let: { + auto type = _validator.derivedType(*entry, head); + if (!type) { + return type; + } + return typeAlong(*type, head, path); + } + case NameCategory::Query: + return Type::any(); + case NameCategory::Mutation: + return std::unexpected("`" + std::string{head} + + "` is a mutation; read it with `result`, `pending` or " + "`error`"); + case NameCategory::Model: + return std::unexpected("`" + std::string{head} + "` is a model alias, not a value"); + case NameCategory::Transfer: + if (path.empty() || !listed(kTransferValues, path.front())) { + return std::unexpected("the transfer `" + std::string{head} + + "` is read as `progress`, `pending` or `error`"); + } + return Type::any(); + case NameCategory::Element: + default: { + KindSpec const* const spec = findKind(entry->element->kind, false); + if (path.empty()) { + return std::unexpected("the element `" + std::string{head} + + "` is read through one of its values, " + "such as `" + + std::string{head} + ".visible`"); + } + std::string const& value = path.front(); + bool const open = (spec->flags & kOpenValues) != 0; + bool const known = listed(kAnyValues, value) || listed(spec->values, value) || open; + if (!known) { + return std::unexpected("the " + entry->element->kind + " `" + std::string{head} + "` has no value `" + + value + "`"); + } + bool const field = open && !listed(kAnyValues, value) && !listed(spec->values, value); + Type const type = field ? Type::any() : elementValueType(value); + return typeAlong(type, value, path.subspan(1)); + } + } +} + +std::expected ScopeResolver::row(std::span path) const { + static_cast(path); + for (ScopeInfo const* scope = _context.scope; scope != nullptr; scope = scope->parent) { + if (scope->row) { + return Type::any(); + } + } + return std::unexpected(std::string{"`row` is read only inside a forEach or table row"}); +} + +std::expected ScopeResolver::control(ExprKind form, std::string_view name) const { + if (form == ExprKind::Can && (name.starts_with("host:") || name == "context")) { + return Type::of(TypeKind::Bool); + } + NameEntry const* const entry = DocumentValidator::lookup(_context.scope, name); + bool const query = entry != nullptr && entry->category == NameCategory::Query; + bool const mutation = entry != nullptr && entry->category == NameCategory::Mutation; + if (form == ExprKind::Query && !query) { + return std::unexpected("`" + std::string{name} + "` is not a query of this scope"); + } + if (form == ExprKind::Result && !mutation) { + return std::unexpected("`" + std::string{name} + "` is not a mutation of this scope"); + } + if (!query && !mutation) { + return std::unexpected("`" + std::string{name} + "` is not a query or mutation of this scope"); + } + if (form == ExprKind::Pending || form == ExprKind::Can) { + return Type::of(TypeKind::Bool); + } + if (form == ExprKind::Error || form == ExprKind::ErrorKind) { + return Type::of(TypeKind::String, true); + } + return Type::any(); +} + +std::expected ScopeResolver::pref(std::string_view point, std::span path) const { + auto const& points = _validator.document().customize; + auto const found = points.find(point); + if (found == points.end()) { + return std::unexpected("`" + std::string{point} + "` is not a customization point of this document"); + } + return typeAlong(found->second.type, point, path); +} + +/// @brief The margins a page's `margins` key gives: one literal length for every side, or a record of sides. +/// @param margins The key's expression. +/// @return The margins. +PageMargins pageMarginsOf(ExprPtr const& margins) { + if (margins->kind != ExprKind::Literal || margins->literal.asRecord() == nullptr) { + return PageMargins{pageLengthOf(margins, "margins")}; + } + PageMargins result; + for (auto const& [side, amount] : *margins->literal.asRecord()) { + std::int64_t const* const count = amount.asInt(); + Mm* target = nullptr; + if (side == "top") { + target = &result.top; + } else if (side == "right") { + target = &result.right; + } else if (side == "bottom") { + target = &result.bottom; + } else if (side == "left") { + target = &result.left; + } + if (target == nullptr || count == nullptr || *count < 0 || *count > std::numeric_limits::max()) { + refuse(margins->path, + "`margins` is a literal count of micrometres, or a record of `top`, `right`, " + "`bottom` and `left` counts"); + } + *target = Mm::fromMicrometres(static_cast(*count)); + } + return result; +} + +} // namespace + +PageGeometry pageGeometryOf(DocNode const& node) { + PageGeometry geometry; + geometry.width = pageLengthOf(node.prop("width"), "width"); + geometry.height = pageLengthOf(node.prop("height"), "height"); + if (ExprPtr const margins = node.prop("margins")) { + geometry.margins = pageMarginsOf(margins); + } + if (std::optional const problem = geometry.problem()) { + refuse(node.path, *problem); + } + return geometry; +} + +RegionGeometry regionGeometryOf(DocNode const& node, PageGeometry const& page) { + RegionGeometry geometry; + std::string_view const anchor = node.name("anchor"); + if (anchor == "top") { + geometry.anchor = PageAnchor::Top; + } else if (anchor == "bottom") { + geometry.anchor = PageAnchor::Bottom; + } else if (anchor == "offset") { + geometry.anchor = PageAnchor::Offset; + } else { + refuse(pointerAppend(node.path, "anchor"), "`anchor` is `top`, `bottom` or `offset`"); + } + if (ExprPtr const x = node.prop("x")) { + geometry.x = pageLengthOf(x, "x"); + } + if (ExprPtr const y = node.prop("y")) { + geometry.y = pageLengthOf(y, "y"); + } + if (ExprPtr const width = node.prop("width")) { + geometry.width = pageLengthOf(width, "width"); + } + if (ExprPtr const height = node.prop("height")) { + geometry.height = pageLengthOf(height, "height"); + } + if (std::optional const problem = geometry.problem(page)) { + refuse(node.path, *problem); + } + return geometry; +} + +KindSpec const* findKind(std::string_view kind, bool part) { + for (KindSpec const& spec : kKinds) { + if (spec.kind == kind && ((spec.flags & kPart) != 0) == part) { + return &spec; + } + } + return nullptr; +} + +} // namespace detail + +std::expected loadDocument(Json const& json, LoadOptions const& options) { + std::string documentId; + if (auto const* const object = std::get_if(&json.data)) { + auto const* const found = object->find("id"); + if (found != object->end()) { + if (auto const* const text = std::get_if(&found->second.data)) { + documentId = *text; + } + } + } + try { + Document doc = detail::DocumentParser{}.parse(json); + detail::DocumentValidator validator{doc, options}; + validator.run(); + doc.warnings = validator.takeWarnings(); + doc.dateValueKinds = validator.takeDateValueKinds(); + doc.focusTargets = validator.takeFocusTargets(); + return doc; + } catch (detail::DocumentRefused const& refused) { + Refusal refusal = refused.refusal(); + refusal.document = documentId; + return std::unexpected(std::move(refusal)); + } +} + +std::expected loadDocumentText(std::string_view text, LoadOptions const& options) { + auto json = parseJson(text); + if (!json) { + return std::unexpected(Refusal{.document = {}, .path = "", .reason = std::move(json.error())}); + } + return loadDocument(*json, options); +} + +std::vector nodeKinds() { + std::vector kinds; + for (detail::KindSpec const& spec : detail::kKinds) { + if ((spec.flags & detail::kPart) == 0) { + kinds.push_back(spec.kind); + } + } + return kinds; +} + +} // namespace morph::ui From 0ab834cada4cf6feb48b0ac5d2164da61fb2e92a Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 04:15:47 +0100 Subject: [PATCH 07/38] Move the expression language into src/ui/expression.cpp The parser, the checker, the evaluator, the function table and the unit and date helpers move to the compiled library. `parseExpression`, `checkExpression`, `evaluate`, `functionNames`, `walk`, `readDateValue`, `runRecord`, `splitPath`, `typeAlong`, `numeric`, `convertUnit` and `unitDisplay` keep documented MORPH_API declarations: the document loader and the interpreter call them. `StaticEnvironment` carries MORPH_API, with `control` and `report` out of line. The evaluator's body lives in an unnamed namespace as `EvaluatorCore`. The interpreter drives an evaluator directly to group and order table rows, so `detail::Evaluator` is a handle over it with `eval`, `sortOrder`, `sortRows` and `sameRun`; `evaluate` uses the core without the handle's allocation. Includes the header no longer needs are dropped: a TU that includes only expression.hpp peaks at 417 MB of front-end memory, from 544 MB. The branch-coverage allowlist entries for expression.hpp now name src/ui/expression.cpp, and the install check's consumer loads a document and evaluates an expression so it links the moved code. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- CMakeLists.txt | 1 + docs/spec/ui/document.md | 2 +- docs/spec/ui/expressions.md | 2 +- docs/spec/ui/refusals.md | 2 +- include/morph/ui/expression.hpp | 2642 +----------------------- scripts/branch_partial_allowlist.json | 12 +- scripts/check_install_export.sh | 16 + src/ui/expression.cpp | 2702 +++++++++++++++++++++++++ 8 files changed, 2767 insertions(+), 2612 deletions(-) create mode 100644 src/ui/expression.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 677904835..6514fcc3d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -413,6 +413,7 @@ endif() include(GenerateExportHeader) add_library(morph STATIC src/ui/document.cpp + src/ui/expression.cpp src/ui/interpreter.cpp src/ui/library.cpp ) diff --git a/docs/spec/ui/document.md b/docs/spec/ui/document.md index 90bd23dab..2cc3dcd87 100644 --- a/docs/spec/ui/document.md +++ b/docs/spec/ui/document.md @@ -1,7 +1,7 @@ # The UI document — design Design spec for the UI document's C++ model and its load-time validation -(`include/morph/ui/document.hpp`), and for the typed values every document expression evaluates to +(`include/morph/ui/document.hpp`, loaded by `src/ui/document.cpp`), and for the typed values every document expression evaluates to (`include/morph/ui/value.hpp`). A server defines a screen as a JSON document (spec 5, `docs/superpowers/specs/2026-10-07-ui-document-design.md`); `ui::loadDocument` parses it into a `ui::Document` and refuses it, with the JSON Pointer and the reason, when it breaks a rule of diff --git a/docs/spec/ui/expressions.md b/docs/spec/ui/expressions.md index 9f4fbd947..f748a9d5d 100644 --- a/docs/spec/ui/expressions.md +++ b/docs/spec/ui/expressions.md @@ -1,6 +1,6 @@ # Expressions (`expr/1`) — design -Design spec for the expression language of the UI document (`include/morph/ui/expression.hpp`) and +Design spec for the expression language of the UI document (`include/morph/ui/expression.hpp`, implemented in `src/ui/expression.cpp`) and the MessageFormat 2 subset its `t` reads (`include/morph/ui/message.hpp`). Every bound property, query body, condition and command argument of a document is an expression: a JSON tree that `parseExpression` reads into an immutable `ui::Expr`, `checkExpression` checks against the diff --git a/docs/spec/ui/refusals.md b/docs/spec/ui/refusals.md index 3c231d0e6..097e3bce2 100644 --- a/docs/spec/ui/refusals.md +++ b/docs/spec/ui/refusals.md @@ -9,7 +9,7 @@ application's, in its catalogues. |---|---| | `include/morph/core/action_refusal.hpp` | `morph::model::RefusalArg`, `morph::model::ActionRefusal` | | `include/morph/core/wire.hpp` | the `err` envelope's `refusal` member (`wire::RefusalBody`), `wire::executeFailure` | -| `include/morph/ui/expression.hpp` | the `refusal` form, `t` with a key expression, the `refusalText` function | +| `include/morph/ui/expression.hpp`, `src/ui/expression.cpp` | the `refusal` form, `t` with a key expression, the `refusalText` function | | `include/morph/ui/author.hpp` | `refusal()` on query and mutation handles, `tAt`, `refusalText` | ## Contents diff --git a/include/morph/ui/expression.hpp b/include/morph/ui/expression.hpp index 236734d78..2668de195 100644 --- a/include/morph/ui/expression.hpp +++ b/include/morph/ui/expression.hpp @@ -2,38 +2,28 @@ #pragma once #include -#include -#include #include #include #include #include #include -#include #include -#include -#include #include #include -#include +#include #include -#include #include #include #include #include -#include #include #include #include "../render/i18n.hpp" #include "../render/locale_format.hpp" -#include "../table/data_source.hpp" #include "../util/datetime.hpp" #include "../util/rational.hpp" -#include "date_pattern.hpp" #include "locale_table.hpp" -#include "message.hpp" #include "value.hpp" /// @file @@ -186,648 +176,14 @@ struct Expr { /// @param key The shared value. /// @param items The run's elements, in order; not empty. /// @return The record. -[[nodiscard]] inline Value runRecord(Value key, ValueList items) { - ValueRecord record; - record.insert_or_assign("key", std::move(key)); - record.insert_or_assign("count", static_cast(items.size())); - record.insert_or_assign("first", items.front()); - record.insert_or_assign("last", items.back()); - record.insert_or_assign("items", Value{std::move(items)}); - return Value{std::move(record)}; -} +[[nodiscard]] MORPH_API Value runRecord(Value key, ValueList items); namespace detail { -/// @brief A set of type kinds, as bits. -using KindSet = std::uint16_t; - -/// @brief The bit of one kind. -/// @param kind The kind. -/// @return Its bit. -[[nodiscard]] constexpr KindSet kindBit(TypeKind kind) noexcept { - return static_cast(1U << static_cast(kind)); -} - -/// @brief Every kind. -inline constexpr KindSet kAllKinds = 0xFFFF; -/// @brief The numbers. -inline constexpr KindSet kNumeric = kindBit(TypeKind::Int) | kindBit(TypeKind::Decimal) | kindBit(TypeKind::Quantity); -/// @brief The ordered kinds. -inline constexpr KindSet kOrdered = kNumeric | kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String); - -/// @brief The sentence `refusalText` shows when the catalogue has neither a refusal's code nor a class of it. -inline constexpr std::string_view kBuiltInRefusal = "This was refused."; - -/// @brief The signature of a library function. -struct FunctionSpec { - /// @brief The name a document calls it by. - std::string_view name; - /// @brief The fewest arguments. - std::uint8_t minArgs; - /// @brief The most arguments; 255 for any number. - std::uint8_t maxArgs; - /// @brief The kinds the first, second and every further argument accept. - std::array accepts; - /// @brief The result's kind; `Any` when it depends on the arguments. - TypeKind result; -}; - -/// @brief The library, indexed by `FunctionId`. -// NOLINTBEGIN(modernize-use-designated-initializers): one row per function reads as a table; names on every field would not. -inline constexpr std::array kFunctions = {{ - {"and", 1, 255, {kindBit(TypeKind::Bool), kindBit(TypeKind::Bool), kindBit(TypeKind::Bool)}, TypeKind::Bool}, - {"or", 1, 255, {kindBit(TypeKind::Bool), kindBit(TypeKind::Bool), kindBit(TypeKind::Bool)}, TypeKind::Bool}, - {"not", 1, 1, {kindBit(TypeKind::Bool), 0, 0}, TypeKind::Bool}, - {"eq", 2, 2, {kAllKinds, kAllKinds, 0}, TypeKind::Bool}, - {"ne", 2, 2, {kAllKinds, kAllKinds, 0}, TypeKind::Bool}, - {"lt", 2, 2, {kOrdered, kOrdered, 0}, TypeKind::Bool}, - {"le", 2, 2, {kOrdered, kOrdered, 0}, TypeKind::Bool}, - {"gt", 2, 2, {kOrdered, kOrdered, 0}, TypeKind::Bool}, - {"ge", 2, 2, {kOrdered, kOrdered, 0}, TypeKind::Bool}, - {"add", 2, 2, {kNumeric, kNumeric, 0}, TypeKind::Any}, - {"sub", 2, 2, {kNumeric, kNumeric, 0}, TypeKind::Any}, - {"mul", 2, 2, {kNumeric, kNumeric, 0}, TypeKind::Any}, - {"div", 2, 2, {kNumeric, kNumeric, 0}, TypeKind::Any}, - {"neg", 1, 1, {kNumeric, 0, 0}, TypeKind::Any}, - {"round", 2, 3, {kNumeric, kindBit(TypeKind::Int), kindBit(TypeKind::String)}, TypeKind::Any}, - {"engaged", 1, 1, {kAllKinds, 0, 0}, TypeKind::Bool}, - {"coalesce", 1, 255, {kAllKinds, kAllKinds, kAllKinds}, TypeKind::Any}, - {"concat", - 1, - 255, - {kindBit(TypeKind::String), kindBit(TypeKind::String), kindBit(TypeKind::String)}, - TypeKind::String}, - {"format", 1, 255, {kindBit(TypeKind::String), kAllKinds, kAllKinds}, TypeKind::String}, - {"trim", 1, 1, {kindBit(TypeKind::String), 0, 0}, TypeKind::String}, - {"length", 1, 1, {kindBit(TypeKind::String), 0, 0}, TypeKind::Int}, - {"isEmpty", 1, 1, {kindBit(TypeKind::String) | kindBit(TypeKind::List), 0, 0}, TypeKind::Bool}, - {"contains", 2, 2, {kindBit(TypeKind::String), kindBit(TypeKind::String), 0}, TypeKind::Bool}, - {"count", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Int}, - {"sum", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Any}, - {"mean", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Any}, - {"min", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Any}, - {"max", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Any}, - {"any", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Bool}, - {"all", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Bool}, - {"first", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Any}, - {"includes", 2, 2, {kindBit(TypeKind::List), kAllKinds, 0}, TypeKind::Bool}, - {"indexOf", 2, 2, {kindBit(TypeKind::List), kAllKinds, 0}, TypeKind::Int}, - {"number", 1, 1, {kNumeric, 0, 0}, TypeKind::String}, - {"decimal", 2, 3, {kNumeric, kindBit(TypeKind::Int), kindBit(TypeKind::String)}, TypeKind::String}, - {"quantity", 1, 2, {kindBit(TypeKind::Quantity), kindBit(TypeKind::String), 0}, TypeKind::String}, - {"money", - 2, - 3, - {kindBit(TypeKind::Int) | kindBit(TypeKind::Decimal), kindBit(TypeKind::String), kindBit(TypeKind::String)}, - TypeKind::String}, - {"date", - 1, - 2, - {kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String), kindBit(TypeKind::String), 0}, - TypeKind::String}, - {"dateTime", - 1, - 2, - {kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String), kindBit(TypeKind::String), 0}, - TypeKind::String}, - {"t", - 2, - 3, - {kindBit(TypeKind::String), kindBit(TypeKind::String), kindBit(TypeKind::Record) | kindBit(TypeKind::List)}, - TypeKind::String}, - {"parseDecimal", 1, 2, {kindBit(TypeKind::String), kindBit(TypeKind::Int), 0}, TypeKind::Decimal}, - {"concatLists", - 1, - 255, - {kindBit(TypeKind::List), kindBit(TypeKind::List), kindBit(TypeKind::List)}, - TypeKind::Any}, - {"slice", 2, 3, {kindBit(TypeKind::List), kindBit(TypeKind::Int), kindBit(TypeKind::Int)}, TypeKind::Any}, - {"abs", 1, 1, {kNumeric, 0, 0}, TypeKind::Any}, - {"sqrt", - 2, - 3, - {kindBit(TypeKind::Int) | kindBit(TypeKind::Decimal), kindBit(TypeKind::Int), kindBit(TypeKind::String)}, - TypeKind::Decimal}, - {"stdev", 2, 3, {kindBit(TypeKind::List), kindBit(TypeKind::Int), kindBit(TypeKind::String)}, TypeKind::Any}, - {"rsd", 2, 3, {kindBit(TypeKind::List), kindBit(TypeKind::Int), kindBit(TypeKind::String)}, TypeKind::Decimal}, - {"dateAdd", - 3, - 3, - {kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String), kindBit(TypeKind::Int), kindBit(TypeKind::String)}, - TypeKind::Any}, - {"dateRange", - 2, - 2, - {kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String), - kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String), 0}, - TypeKind::String}, - {"refusalText", 1, 1, {kindBit(TypeKind::Record), 0, 0}, TypeKind::String}, -}}; -// NOLINTEND(modernize-use-designated-initializers) - -/// @brief The signature of a function. -/// @param function The function. -/// @return Its entry in `kFunctions`. -[[nodiscard]] constexpr FunctionSpec const& functionSpec(FunctionId function) { - return kFunctions.at(static_cast(function)); -} - -/// @brief The position of a function's optional rounding mode, `"halfEven"` or `"halfUp"`. -/// @param function The function. -/// @return The argument index of its mode, or empty for a function that does not round. -[[nodiscard]] constexpr std::optional modeArgument(FunctionId function) noexcept { - if (function == FunctionId::Round || function == FunctionId::DecimalText || function == FunctionId::Sqrt || - function == FunctionId::Stdev || function == FunctionId::Rsd) { - return 2; - } - return std::nullopt; -} - -/// @brief Reads a rounding mode: `"halfEven"`, ties to the even neighbour, or `"halfUp"`, ties away from zero. -/// @param mode The mode's value. -/// @return The mode, or empty for any other value. -[[nodiscard]] inline std::optional roundingMode(Value const& mode) { - std::string const* const name = mode.asString(); - if (name != nullptr && *name == "halfEven") { - return math::RoundingMode::HalfEven; - } - if (name != nullptr && *name == "halfUp") { - return math::RoundingMode::HalfAwayFromZero; - } - return std::nullopt; -} - -/// @brief The units `dateAdd` adds. -inline constexpr std::array kDateUnits = {"days", "weeks", "months", "years", "hours", "minutes"}; - -/// @brief The names `{"env": ...}` reads. -inline constexpr std::array kEnvNames = {"widthClass", "locale", "platform", - "online", "backend", "context"}; - -/// @brief The names `{"session": ...}` reads. -inline constexpr std::array kSessionNames = {"principal", "userName", "displayName", - "userKey", "tenant", "authenticated"}; - -/// @brief Whether a name is one of a closed set. -/// @param names The set. -/// @param name The candidate. -/// @return Whether @p name is in @p names. -template -[[nodiscard]] constexpr bool oneOf(std::array const& names, std::string_view name) noexcept { - return std::ranges::find(names, name) != names.end(); -} - /// @brief Splits `head.a.b` into its segments. /// @param text The dotted path. /// @return The segments, or the reason the path is malformed. -[[nodiscard]] inline std::expected, std::string> splitPath(std::string_view text) { - std::vector segments; - std::size_t start = 0; - for (;;) { - std::size_t const dot = text.find('.', start); - std::string_view const segment = - text.substr(start, dot == std::string_view::npos ? std::string_view::npos : dot - start); - if (segment.empty()) { - return std::unexpected("`" + std::string{text} + "` has an empty segment"); - } - segments.emplace_back(segment); - if (dot == std::string_view::npos) { - return segments; - } - start = dot + 1; - } -} - -/// @brief Reads one JSON expression tree into `Expr` nodes, counting them against the size bound. -// NOLINTBEGIN(misc-no-recursion): an expression is a tree and parsing descends it; the node bound limits the depth. -class ExprParser { -public: - /// @brief The keys a form may carry beside its own. - struct FormKeys { - /// @brief The form's own key. - std::string_view key; - /// @brief The form. - ExprKind kind; - /// @brief The keys allowed beside it. - std::array companions; - }; - - /// @brief Parses @p json, whose JSON Pointer is @p path. - /// @param json The expression. - /// @param path Its JSON Pointer. - /// @return The expression, or the refusal. - [[nodiscard]] std::expected parse(Json const& json, std::string const& path) { - return node(json, path); - } - -private: - // NOLINTBEGIN(modernize-use-designated-initializers): one row per form reads as a table. - static constexpr std::array kForms = {{ - {"lit", ExprKind::Literal, {}}, - {"ref", ExprKind::Ref, {}}, - {"row", ExprKind::Row, {}}, - {"query", ExprKind::Query, {}}, - {"pending", ExprKind::Pending, {}}, - {"error", ExprKind::Error, {}}, - {"result", ExprKind::Result, {}}, - {"errorKind", ExprKind::ErrorKind, {}}, - {"refusal", ExprKind::Refusal, {}}, - {"can", ExprKind::Can, {}}, - {"pref", ExprKind::Pref, {}}, - {"fn", ExprKind::Call, {"args", ""}}, - {"t", ExprKind::Call, {"fallback", "args"}}, - {"if", ExprKind::If, {}}, - {"obj", ExprKind::Object, {}}, - {"list", ExprKind::List, {}}, - {"map", ExprKind::Map, {"as", "to"}}, - {"filter", ExprKind::Filter, {"as", "where"}}, - {"sort", ExprKind::Sort, {"as", "by", "order"}}, - {"runs", ExprKind::Runs, {"as", "by"}}, - {"env", ExprKind::Env, {}}, - {"session", ExprKind::Session, {}}, - {"host", ExprKind::Host, {}}, - {"get", ExprKind::Get, {"path", ""}}, - }}; - // NOLINTEND(modernize-use-designated-initializers) - - [[nodiscard]] static std::unexpected refuse(std::string const& path, std::string reason) { - return std::unexpected(Refusal{.document = {}, .path = path, .reason = std::move(reason)}); - } - - [[nodiscard]] static std::string const* text(Json const& json) { return std::get_if(&json.data); } - - [[nodiscard]] static Json const* member(Json::object_t const& object, std::string_view key) { - auto const* const found = object.find(key); - return found == object.end() ? nullptr : &found->second; - } - - [[nodiscard]] static ExprPtr literal(Value value, std::string path) { - auto made = std::make_shared(); - made->kind = ExprKind::Literal; - made->literal = std::move(value); - made->path = std::move(path); - return made; - } - - [[nodiscard]] std::expected node(Json const& json, std::string const& path) { - if (++_count > kMaxExpressionNodes) { - return refuse(path, "the expression has more than " + std::to_string(kMaxExpressionNodes) + - " nodes, the bound of expr/1"); - } - if (std::holds_alternative(json.data)) { - return refuse(path, R"(a list is written {"list": [...]}, a constant list {"lit": [...]})"); - } - auto const* const object = std::get_if(&json.data); - if (object == nullptr) { - auto value = valueFromJson(json); - if (!value) { - return refuse(path, value.error()); - } - return literal(std::move(*value), path); - } - auto made = std::make_shared(); - made->path = path; - if (auto refused = form(*made, *object, path)) { - return std::unexpected(std::move(*refused)); - } - return made; - } - - [[nodiscard]] std::optional form(Expr& made, Json::object_t const& object, std::string const& path) { - FormKeys const* chosen = nullptr; - for (auto const& [key, value] : object) { - static_cast(value); - for (FormKeys const& candidate : kForms) { - if (candidate.key != key) { - continue; - } - if (chosen != nullptr) { - return refuse(path, "an expression has one form; found `" + std::string{chosen->key} + "` and `" + - key + "`") - .error(); - } - chosen = &candidate; - } - } - if (chosen == nullptr) { - if (object.empty()) { - return refuse(path, "an empty object is not an expression; a constant record is {\"lit\": {}}") - .error(); - } - return refuse(path, "`" + object.begin()->first + "` is not an expression form of expr/1").error(); - } - for (auto const& [key, value] : object) { - static_cast(value); - if (key != chosen->key && !std::ranges::contains(chosen->companions, key)) { - return refuse(pointerAppend(path, key), - "`" + key + "` does not belong to the `" + std::string{chosen->key} + "` form") - .error(); - } - } - Json const& primary = *member(object, chosen->key); - std::string const primaryPath = pointerAppend(path, chosen->key); - made.kind = chosen->kind; - switch (chosen->kind) { - case ExprKind::Literal: { - auto value = valueFromJson(primary); - if (!value) { - return refuse(primaryPath, value.error()).error(); - } - made.literal = std::move(*value); - return std::nullopt; - } - case ExprKind::Ref: - case ExprKind::Pref: - return dotted(made, primary, primaryPath); - case ExprKind::Row: - return rowPath(made, primary, primaryPath); - case ExprKind::Query: - case ExprKind::Pending: - case ExprKind::Error: - case ExprKind::Result: - case ExprKind::ErrorKind: - case ExprKind::Refusal: - case ExprKind::Can: - return controlName(made, primary, primaryPath, chosen->key); - case ExprKind::Env: - case ExprKind::Session: - case ExprKind::Host: - return clientName(made, primary, primaryPath, chosen->key); - case ExprKind::Call: - if (chosen->key == "t") { - return translate(made, object, path); - } - return call(made, object, path); - case ExprKind::If: - return operands(made.args, primary, primaryPath, 3, "`if` takes [condition, then, else]"); - case ExprKind::List: - return operands(made.args, primary, primaryPath, 0, "`list` takes an array of expressions"); - case ExprKind::Object: - return fields(made.fields, primary, primaryPath); - case ExprKind::Get: - return get(made, object, path); - case ExprKind::Map: - case ExprKind::Filter: - case ExprKind::Sort: - case ExprKind::Runs: - default: - return comprehension(made, object, path); - } - } - - [[nodiscard]] static std::optional dotted(Expr& made, Json const& primary, std::string const& path) { - std::string const* const dottedPath = text(primary); - if (dottedPath == nullptr) { - return refuse(path, "a name and path is written as a string `name.path`").error(); - } - auto segments = splitPath(*dottedPath); - if (!segments) { - return refuse(path, segments.error()).error(); - } - if (!isName(segments->front())) { - return refuse(path, "`" + segments->front() + "` is not a name").error(); - } - made.name = std::move(segments->front()); - made.fieldPath.assign(std::make_move_iterator(segments->begin() + 1), - std::make_move_iterator(segments->end())); - return std::nullopt; - } - - [[nodiscard]] static std::optional rowPath(Expr& made, Json const& primary, std::string const& path) { - std::string const* const dottedPath = text(primary); - if (dottedPath == nullptr) { - return refuse(path, "`row` names a field path as a string, \"\" for the whole row").error(); - } - if (dottedPath->empty()) { - return std::nullopt; - } - auto segments = splitPath(*dottedPath); - if (!segments) { - return refuse(path, segments.error()).error(); - } - made.fieldPath = std::move(*segments); - return std::nullopt; - } - - [[nodiscard]] static std::optional controlName(Expr& made, Json const& primary, std::string const& path, - std::string_view key) { - std::string const* const name = text(primary); - bool const can = made.kind == ExprKind::Can; - bool const hostCommand = can && name != nullptr && name->starts_with("host:") && name->size() > 5; - if (name == nullptr || (!isName(*name) && !hostCommand)) { - return refuse(path, "`" + std::string{key} + "` takes the name of a " + - (can ? "mutation, query or `host:` command" : "query or mutation")) - .error(); - } - made.name = *name; - return std::nullopt; - } - - [[nodiscard]] static std::optional clientName(Expr& made, Json const& primary, std::string const& path, - std::string_view key) { - std::string const* const name = text(primary); - bool known = name != nullptr && !name->empty(); - if (known && made.kind == ExprKind::Env) { - known = oneOf(kEnvNames, *name); - } else if (known && made.kind == ExprKind::Session) { - known = oneOf(kSessionNames, *name); - } - if (!known) { - return refuse(path, "`" + std::string{key} + "` does not read this name").error(); - } - made.name = *name; - return std::nullopt; - } - - [[nodiscard]] std::optional operands(std::vector& out, Json const& primary, - std::string const& path, std::size_t exactly, char const* shape) { - auto const* const array = std::get_if(&primary.data); - if (array == nullptr || (exactly != 0 && array->size() != exactly)) { - return refuse(path, shape).error(); - } - for (std::size_t index = 0; index < array->size(); ++index) { - auto operand = node(array->at(index), pointerAppend(path, index)); - if (!operand) { - return std::move(operand.error()); - } - out.push_back(std::move(*operand)); - } - return std::nullopt; - } - - [[nodiscard]] std::optional fields(std::vector>& out, Json const& primary, - std::string const& path) { - auto const* const object = std::get_if(&primary.data); - if (object == nullptr) { - return refuse(path, "`obj` takes an object of expressions").error(); - } - for (auto const& [key, value] : *object) { - auto field = node(value, pointerAppend(path, key)); - if (!field) { - return std::move(field.error()); - } - out.emplace_back(key, std::move(*field)); - } - return std::nullopt; - } - - [[nodiscard]] std::optional call(Expr& made, Json::object_t const& object, std::string const& path) { - std::string const* const name = text(*member(object, "fn")); - std::string const namePath = pointerAppend(path, "fn"); - if (name == nullptr) { - return refuse(namePath, "`fn` names a function as a string").error(); - } - auto const index = - std::ranges::distance(kFunctions.begin(), std::ranges::find(kFunctions, *name, &FunctionSpec::name)); - if (std::cmp_equal(index, kFunctions.size())) { - return refuse(namePath, "the function `" + *name + "` is not in expr/1").error(); - } - FunctionSpec const& spec = *std::next(kFunctions.begin(), index); - made.function = static_cast(index); - if (Json const* const args = member(object, "args")) { - if (auto refused = operands(made.args, *args, pointerAppend(path, "args"), 0, - "`args` takes an array of expressions")) { - return refused; - } - } - if (made.args.size() < spec.minArgs || made.args.size() > spec.maxArgs) { - std::string arity = std::to_string(static_cast(spec.minArgs)); - if (spec.maxArgs == 255) { - arity += " or more"; - } else if (spec.maxArgs != spec.minArgs) { - arity += " to " + std::to_string(static_cast(spec.maxArgs)); - } - return refuse(path, - "`" + *name + "` takes " + arity + " arguments, not " + std::to_string(made.args.size())) - .error(); - } - return std::nullopt; - } - - [[nodiscard]] std::optional translate(Expr& made, Json::object_t const& object, std::string const& path) { - made.function = FunctionId::Translate; - Json const& keyJson = *member(object, "t"); - std::string const* const key = text(keyJson); - Json const* const fallback = member(object, "fallback"); - std::string const* const fallbackText = fallback == nullptr ? nullptr : text(*fallback); - std::string const keyPath = pointerAppend(path, "t"); - Json const* const keyExpression = wrapped(keyJson); - if (keyExpression == nullptr && (key == nullptr || key->empty())) { - return refuse(keyPath, R"(`t` names a message key as a string, or as {"expr": e} for an expression)") - .error(); - } - if (fallbackText == nullptr) { - return refuse(pointerAppend(path, "fallback"), "`t` needs its `fallback` text as a string").error(); - } - if (keyExpression != nullptr) { - auto computed = node(*keyExpression, pointerAppend(keyPath, "expr")); - if (!computed) { - return std::move(computed.error()); - } - made.args.push_back(std::move(*computed)); - } else { - made.args.push_back(literal(*key, keyPath)); - } - made.args.push_back(literal(*fallbackText, pointerAppend(path, "fallback"))); - if (Json const* const args = member(object, "args"); args != nullptr && wrapped(*args) != nullptr) { - auto list = node(*wrapped(*args), pointerAppend(pointerAppend(path, "args"), "expr")); - if (!list) { - return std::move(list.error()); - } - made.args.push_back(std::move(*list)); - } else if (args != nullptr) { - auto record = std::make_shared(); - record->kind = ExprKind::Object; - record->path = pointerAppend(path, "args"); - if (auto refused = fields(record->fields, *args, record->path)) { - return refused; - } - made.args.push_back(std::move(record)); - } - return std::nullopt; - } - - /// The expression in `{"expr": e}`, the wrapper `t` takes a computed key or argument list in; null when @p json - /// is anything else. - [[nodiscard]] static Json const* wrapped(Json const& json) { - auto const* const object = std::get_if(&json.data); - if (object == nullptr || object->size() != 1) { - return nullptr; - } - return member(*object, "expr"); - } - - [[nodiscard]] std::optional get(Expr& made, Json::object_t const& object, std::string const& path) { - Json const* const fieldPath = member(object, "path"); - if (fieldPath == nullptr) { - return refuse(path, "`get` needs `path`").error(); - } - std::string const* const dottedPath = text(*fieldPath); - std::string const pathPointer = pointerAppend(path, "path"); - if (dottedPath == nullptr || dottedPath->empty()) { - return refuse(pathPointer, "`get` reads a `path` written as a string `a.b.0`").error(); - } - auto segments = splitPath(*dottedPath); - if (!segments) { - return refuse(pathPointer, segments.error()).error(); - } - auto source = node(*member(object, "get"), pointerAppend(path, "get")); - if (!source) { - return std::move(source.error()); - } - made.fieldPath = std::move(*segments); - made.args.push_back(std::move(*source)); - return std::nullopt; - } - - [[nodiscard]] std::optional comprehension(Expr& made, Json::object_t const& object, - std::string const& path) { - std::string_view sourceKey = "filter"; - std::string_view bodyKey = "where"; - if (made.kind == ExprKind::Map) { - sourceKey = "map"; - bodyKey = "to"; - } else if (made.kind == ExprKind::Sort) { - sourceKey = "sort"; - bodyKey = "by"; - } else if (made.kind == ExprKind::Runs) { - sourceKey = "runs"; - bodyKey = "by"; - } - Json const* const variable = member(object, "as"); - Json const* const body = member(object, bodyKey); - std::string const* const name = variable == nullptr ? nullptr : text(*variable); - if (name == nullptr || !isName(*name)) { - return refuse(pointerAppend(path, "as"), "`" + std::string{sourceKey} + "` names its element with `as`") - .error(); - } - if (body == nullptr) { - return refuse(path, "`" + std::string{sourceKey} + "` needs `" + std::string{bodyKey} + "`").error(); - } - made.name = *name; - auto source = node(*member(object, sourceKey), pointerAppend(path, sourceKey)); - if (!source) { - return std::move(source.error()); - } - auto each = node(*body, pointerAppend(path, bodyKey)); - if (!each) { - return std::move(each.error()); - } - made.args.push_back(std::move(*source)); - made.args.push_back(std::move(*each)); - if (Json const* const order = member(object, "order"); order != nullptr && made.kind == ExprKind::Sort) { - auto direction = node(*order, pointerAppend(path, "order")); - if (!direction) { - return std::move(direction.error()); - } - made.args.push_back(std::move(*direction)); - } - return std::nullopt; - } - - std::size_t _count = 0; - // NOLINTEND(misc-no-recursion) -}; +[[nodiscard]] MORPH_API std::expected, std::string> splitPath(std::string_view text); } // namespace detail @@ -838,20 +194,12 @@ class ExprParser { /// @param json The expression's JSON. /// @param path Its JSON Pointer inside the document, carried by every node and every refusal. /// @return The expression, or the refusal. -[[nodiscard]] inline std::expected parseExpression(Json const& json, std::string const& path = "") { - return detail::ExprParser{}.parse(json, path); -} +[[nodiscard]] MORPH_API std::expected parseExpression(Json const& json, + std::string const& path = ""); /// @brief The names of the `expr/1` library, in `FunctionId` order. /// @return The names. -[[nodiscard]] inline std::vector functionNames() { - std::vector names; - names.reserve(detail::kFunctions.size()); - for (auto const& spec : detail::kFunctions) { - names.push_back(spec.name); - } - return names; -} +[[nodiscard]] MORPH_API std::vector functionNames(); /// @brief What an expression's names resolve to, for `checkExpression`: the document's scopes implement it. class NameResolver { @@ -935,323 +283,13 @@ class PermissiveResolver final : public NameResolver { namespace detail { -/// @brief The static type of a literal. -/// @param value The literal. -/// @return Its type; `any` for `null`. -[[nodiscard]] inline Type typeOfValue(Value const& value) { - // The type kind of each value kind, indexed by `ValueKind`; `null` has no type of its own. - constexpr std::array kTypes = {TypeKind::Any, TypeKind::Bool, TypeKind::Int, - TypeKind::String, TypeKind::Decimal, TypeKind::Quantity, - TypeKind::Timestamp, TypeKind::List, TypeKind::Record}; - return Type::of(kTypes.at(static_cast(value.kind()))); -} - /// @brief The type a field path reads from a value of a known type. /// @param type The type of the head. /// @param head The head's name, for the reason. /// @param path The path. /// @return `any` when the path can read something, or why it cannot. -[[nodiscard]] inline std::expected typeAlong(Type const& type, std::string_view head, - std::span path) { - if (path.empty()) { - return type; - } - if (type.kind == TypeKind::Any || type.kind == TypeKind::Record || type.kind == TypeKind::List) { - return Type::any(); - } - return std::unexpected("`" + std::string{head} + "` is " + type.name() + " and has no field `" + path.front() + - "`"); -} - -/// @brief Walks an expression once, resolving names and checking the statically known types. -// NOLINTBEGIN(misc-no-recursion): an expression is a tree and checking descends it; the node bound limits the depth. -class ExprChecker { -public: - /// @brief Checks against @p resolver. - /// @param resolver What the names resolve to. - explicit ExprChecker(NameResolver const& resolver) : _resolver{&resolver} {} - - /// @brief Checks one node and its operands. - /// @param expr The node. - /// @return Its static type, or the refusal. - [[nodiscard]] std::expected check(Expr const& expr) { - switch (expr.kind) { - case ExprKind::Literal: - return typeOfValue(expr.literal); - case ExprKind::Ref: - return reference(expr); - case ExprKind::Row: - return wrap(expr, _resolver->row(expr.fieldPath)); - case ExprKind::Query: - case ExprKind::Pending: - case ExprKind::Error: - case ExprKind::Result: - case ExprKind::ErrorKind: - case ExprKind::Refusal: - case ExprKind::Can: - return wrap(expr, _resolver->control(expr.kind, expr.name)); - case ExprKind::Pref: - return wrap(expr, _resolver->pref(expr.name, expr.fieldPath)); - case ExprKind::Env: - return Type::of(expr.name == "online" ? TypeKind::Bool : TypeKind::String, expr.name != "online"); - case ExprKind::Session: - return Type::of(expr.name == "authenticated" ? TypeKind::Bool : TypeKind::String, - expr.name != "authenticated"); - case ExprKind::Host: - return Type::any(); - case ExprKind::If: - return choice(expr); - case ExprKind::Object: { - for (auto const& [name, field] : expr.fields) { - static_cast(name); - auto checked = check(*field); - if (!checked) { - return checked; - } - } - return Type::of(TypeKind::Record); - } - case ExprKind::List: { - for (ExprPtr const& item : expr.args) { - auto checked = check(*item); - if (!checked) { - return checked; - } - } - return Type::of(TypeKind::List); - } - case ExprKind::Map: - case ExprKind::Filter: - case ExprKind::Sort: - case ExprKind::Runs: - return comprehension(expr); - case ExprKind::Get: { - auto source = check(*expr.args.at(0)); - if (!source) { - return source; - } - if (!admitsKind(*source, kindBit(TypeKind::Record) | kindBit(TypeKind::List))) { - return refuse(expr, "`get` reads a path out of a record or a list, not " + source->name()); - } - return Type::any(); - } - case ExprKind::Call: - default: - return call(expr); - } - } - -private: - [[nodiscard]] static std::expected wrap(Expr const& expr, std::expected type) { - if (!type) { - return std::unexpected(Refusal{.document = {}, .path = expr.path, .reason = std::move(type.error())}); - } - return std::move(*type); - } - - [[nodiscard]] static std::unexpected refuse(Expr const& expr, std::string reason) { - return std::unexpected(Refusal{.document = {}, .path = expr.path, .reason = std::move(reason)}); - } - - [[nodiscard]] std::expected reference(Expr const& expr) { - for (auto const& [name, type] : std::views::reverse(_locals)) { - if (name == expr.name) { - return wrap(expr, typeAlong(type, expr.name, expr.fieldPath)); - } - } - return wrap(expr, _resolver->ref(expr.name, expr.fieldPath)); - } - - [[nodiscard]] static bool admitsKind(Type const& type, KindSet accepted) { - return type.kind == TypeKind::Any || (accepted & kindBit(type.kind)) != 0; - } - - [[nodiscard]] std::expected condition(Expr const& expr, std::string_view what) { - auto type = check(expr); - if (type && !admitsKind(*type, kindBit(TypeKind::Bool))) { - return refuse(expr, std::string{what} + " is " + type->name() + "; expected bool"); - } - return type; - } - - [[nodiscard]] std::expected choice(Expr const& expr) { - auto cond = condition(*expr.args.at(0), "the condition of `if`"); - if (!cond) { - return cond; - } - auto then = check(*expr.args.at(1)); - if (!then) { - return then; - } - auto otherwise = check(*expr.args.at(2)); - if (!otherwise) { - return otherwise; - } - if (then->kind == otherwise->kind && then->kind != TypeKind::List) { - return Type::of(then->kind, then->optional || otherwise->optional); - } - return Type::any(); - } - - [[nodiscard]] std::expected comprehension(Expr const& expr) { - auto source = check(*expr.args.at(0)); - if (!source) { - return source; - } - std::string_view form = "filter"; - if (expr.kind == ExprKind::Map) { - form = "map"; - } else if (expr.kind == ExprKind::Sort) { - form = "sort"; - } else if (expr.kind == ExprKind::Runs) { - form = "runs"; - } - if (!admitsKind(*source, kindBit(TypeKind::List))) { - return refuse(*expr.args.at(0), "`" + std::string{form} + "` runs over a list, not " + source->name()); - } - Type element = source->element ? *source->element : Type::any(); - _locals.emplace_back(expr.name, element); - auto body = expr.kind == ExprKind::Filter ? condition(*expr.args.at(1), "the `where` of `filter`") - : check(*expr.args.at(1)); - _locals.pop_back(); - if (!body) { - return body; - } - if (expr.kind == ExprKind::Map) { - return Type::listOf(*body); - } - if (expr.kind == ExprKind::Runs) { - return Type::listOf(Type::of(TypeKind::Record)); - } - if (expr.kind == ExprKind::Sort && expr.args.size() > 2) { - auto order = check(*expr.args.at(2)); - if (!order) { - return order; - } - if (!admitsKind(*order, kindBit(TypeKind::String))) { - return refuse(*expr.args.at(2), "the `order` of `sort` is " + order->name() + "; expected string"); - } - } - return Type::listOf(std::move(element)); - } - - [[nodiscard]] std::expected call(Expr const& expr) { - FunctionSpec const& spec = functionSpec(expr.function); - std::vector types; - for (std::size_t index = 0; index < expr.args.size(); ++index) { - auto type = check(*expr.args.at(index)); - if (!type) { - return type; - } - KindSet const accepted = spec.accepts.at(std::min(index, 2)); - if (!admitsKind(*type, accepted)) { - return refuse(*expr.args.at(index), "argument " + std::to_string(index + 1) + " of `" + - std::string{spec.name} + "` is " + type->name() + - ", which it does not take"); - } - types.push_back(std::move(*type)); - } - if (auto refused = literalRefusal(expr)) { - return std::unexpected(std::move(*refused)); - } - if (spec.result != TypeKind::Any) { - return Type::of(spec.result, true); - } - if (expr.function == FunctionId::ConcatLists) { - return concatenated(types); - } - if (expr.function == FunctionId::Slice) { - Type const& source = types.front(); - return Type::listOf(source.element ? *source.element : Type::any(), true); - } - return numericResult(expr.function, types); - } - - /// The checks of an argument written as a literal: a rounding mode and a `dateAdd` unit are checked at load, - /// because a wrong one is a wrong value, not a wrong look; a `t` fallback must be in the message subset. - [[nodiscard]] static std::optional literalRefusal(Expr const& expr) { - auto const literalText = [&expr](std::size_t index) -> std::string const* { - if (index >= expr.args.size() || expr.args.at(index)->kind != ExprKind::Literal) { - return nullptr; - } - return expr.args.at(index)->literal.asString(); - }; - if (auto const position = modeArgument(expr.function)) { - std::string const* const mode = literalText(*position); - if (mode != nullptr && !roundingMode(Value{*mode})) { - return refuse(*expr.args.at(*position), "the rounding mode is `halfEven` or `halfUp`").error(); - } - } - if (std::string const* const unit = literalText(2); - expr.function == FunctionId::DateAdd && unit != nullptr && !oneOf(kDateUnits, *unit)) { - return refuse(*expr.args.at(2), "the unit is `days`, `weeks`, `months`, `years`, `hours` or `minutes`") - .error(); - } - if (std::string const* const pattern = literalText(1); - expr.function == FunctionId::Translate && pattern != nullptr) { - auto parsed = parseMessage(*pattern); - if (!parsed) { - return refuse(*expr.args.at(1), "the fallback is outside the ui/1 message subset: " + parsed.error()) - .error(); - } - } - return std::nullopt; - } - - /// `concatLists`'s type: `list` when every element type that is known is `T`, else `list`. - [[nodiscard]] static Type concatenated(std::vector const& types) { - std::optional common; - for (Type const& type : types) { - if (type.isAny() || !type.element || type.element->isAny()) { - continue; - } - if (!common) { - common = *type.element; - } else if (!(*common == *type.element)) { - return Type::listOf(Type::any(), true); - } - } - return Type::listOf(common.value_or(Type::any()), true); - } - - [[nodiscard]] static Type numericResult(FunctionId function, std::vector const& types) { - if (function == FunctionId::Coalesce || function == FunctionId::Sum || function == FunctionId::Mean || - function == FunctionId::Min || function == FunctionId::Max || function == FunctionId::First || - function == FunctionId::Stdev) { - return Type::any(); - } - if (function == FunctionId::DateAdd) { - // The result keeps the value's form: a timestamp stays one, a date or ISO text stays text. - Type const& value = types.front(); - bool const known = value.kind == TypeKind::Timestamp || value.kind == TypeKind::String; - return known ? Type::of(value.kind, true) : Type::any(); - } - if (function == FunctionId::Neg || function == FunctionId::Round || function == FunctionId::Abs) { - return Type::of(types.front().kind, true); - } - Type const& lhs = types.at(0); - Type const& rhs = types.at(1); - if (lhs.isAny() || rhs.isAny()) { - return Type::any(); - } - bool const lhsQuantity = lhs.kind == TypeKind::Quantity; - bool const rhsQuantity = rhs.kind == TypeKind::Quantity; - if (lhsQuantity || rhsQuantity) { - if (function == FunctionId::Div && lhsQuantity && rhsQuantity) { - return Type::of(TypeKind::Decimal, true); - } - return Type::of(TypeKind::Quantity, true); - } - if (lhs.kind == TypeKind::Int && rhs.kind == TypeKind::Int && function != FunctionId::Div) { - return Type::of(TypeKind::Int, true); - } - return function == FunctionId::Div ? Type::any() : Type::of(TypeKind::Decimal, true); - } - - NameResolver const* _resolver; - std::vector> _locals; - // NOLINTEND(misc-no-recursion) -}; +[[nodiscard]] MORPH_API std::expected typeAlong(Type const& type, std::string_view head, + std::span path); } // namespace detail @@ -1263,9 +301,7 @@ class ExprChecker { /// @param expr The expression. /// @param resolver What the document's names resolve to. /// @return The expression's static type (`any` where it cannot be known), or the refusal. -[[nodiscard]] inline std::expected checkExpression(Expr const& expr, NameResolver const& resolver) { - return detail::ExprChecker{resolver}.check(expr); -} +[[nodiscard]] MORPH_API std::expected checkExpression(Expr const& expr, NameResolver const& resolver); /// @brief One unit of the server's unit systems, as `x-unitAlternatives` declares it. struct UnitInfo { @@ -1369,27 +405,7 @@ class Environment { /// @param value The value. /// @param path The segments. /// @return The value at the path, or `null` when a segment does not exist. -[[nodiscard]] inline Value walk(Value const& value, std::span path) { - Value const* current = &value; - for (std::string const& segment : path) { - if (ValueList const* const items = current->asList()) { - // A segment past the largest index is out of range, not wrapped onto an element that exists. - std::size_t index = 0; - char const* const end = std::to_address(segment.end()); - auto const [stop, error] = std::from_chars(std::to_address(segment.begin()), end, index); - if (error != std::errc{} || stop != end || index >= items->size()) { - return Value{}; - } - current = &items->at(index); - continue; - } - current = current->field(segment); - if (current == nullptr) { - return Value{}; - } - } - return *current; -} +[[nodiscard]] MORPH_API Value walk(Value const& value, std::span path); /// @brief The form of a value the date functions read. enum class DateForm : std::uint8_t { @@ -1417,48 +433,7 @@ struct DateValue { /// `""` are absent. /// @param value The value. /// @return The reading. -[[nodiscard]] inline DateValue readDateValue(Value const& value) { - if (value.isNull()) { - return {}; - } - if (time::DateTime const* const instant = value.asTimestamp()) { - return {.form = DateForm::Timestamp, .date = {}, .instant = *instant}; - } - std::string const* const text = value.asString(); - if (text == nullptr) { - return {.form = DateForm::Unreadable, .date = {}, .instant = {}}; - } - if (text->empty()) { - return {}; - } - if (text->size() == 10 && text->at(4) == '-' && text->at(7) == '-') { - auto const field = [&text](std::size_t offset, std::size_t count) -> std::optional { - unsigned parsed = 0; - std::string_view const digits = std::string_view{*text}.substr(offset, count); - char const* const end = std::to_address(digits.end()); - auto const [stop, error] = std::from_chars(std::to_address(digits.begin()), end, parsed); - if (error != std::errc{} || stop != end) { - return std::nullopt; - } - return parsed; - }; - auto const year = field(0, 4); - auto const month = field(5, 2); - auto const day = field(8, 2); - if (year && month && day) { - std::chrono::year_month_day const date{std::chrono::year{static_cast(*year)}, - std::chrono::month{*month}, std::chrono::day{*day}}; - if (date.ok()) { - return {.form = DateForm::Date, .date = date, .instant = {}}; - } - return {.form = DateForm::Unreadable, .date = {}, .instant = {}}; - } - } - if (auto const parsed = time::DateTime::fromIso8601(*text)) { - return {.form = DateForm::InstantText, .date = {}, .instant = *parsed}; - } - return {.form = DateForm::Unreadable, .date = {}, .instant = {}}; -} +[[nodiscard]] MORPH_API DateValue readDateValue(Value const& value); namespace detail { @@ -1475,33 +450,7 @@ struct Number { /// @brief Takes a numeric value apart. /// @param value The value. /// @return The number, or `std::nullopt` when it is not one. -[[nodiscard]] inline std::optional numeric(Value const& value) { - if (std::int64_t const* const whole = value.asInt()) { - return Number{.value = math::Rational{*whole, math::DecimalPlaces{0}}, .integer = true, .unit = nullptr}; - } - if (Decimal const* const decimal = value.asDecimal()) { - return Number{.value = decimal->value, .integer = false, .unit = nullptr}; - } - if (Quantity const* const quantity = value.asQuantity()) { - return Number{.value = quantity->value, .integer = false, .unit = &quantity->unit}; - } - return std::nullopt; -} - -/// @brief Builds a numeric value. -/// @param value The exact value. -/// @param integer Whether every operand was an `int`. -/// @param unit The unit, or `nullptr`. -/// @return A quantity with a unit; an `int` when integral and every operand was one; a decimal otherwise. -[[nodiscard]] inline Value makeNumber(math::Rational const& value, bool integer, std::string const* unit) { - if (unit != nullptr) { - return Quantity{.value = value, .unit = *unit}; - } - if (integer && value.isInteger()) { - return Value{value.numerator}; - } - return Decimal{value}; -} +[[nodiscard]] MORPH_API std::optional numeric(Value const& value); /// @brief Converts an exact value between two units of one dimension. /// @param value The value in @p from. @@ -1510,323 +459,33 @@ struct Number { /// @param units The unit table. /// @return The value in @p target, its places widened by the decimal places of the conversion ratio; `std::nullopt` /// when the units do not convert or the result overflows. -[[nodiscard]] inline std::optional convertUnit(math::Rational const& value, std::string_view from, - std::string_view target, UnitTable const& units) { - if (from == target) { - return value; - } - auto factor = [&units](std::string_view unit) { - auto const found = units.find(unit); - if (found == units.end()) { - return std::pair{std::string{unit}, math::Rational{1, math::DecimalPlaces{0}}}; - } - return std::pair{found->second.canonical, found->second.toCanonical}; - }; - auto const [fromBase, fromFactor] = factor(from); - auto const [toBase, toFactor] = factor(target); - if (fromBase != toBase) { - return std::nullopt; - } - auto const ratio = - math::checkedDiv(math::Rational{math::Numerator{fromFactor.numerator}, - math::Denominator{fromFactor.denominator}, math::DecimalPlaces{0}}, - math::Rational{math::Numerator{toFactor.numerator}, math::Denominator{toFactor.denominator}, - math::DecimalPlaces{0}}); - if (!ratio) { - return std::nullopt; - } - auto converted = math::checkedMul(value, *ratio); - if (!converted) { - return std::nullopt; - } - // The places widen by the ratio's own decimal places, so 1500 mg shows as 1.500 g rather than rounding to 2 g; - // a ratio that is not a terminating decimal adds none. - auto denominator = static_cast(ratio->denominator); - std::uint32_t twos = 0; - std::uint32_t fives = 0; - for (; denominator % 2U == 0; denominator /= 2U) { - ++twos; - } - for (; denominator % 5U == 0; denominator /= 5U) { - ++fives; - } - std::uint32_t const extra = denominator == 1 ? std::max(twos, fives) : 0U; - converted->decimalPlaces = - math::DecimalPlaces{std::min(value.decimalPlaces.value + extra, math::kMaxDecimalPlaces)}; - return *converted; -} +[[nodiscard]] MORPH_API std::optional convertUnit(math::Rational const& value, std::string_view from, + std::string_view target, UnitTable const& units); /// @brief The display text of a unit. /// @param unit The unit id. /// @param units The unit table. /// @return Its display text, or the id. -[[nodiscard]] inline std::string unitDisplay(std::string const& unit, UnitTable const& units) { - auto const found = units.find(unit); - return found == units.end() || found->second.display.empty() ? unit : found->second.display; -} - -/// @brief The fraction digits a currency shows (ISO 4217's minor unit). -/// @param currency The currency code. -/// @return 0, 2 or 3. -[[nodiscard]] inline std::uint32_t currencyDigits(std::string_view currency) { - static constexpr std::array kNone = {"JPY", "KRW", "VND", "CLP", "ISK", - "UGX", "XAF", "XOF", "PYG"}; - static constexpr std::array kThree = {"BHD", "KWD", "OMR", "JOD", "TND", "IQD", "LYD"}; - if (oneOf(kNone, currency)) { - return 0; - } - return oneOf(kThree, currency) ? 3U : 2U; -} - -/// @brief A calendar day moved by whole months, its day of the month clamped to the target month's last day. -/// @param date The day. -/// @param months The months, negative to go back; bounded by the caller to the span of years 1 to 9999. -/// @return The moved day: `2026-01-31` plus one month is `2026-02-28`. -[[nodiscard]] inline std::chrono::year_month_day addMonths(std::chrono::year_month_day const& date, - std::int64_t months) { - std::chrono::year_month_day const moved = date + std::chrono::months{static_cast(months)}; - if (moved.ok()) { - return moved; - } - return std::chrono::year_month_day{ - std::chrono::year_month_day_last{moved.year(), std::chrono::month_day_last{moved.month()}}}; -} - -/// @brief The largest amount of each `dateAdd` unit that can stay within years 1 to 9999, in `kDateUnits` order. -/// -/// Compared with the amount before any `std::chrono` arithmetic, whose day and month counts are narrower than -/// `int64`, so a huge amount is reported rather than narrowed into a date. -inline constexpr std::array kDateSpans = {3'652'059, 521'723, 119'988, - 9'999, 87'649'416, 5'258'964'960}; - -/// @brief Whether a calendar day lies in years 1 to 9999, the years ISO text can write. -/// @param date The day. -/// @return Whether it is in range. -[[nodiscard]] inline bool inIsoRange(std::chrono::year_month_day const& date) { - return date.year() >= std::chrono::year{1} && date.year() <= std::chrono::year{9999}; -} - -/// @brief A calendar day as ISO text. -/// @param date The day. -/// @return `yyyy-MM-dd`. -[[nodiscard]] inline std::string isoDate(std::chrono::year_month_day const& date) { - return std::format("{:04}-{:02}-{:02}", static_cast(date.year()), static_cast(date.month()), - static_cast(date.day())); -} - -/// @brief A sample's exact moments over one denominator: the elements as integers `X = x * D`, their sum and the sum -/// of their squares, in 128 bits. -struct Moments { - /// @brief The count. - std::uint64_t count = 0; - /// @brief The common denominator `D`, the least common multiple of the elements' denominators. - std::uint64_t scale = 1; - /// @brief `|sum X|`. - math::detail::U128 sumMagnitude; - /// @brief `sum X^2`. - math::detail::U128 squares; - /// @brief The unit of a sample of quantities, the first element's; `nullptr` for plain numbers. - std::string const* unit = nullptr; -}; - -/// @brief The least common multiple of exact values' denominators, over which each value is an integer. -/// @param values The values, canonical. -/// @return The common denominator, or empty past `int64`. -[[nodiscard]] inline std::optional commonDenominator(std::vector const& values) { - std::uint64_t common = 1; - for (math::Rational const& value : values) { - auto const denominator = static_cast(value.denominator); - math::detail::U128 const product = math::detail::mulU64(common, denominator / std::gcd(common, denominator)); - if (product.hi != 0 || product.lo > static_cast(std::numeric_limits::max())) { - return std::nullopt; - } - common = product.lo; - } - return common; -} - -/// @brief A sample read for `stdev` and `rsd`: its moments, `null` without a report, or the reason to report. -using SampleReading = std::expected, std::string>; - -/// @brief The exact moments of a sample of numbers, or of quantities converted to the first element's unit. -/// -/// A `null` element makes the sample `null`; an element that is not a number, a quantity among plain numbers or units -/// that do not convert is a mismatch; a common denominator, an element or a sum that leaves its width overflows. -/// @param items The sample. -/// @param units The unit table. -/// @return The moments; empty for a `null` element; the reason for a mismatch or an overflow. -[[nodiscard]] inline SampleReading momentsOf(ValueList const& items, UnitTable const& units) { - using math::detail::U128; - std::vector values; - values.reserve(items.size()); - Moments moments; - for (std::size_t index = 0; index < items.size(); ++index) { - auto const number = numeric(items.at(index)); - if (items.at(index).isNull()) { - return std::optional{}; - } - if (!number) { - return std::unexpected(std::string{"an element is not a number"}); - } - if (index == 0) { - moments.unit = number->unit; - } else if ((moments.unit == nullptr) != (number->unit == nullptr)) { - return std::unexpected(std::string{"quantities and plain numbers do not combine"}); - } - auto converted = moments.unit == nullptr ? std::optional{number->value} - : convertUnit(number->value, *number->unit, *moments.unit, units); - if (!converted) { - return std::unexpected(std::string{"the elements' units do not convert"}); - } - values.push_back(*converted); - } - auto const scale = commonDenominator(values); - if (!scale) { - return std::unexpected(std::string{"the statistics overflow"}); - } - moments.scale = *scale; - U128 positive{}; - U128 negative{}; - for (math::Rational const& value : values) { - auto const denominator = static_cast(value.denominator); - U128 const scaled = math::detail::mulU64(math::detail::absU64(value.numerator), moments.scale / denominator); - auto squares = scaled.hi == 0 - ? math::detail::checkedAddU128(moments.squares, math::detail::mulU64(scaled.lo, scaled.lo)) - : std::nullopt; - auto sum = math::detail::checkedAddU128(value.numerator < 0 ? negative : positive, scaled); - if (!squares || !sum) { - return std::unexpected(std::string{"the statistics overflow"}); - } - moments.squares = *squares; - (value.numerator < 0 ? negative : positive) = *sum; - } - moments.count = values.size(); - moments.sumMagnitude = positive >= negative ? math::detail::wrappingSubU128(positive, negative) - : math::detail::wrappingSubU128(negative, positive); - return std::optional{moments}; -} - -/// @brief The standard deviation or the RSD of a sample, correctly rounded at @p places. -/// -/// With `n` elements `X = x * D`, `V = n * sum X^2 - (sum X)^2`: the sample standard deviation is the root of -/// `V * 10^(2 * places) / (n * (n - 1) * D^2)`, and the RSD in percent the root of -/// `10^(4 + 2 * places) * n * V / ((n - 1) * (sum X)^2)`, where `D` cancels. Nothing is rounded before the root. -/// @param moments The sample's moments, two or more elements. -/// @param relative Whether to compute the RSD. -/// @param places The places of the result. -/// @param mode The tie-breaking rule. -/// @return The result, or the reason it cannot be computed. -[[nodiscard]] inline std::expected spreadOf(Moments const& moments, bool relative, - std::uint32_t places, - math::RoundingMode mode) { - using math::detail::checkedMulU128; - using math::detail::U128; - std::string const overflow = "the statistics overflow"; - U128 const count{.hi = 0, .lo = moments.count}; - U128 const degrees{.hi = 0, .lo = moments.count - 1}; - auto const scaledSquares = checkedMulU128(count, moments.squares); - auto const squaredSum = checkedMulU128(moments.sumMagnitude, moments.sumMagnitude); - // n * sum X^2 >= (sum X)^2 by Cauchy-Schwarz, so the difference is never negative. - auto const spread = - scaledSquares && squaredSum ? math::detail::checkedSubU128(*scaledSquares, *squaredSum) : std::nullopt; - if (!spread) { - return std::unexpected(overflow); - } - std::optional numerator; - std::optional denominator; - if (relative) { - if (moments.sumMagnitude == U128{}) { - return std::unexpected(std::string{"the RSD of values whose mean is zero"}); - } - auto const power = math::detail::powerOfTenU128(4 + (2 * places)); - auto const scaled = power ? checkedMulU128(*power, count) : std::nullopt; - numerator = scaled ? checkedMulU128(*scaled, *spread) : std::nullopt; - denominator = checkedMulU128(degrees, *squaredSum); - } else { - auto const power = math::detail::powerOfTenU128(2 * places); - numerator = power ? checkedMulU128(*spread, *power) : std::nullopt; - auto const pairs = checkedMulU128(count, degrees); - denominator = - pairs ? checkedMulU128(*pairs, math::detail::mulU64(moments.scale, moments.scale)) : std::nullopt; - } - auto const root = numerator && denominator - ? math::detail::roundSqrtOfFraction(*numerator, *denominator, places, mode) - : std::nullopt; - if (!root) { - return std::unexpected(overflow); - } - return *root; -} +[[nodiscard]] MORPH_API std::string unitDisplay(std::string const& unit, UnitTable const& units); -/// @brief Evaluates expressions against an environment, with the comprehension variables in scope. -// NOLINTBEGIN(misc-no-recursion): an expression is a tree and evaluating it descends it; the node bound limits the depth. -class Evaluator { +/// @brief Evaluates expressions against an environment: the part of the evaluator that other code drives +/// directly, such as grouping and ordering a table's rows. `evaluate` is the entry point for one +/// expression. +class MORPH_API Evaluator { public: /// @brief Evaluates against @p env. - /// @param env What the expression reads. - explicit Evaluator(Environment const& env) : _env{&env} {} + /// @param env What the expression reads; it must outlive the evaluator. + explicit Evaluator(Environment const& env); + Evaluator(Evaluator const&) = delete; + Evaluator& operator=(Evaluator const&) = delete; + Evaluator(Evaluator&&) = delete; + Evaluator& operator=(Evaluator&&) = delete; + ~Evaluator(); /// @brief Evaluates one node. /// @param expr The node. /// @return Its value; `null` on a runtime error, which is reported. - [[nodiscard]] Value eval(Expr const& expr) { - switch (expr.kind) { - case ExprKind::Literal: - return expr.literal; - case ExprKind::Ref: - for (auto const& [name, value] : std::views::reverse(_locals)) { - if (name == expr.name) { - return walk(value, expr.fieldPath); - } - } - return _env->ref(expr.name, expr.fieldPath); - case ExprKind::Row: - return _env->row(expr.fieldPath); - case ExprKind::Query: - case ExprKind::Pending: - case ExprKind::Error: - case ExprKind::Result: - case ExprKind::ErrorKind: - case ExprKind::Refusal: - case ExprKind::Can: - return _env->control(expr.kind, expr.name); - case ExprKind::Pref: - return _env->pref(expr.name, expr.fieldPath); - case ExprKind::Env: - case ExprKind::Session: - case ExprKind::Host: - return _env->client(expr.kind, expr.name); - case ExprKind::If: - return choice(expr); - case ExprKind::Object: { - ValueRecord record; - for (auto const& [name, field] : expr.fields) { - record.insert_or_assign(name, eval(*field)); - } - return record; - } - case ExprKind::List: { - ValueList items; - items.reserve(expr.args.size()); - for (ExprPtr const& item : expr.args) { - items.push_back(eval(*item)); - } - return items; - } - case ExprKind::Map: - case ExprKind::Filter: - return comprehension(expr); - case ExprKind::Sort: - return sorted(expr); - case ExprKind::Runs: - return grouped(expr); - case ExprKind::Get: - return walk(eval(*expr.args.at(0)), expr.fieldPath); - case ExprKind::Call: - default: - return call(expr); - } - } + [[nodiscard]] Value eval(Expr const& expr); /// @brief Orders two values as sorting does: as `lt` orders them, except that strings compare case-folded as /// the table engine's default collator folds them, and by their own bytes when they fold the same, so @@ -1834,16 +493,7 @@ class Evaluator { /// @param lhs A value, not `null`. /// @param rhs A value, not `null`. /// @return The ordering; `nullopt` when the two are not of one comparable kind. - [[nodiscard]] std::optional sortOrder(Value const& lhs, Value const& rhs) { - std::string const* const lhsText = lhs.asString(); - std::string const* const rhsText = rhs.asString(); - if (lhsText != nullptr && rhsText != nullptr) { - table::CodePointCollator const collator; - std::strong_ordering const folded = collator.fold(*lhsText) <=> collator.fold(*rhsText); - return folded != std::strong_ordering::equal ? folded : *lhsText <=> *rhsText; - } - return order(lhs, rhs); - } + [[nodiscard]] std::optional sortOrder(Value const& lhs, Value const& rhs); /// @brief A stable order of rows by their sort keys: by each key in turn, `null` last in either direction, and /// a descending key reversing the comparison, not the rows, so rows with equal keys keep their order. @@ -1851,1205 +501,17 @@ class Evaluator { /// @param descending Whether each key sorts descending. /// @return The rows' indices in sorted order; `nullopt` when a key's values are not of one comparable kind. [[nodiscard]] std::optional> sortRows(std::vector> const& keys, - std::vector const& descending) { - // Every value of a key is checked against the key's first value, so the comparison below never meets a - // pair it cannot order and the sort's ordering is strict and weak. - for (std::size_t level = 0; level < descending.size(); ++level) { - if (!orderable(keys, level)) { - return std::nullopt; - } - } - std::vector indices(keys.size()); - // NOLINTNEXTLINE(modernize-use-ranges): std::ranges::iota is missing from Emscripten's libc++. - std::iota(indices.begin(), indices.end(), std::size_t{0}); - std::ranges::stable_sort(indices, [&](std::size_t left, std::size_t right) { - for (std::size_t level = 0; level < descending.size(); ++level) { - std::strong_ordering const ordering = - keyOrder(keys.at(left).at(level), keys.at(right).at(level), descending.at(level)); - if (ordering != std::strong_ordering::equal) { - return ordering == std::strong_ordering::less; - } - } - return false; - }); - return indices; - } + std::vector const& descending); - /// @brief Whether two `by` values put their elements in one run: `eq`'s comparison, except that `null` equals - /// `null`, so the elements without the value make one run. + /// @brief Whether two values belong to one run when adjacent rows are grouped. /// @param lhs A value. - /// @param rhs A value. - /// @return Whether they are the same run's. - [[nodiscard]] bool sameRun(Value const& lhs, Value const& rhs) { return sameElement(lhs, rhs); } + /// @param rhs The other. + /// @return Whether they are the same element. + [[nodiscard]] bool sameRun(Value const& lhs, Value const& rhs); private: - Value mismatch(Expr const& expr, std::string_view reason) { - ++_mismatches; - _env->report(expr.path, reason); - return Value{}; - } - - /// The calendar day of a reading in the display zone: a date as it is, an instant shifted by the display offset. - [[nodiscard]] std::chrono::year_month_day localDay(DateValue const& reading) { - if (reading.form == DateForm::Date) { - return reading.date; - } - auto const local = reading.instant + std::chrono::minutes{_env->formatting().utcOffsetMinutes}; - return std::chrono::year_month_day{std::chrono::floor(local.value)}; - } - - /// `dateRange(from, to)`: the span of two days in the shortest form that stays unambiguous, `20–24 Oct 2026` - /// within a month, `28 Oct – 3 Nov 2026` within a year, and both days in full across years. It is one fixed - /// English form, not the application's date pattern, because the pattern writes a single day. - Value dateRange(Expr const& expr, std::vector const& args) { - DateValue const from = readDateValue(args.at(0)); - DateValue const until = readDateValue(args.at(1)); - if (from.form == DateForm::Unreadable || until.form == DateForm::Unreadable) { - return mismatch(expr, "`dateRange` takes two dates, timestamps or ISO text"); - } - if (from.form == DateForm::Absent || until.form == DateForm::Absent) { - return Value{}; - } - auto const first = localDay(from); - auto const last = localDay(until); - auto const month = [](std::chrono::year_month_day day) { - return std::string{detail::dates::kMonths.at(static_cast(day.month()) - 1)}; - }; - auto const dayOf = [](std::chrono::year_month_day day) { - return std::to_string(static_cast(day.day())); - }; - auto const yearOf = [](std::chrono::year_month_day day) { - return std::to_string(static_cast(day.year())); - }; - // U+2013 EN DASH, written as bytes so the source's character set cannot change it. - std::string const dash = "\xE2\x80\x93"; - std::string const separator = " " + dash + " "; - if (first.year() != last.year()) { - return dayOf(first) + " " + month(first) + " " + yearOf(first) + separator + dayOf(last) + " " + - month(last) + " " + yearOf(last); - } - if (first.month() != last.month()) { - return dayOf(first) + " " + month(first) + separator + dayOf(last) + " " + month(last) + " " + - yearOf(last); - } - if (first.day() == last.day()) { - return dayOf(last) + " " + month(last) + " " + yearOf(last); - } - return dayOf(first) + dash + dayOf(last) + " " + month(last) + " " + yearOf(last); - } - - /// `dateAdd(value, amount, unit)`: a date or an instant moved by whole units, in the value's own form. - Value addToDate(Expr const& expr, std::vector const& args) { - DateValue const reading = readDateValue(args.at(0)); - if (reading.form == DateForm::Absent) { - return Value{}; - } - std::int64_t const* const amount = args.at(1).asInt(); - std::string const* const unit = args.at(2).asString(); - auto const unitIndex = unit == nullptr ? kDateUnits.size() - : static_cast(std::ranges::distance( - kDateUnits.begin(), std::ranges::find(kDateUnits, *unit))); - if (reading.form == DateForm::Unreadable || amount == nullptr || unitIndex == kDateUnits.size()) { - return mismatch(expr, "`dateAdd` takes a date, a timestamp or ISO text, an int and a unit"); - } - bool const clock = unitIndex >= 4; - if (reading.form == DateForm::Date && clock) { - return mismatch(expr, "a date has no time of day; add hours to a timestamp"); - } - std::string_view const outOfRange = "the date is out of range"; - if (*amount > kDateSpans.at(unitIndex) || *amount < -kDateSpans.at(unitIndex)) { - return mismatch(expr, outOfRange); - } - bool const calendar = unitIndex == 2 || unitIndex == 3; - std::int64_t const months = unitIndex == 3 ? *amount * 12 : *amount; - std::int64_t const days = unitIndex == 1 ? *amount * 7 : *amount; - if (reading.form == DateForm::Date) { - std::chrono::year_month_day const moved = - calendar ? addMonths(reading.date, months) - : std::chrono::year_month_day{std::chrono::sys_days{reading.date} + - std::chrono::days{static_cast(days)}}; - if (!inIsoRange(moved)) { - return mismatch(expr, outOfRange); - } - return isoDate(moved); - } - time::DateTime moved = reading.instant; - if (calendar) { - // The calendar is the one at the display offset: the wall-clock time there is kept. - std::chrono::minutes const offset{_env->formatting().utcOffsetMinutes}; - auto const local = reading.instant.value + offset; - auto const day = std::chrono::floor(local); - std::chrono::year_month_day const date = addMonths(std::chrono::year_month_day{day}, months); - moved = time::DateTime{std::chrono::sys_days{date} + (local - day) - offset}; - } else if (unitIndex == 4) { - moved = time::DateTime{reading.instant.value + std::chrono::hours{*amount}}; - } else if (unitIndex == 5) { - moved = time::DateTime{reading.instant.value + std::chrono::minutes{*amount}}; - } else { - moved = time::DateTime{reading.instant.value + std::chrono::days{static_cast(days)}}; - } - if (!inIsoRange(std::chrono::year_month_day{std::chrono::floor(moved.value)})) { - return mismatch(expr, outOfRange); - } - if (reading.form == DateForm::Timestamp) { - return moved; - } - return moved.toIso8601(); - } - - /// `sqrt(x, dp, mode?)`: the root of a plain number, correctly rounded at `dp` places. - Value squareRoot(Expr const& expr, std::vector const& args) { - auto const number = numeric(args.at(0)); - std::int64_t const* const places = args.at(1).asInt(); - auto const mode = modeOf(args); - if (!number || number->unit != nullptr || places == nullptr || *places < 0 || - std::cmp_greater(*places, math::kMaxDecimalPlaces) || !mode) { - return mismatch(expr, "`sqrt` takes a plain number, places from 0 to 18 and a rounding mode"); - } - if (number->value.isNegative()) { - return mismatch(expr, "the square root of a negative number"); - } - auto const digits = static_cast(*places); - auto const power = math::detail::powerOfTenU128(2 * digits); - auto const scaled = - power ? math::detail::checkedMulU128( - math::detail::U128{.hi = 0, .lo = static_cast(number->value.numerator)}, *power) - : std::nullopt; - auto const root = - scaled ? math::detail::roundSqrtOfFraction( - *scaled, - math::detail::U128{.hi = 0, .lo = static_cast(number->value.denominator)}, - digits, *mode) - : std::nullopt; - if (!root) { - return mismatch(expr, "the result overflows"); - } - return Decimal{*root}; - } - - /// `stdev(list, dp, mode?)` and `rsd(list, dp, mode?)`: exact, rounded once at `dp` places. - Value statistic(Expr const& expr, std::vector const& args) { - ValueList const* const items = args.at(0).asList(); - std::int64_t const* const places = args.at(1).asInt(); - auto const mode = modeOf(args); - if (items == nullptr || places == nullptr || *places < 0 || - std::cmp_greater(*places, math::kMaxDecimalPlaces) || !mode) { - return mismatch(expr, "the statistics take a list, places from 0 to 18 and a rounding mode"); - } - SampleReading const sample = momentsOf(*items, _env->formatting().units); - if (!sample) { - return mismatch(expr, sample.error()); - } - // Fewer than two values is a worksheet still being filled: no spread yet, and nothing to report. - if (!sample->has_value() || (*sample)->count < 2) { - return Value{}; - } - bool const relative = expr.function == FunctionId::Rsd; - auto const spread = spreadOf(**sample, relative, static_cast(*places), *mode); - if (!spread) { - return mismatch(expr, spread.error()); - } - if (!relative && (*sample)->unit != nullptr) { - return Quantity{.value = *spread, .unit = *(*sample)->unit}; - } - return Decimal{*spread}; - } - - /// The rounding mode of a call whose mode is its third argument: half to even when it is absent. - static std::optional modeOf(std::vector const& args) { - if (args.size() < 3) { - return math::RoundingMode::HalfEven; - } - return roundingMode(args.at(2)); - } - - Value choice(Expr const& expr) { - Value const cond = eval(*expr.args.at(0)); - if (cond.isNull()) { - return Value{}; - } - bool const* const flag = cond.asBool(); - if (flag == nullptr) { - return mismatch(expr, "the condition of `if` is not a bool"); - } - return eval(*expr.args.at(*flag ? 1 : 2)); - } - - Value comprehension(Expr const& expr) { - Value const source = eval(*expr.args.at(0)); - if (source.isNull()) { - return Value{}; - } - ValueList const* const items = source.asList(); - if (items == nullptr) { - return mismatch(expr, "a comprehension runs over a list"); - } - ValueList out; - for (Value const& item : *items) { - _locals.emplace_back(expr.name, item); - Value body = eval(*expr.args.at(1)); - _locals.pop_back(); - if (expr.kind == ExprKind::Map) { - out.push_back(std::move(body)); - continue; - } - bool const* const keep = body.asBool(); - if (keep == nullptr && !body.isNull()) { - return mismatch(expr, "the `where` of `filter` is not a bool"); - } - if (keep != nullptr && *keep) { - out.push_back(item); - } - } - return out; - } - - /// Whether every value of one sort key orders against the key's first value; `null`s aside. - bool orderable(std::vector> const& keys, std::size_t level) { - Value const* first = nullptr; - for (std::vector const& row : keys) { - Value const& value = row.at(level); - if (value.isNull()) { - continue; - } - if (first == nullptr) { - first = &value; - } else if (!sortOrder(*first, value)) { - return false; - } - } - return true; - } - - /// Where @p lhs sorts against @p rhs for one key: `null` last either way, and a descending key reverses the - /// comparison, so equal values compare equal and keep their order. - std::strong_ordering keyOrder(Value const& lhs, Value const& rhs, bool descending) { - if (lhs.isNull() || rhs.isNull()) { - if (lhs.isNull() == rhs.isNull()) { - return std::strong_ordering::equal; - } - return lhs.isNull() ? std::strong_ordering::greater : std::strong_ordering::less; - } - std::strong_ordering const ordering = sortOrder(lhs, rhs).value_or(std::strong_ordering::equal); - if (!descending || ordering == std::strong_ordering::equal) { - return ordering; - } - return ordering == std::strong_ordering::less ? std::strong_ordering::greater : std::strong_ordering::less; - } - - /// `runs`: the list split into runs of adjacent elements whose `by` values are equal. - Value grouped(Expr const& expr) { - Value const source = eval(*expr.args.at(0)); - if (source.isNull()) { - return Value{}; - } - ValueList const* const items = source.asList(); - if (items == nullptr) { - return mismatch(expr, "`runs` runs over a list"); - } - ValueList out; - Value key; - ValueList run; - for (Value const& item : *items) { - std::size_t const before = _mismatches; - _locals.emplace_back(expr.name, item); - Value value = eval(*expr.args.at(1)); - _locals.pop_back(); - // A `by` that fails for an element fails the whole form, as a mismatch inside any operand does. - if (_mismatches != before) { - return Value{}; - } - if (run.empty()) { - key = std::move(value); - } else if (!sameRun(key, value)) { - out.push_back(runRecord(std::exchange(key, std::move(value)), std::exchange(run, {}))); - } - run.push_back(item); - } - if (!run.empty()) { - out.push_back(runRecord(std::move(key), std::move(run))); - } - return out; - } - - /// `sort`: the list ordered by `by`, ascending unless `order` is `"desc"`. - Value sorted(Expr const& expr) { - Value const source = eval(*expr.args.at(0)); - if (source.isNull()) { - return Value{}; - } - ValueList const* const items = source.asList(); - if (items == nullptr) { - return mismatch(expr, "`sort` runs over a list"); - } - bool descending = false; - if (expr.args.size() > 2) { - Value const given = eval(*expr.args.at(2)); - std::string const* const direction = given.asString(); - if (!given.isNull() && (direction == nullptr || (*direction != "asc" && *direction != "desc"))) { - return mismatch(expr, R"(the `order` of `sort` is "asc" or "desc")"); - } - descending = direction != nullptr && *direction == "desc"; - } - std::vector> keys; - keys.reserve(items->size()); - for (Value const& item : *items) { - _locals.emplace_back(expr.name, item); - keys.emplace_back(1, eval(*expr.args.at(1))); - _locals.pop_back(); - } - auto const ranked = sortRows(keys, {descending}); - if (!ranked) { - return mismatch(expr, "the `by` values of `sort` are not of one comparable kind"); - } - ValueList out; - out.reserve(items->size()); - for (std::size_t const index : *ranked) { - out.push_back(items->at(index)); - } - return out; - } - - /// `slice`: `count` elements of the list from `start`, or every element from it. - Value sliced(Expr const& expr, std::vector const& args) { - ValueList const* const items = args.at(0).asList(); - std::int64_t const* const start = args.at(1).asInt(); - std::int64_t const* const count = args.size() > 2 ? args.at(2).asInt() : nullptr; - bool const badCount = args.size() > 2 && (count == nullptr || *count < 0); - if (items == nullptr || start == nullptr || *start < 0 || badCount) { - return mismatch(expr, "`slice` takes a list, a start and a count of 0 or more"); - } - auto const from = static_cast(std::min(*start, std::ssize(*items))); - std::size_t const left = items->size() - from; - std::size_t const taken = count == nullptr ? left : std::min(left, static_cast(*count)); - auto const first = items->begin() + static_cast(from); - return ValueList{first, first + static_cast(taken)}; - } - - /// Three-valued `and` / `or`: the dominant value wins over `null`. - Value kleene(Expr const& expr, bool dominant) { - bool sawNull = false; - for (ExprPtr const& arg : expr.args) { - Value const value = eval(*arg); - if (bool const* const flag = value.asBool()) { - if (*flag == dominant) { - return dominant; - } - continue; - } - if (!value.isNull()) { - _env->report(arg->path, "a logical operand is not a bool"); - } - sawNull = true; - } - if (sawNull) { - return Value{}; - } - return !dominant; - } - - // NOLINTNEXTLINE(readability-function-cognitive-complexity): the four operators over plain numbers and quantities, one rule each. - Value arithmetic(Expr const& expr, Value const& lhsValue, Value const& rhsValue) { - auto const lhs = numeric(lhsValue); - auto const rhs = numeric(rhsValue); - if (!lhs || !rhs) { - return mismatch(expr, "an arithmetic operand is not a number"); - } - UnitTable const& units = _env->formatting().units; - FunctionId const function = expr.function; - math::Rational right = rhs->value; - std::string const* unit = nullptr; - if (lhs->unit != nullptr && rhs->unit != nullptr) { - if (function == FunctionId::Mul) { - return mismatch(expr, "a product of two quantities has no declared unit"); - } - auto converted = convertUnit(rhs->value, *rhs->unit, *lhs->unit, units); - if (!converted) { - return mismatch(expr, "the units `" + *lhs->unit + "` and `" + *rhs->unit + "` do not convert"); - } - right = *converted; - unit = function == FunctionId::Div ? nullptr : lhs->unit; - } else if (lhs->unit != nullptr || rhs->unit != nullptr) { - bool const scales = function == FunctionId::Mul || (function == FunctionId::Div && lhs->unit != nullptr); - if (!scales) { - return mismatch(expr, "a quantity and a plain number do not combine this way"); - } - unit = lhs->unit != nullptr ? lhs->unit : rhs->unit; - } - if (function == FunctionId::Div && right.isZero()) { - return mismatch(expr, "division by zero"); - } - std::expected result = math::Rational{}; - if (function == FunctionId::Add) { - result = math::checkedAdd(lhs->value, right); - } else if (function == FunctionId::Sub) { - result = math::checkedSub(lhs->value, right); - } else if (function == FunctionId::Mul) { - result = math::checkedMul(lhs->value, right); - } else { - result = math::checkedDiv(lhs->value, right); - } - if (!result) { - return mismatch(expr, "the result overflows"); - } - // A quantity is never an `int`, so a ratio of two quantities comes back a decimal. - return makeNumber(*result, lhs->integer && rhs->integer, unit); - } - - /// Orders two values of one comparable kind: numbers exactly (quantities converted), timestamps, strings. - std::optional order(Value const& lhs, Value const& rhs) { - auto const lhsNumber = numeric(lhs); - auto const rhsNumber = numeric(rhs); - if (lhsNumber && rhsNumber) { - if ((lhsNumber->unit == nullptr) != (rhsNumber->unit == nullptr)) { - return std::nullopt; - } - math::Rational right = rhsNumber->value; - if (lhsNumber->unit != nullptr) { - auto converted = convertUnit(right, *rhsNumber->unit, *lhsNumber->unit, _env->formatting().units); - if (!converted) { - return std::nullopt; - } - right = *converted; - } - return lhsNumber->value <=> right; - } - if (time::DateTime const* const lhsTime = lhs.asTimestamp()) { - if (time::DateTime const* const rhsTime = rhs.asTimestamp()) { - return *lhsTime <=> *rhsTime; - } - return std::nullopt; - } - if (std::string const* const lhsText = lhs.asString()) { - if (std::string const* const rhsText = rhs.asString()) { - return *lhsText <=> *rhsText; - } - } - return std::nullopt; - } - - /// Equality over non-null values: numbers by value, lists and records element-wise, other kinds by identity. - bool equal(Value const& lhs, Value const& rhs) { - if (numeric(lhs) && numeric(rhs)) { - auto const ordering = order(lhs, rhs); - return ordering.has_value() && *ordering == std::strong_ordering::equal; - } - if (lhs.kind() != rhs.kind()) { - return false; - } - if (ValueList const* const lhsItems = lhs.asList()) { - return std::ranges::equal(*lhsItems, *rhs.asList(), [this](Value const& left, Value const& right) { - return sameElement(left, right); - }); - } - if (ValueRecord const* const lhsFields = lhs.asRecord()) { - // Records are ordered by field name, so equal records have equal sequences of fields. - return std::ranges::equal(*lhsFields, *rhs.asRecord(), [this](auto const& left, auto const& right) { - return left.first == right.first && sameElement(left.second, right.second); - }); - } - return lhs == rhs; - } - - /// Equality of two elements of a list or record, where `null` equals only `null`. - bool sameElement(Value const& left, Value const& right) { - if (left.isNull() || right.isNull()) { - return left.isNull() && right.isNull(); - } - return equal(left, right); - } - - /// The display text of a value, as `format` shows an argument. - std::optional display(Value const& value) { - FormatContext const& context = _env->formatting(); - if (std::string const* const text = value.asString()) { - return *text; - } - if (bool const* const flag = value.asBool()) { - return std::string{*flag ? "true" : "false"}; - } - if (Quantity const* const quantity = value.asQuantity()) { - auto number = formatNumber(value, withoutGrouping(context.numeric)); - if (!number) { - return std::nullopt; - } - return *number + " " + unitDisplay(quantity->unit, context.units); - } - if (auto number = formatNumber(value, withoutGrouping(context.numeric))) { - return number; - } - if (time::DateTime const* const instant = value.asTimestamp()) { - return dateText(*instant, "medium", true); - } - return std::nullopt; - } - - std::optional dateText(time::DateTime instant, std::string_view style, bool withTime) { - return localDateText(instant + std::chrono::minutes{_env->formatting().utcOffsetMinutes}, style, withTime); - } - - /// The text of a wall-clock time already in the display zone. - std::optional localDateText(time::DateTime local, std::string_view style, bool withTime) { - if (style != "short" && style != "medium" && style != "long") { - return std::nullopt; - } - FormatContext const& context = _env->formatting(); - if (context.dates) { - return context.dates(local, style, withTime); - } - // One pattern for every style, so a screen never mixes two forms of a date; the style chooses a form only - // while no pattern is set. - if (std::string const& pattern = withTime ? context.dateTimePattern : context.datePattern; !pattern.empty()) { - return formatDate(pattern, local, context.utcOffsetMinutes); - } - std::string const iso = local.toIso8601(); - if (!withTime) { - return iso.substr(0, 10); - } - return iso.substr(0, 10) + " " + iso.substr(11, style == "long" ? 8 : 5); - } - - /// Why `format` cannot show an argument: a number that overflows at its places, or a value it has no text for. - Value cannotShow(Expr const& expr, Value const& arg, std::size_t index) { - if (numeric(arg)) { - return mismatch(expr, "the result overflows"); - } - return mismatch(expr, "`format` cannot show argument " + std::to_string(index + 1)); - } - - Value formatTemplate(Expr const& expr, std::vector const& args) { - std::string const& pattern = *args.front().asString(); - std::vector shown; - for (std::size_t index = 1; index < args.size(); ++index) { - auto text = display(args.at(index)); - if (!text) { - return cannotShow(expr, args.at(index), index); - } - shown.push_back(std::move(*text)); - } - std::string out; - for (std::size_t pos = 0; pos < pattern.size(); ++pos) { - char const chr = pattern.at(pos); - if ((chr == '{' || chr == '}') && pos + 1 < pattern.size() && pattern.at(pos + 1) == chr) { - out += chr; - ++pos; - continue; - } - if (chr == '}') { - return mismatch(expr, "`format`'s template has an unmatched `}`"); - } - if (chr != '{') { - out += chr; - continue; - } - std::size_t const close = pattern.find('}', pos); - std::string_view const digits = close == std::string::npos - ? std::string_view{} - : std::string_view{pattern}.substr(pos + 1, close - pos - 1); - std::size_t index = 0; - bool valid = !digits.empty() && digits.size() < 4; - for (char const digit : digits) { - valid = valid && digit >= '0' && digit <= '9'; - index = valid ? (index * 10) + static_cast(digit - '0') : index; - } - if (!valid || index >= shown.size()) { - return mismatch(expr, "`format`'s template has a placeholder with no argument"); - } - out += shown.at(index); - pos = close; - } - return out; - } - - /// The named arguments a list of `{name, value}` records gives a message, each value as text. An element that is - /// not such a record is reported and left out. - ValueRecord namedArguments(Expr const& expr, ValueList const& list) { - ValueRecord named; - for (Value const& item : list) { - ValueRecord const* const entry = item.asRecord(); - auto const text = [entry](char const* field) -> std::string const* { - if (entry == nullptr) { - return nullptr; - } - auto const found = entry->find(field); - return found == entry->end() ? nullptr : found->second.asString(); - }; - std::string const* const argName = text("name"); - std::string const* const argValue = text("value"); - if (argName == nullptr || argValue == nullptr) { - _env->report(expr.path, "an argument of the message is a record of a string `name` and `value`"); - continue; - } - named.insert_or_assign(*argName, Value{*argValue}); - } - return named; - } - - /// Formats the catalogue's message for @p key in the active locale with @p named, else @p fallback. - /// @param reportMissing Whether a key the catalogue lacks is a problem (a key known only at run time). - std::string catalogued(Expr const& expr, std::string const& key, std::string const& fallback, - ValueRecord const& named, bool reportMissing) { - FormatContext const& context = _env->formatting(); - std::optional message; - if (context.translations) { - if (auto const pattern = context.translations(key, context.locale)) { - auto parsed = parseMessage(*pattern); - if (parsed) { - message = std::move(*parsed); - } else { - _env->report(expr.path, "the catalogue's message `" + key + - "` is outside the ui/1 subset: " + parsed.error()); - } - } - } - if (!message && reportMissing) { - _env->report(expr.path, "the catalogue has no message for the key `" + key + "`"); - } - if (!message) { - auto parsed = parseMessage(fallback); - if (!parsed) { - _env->report(expr.path, "the fallback is outside the ui/1 subset: " + parsed.error()); - return fallback; - } - message = std::move(*parsed); - } - FormattedMessage formatted = - formatMessage(*message, named, MessageLocale{.locale = context.locale, .numeric = context.numeric}); - for (std::string const& error : formatted.errors) { - _env->report(expr.path, error); - } - return std::move(formatted.text); - } - - Value translate(Expr const& expr, std::vector const& args) { - std::string const& key = *args.at(0).asString(); - std::string const& fallback = *args.at(1).asString(); - ValueRecord const empty; - ValueRecord listed; - ValueRecord const* named = ∅ - if (args.size() > 2) { - if (ValueList const* const list = args.at(2).asList()) { - listed = namedArguments(expr, *list); - named = &listed; - } else { - named = args.at(2).asRecord(); - } - if (named == nullptr) { - return mismatch(expr, "the arguments of `t` are a record, or a list of `{name, value}` records"); - } - } - bool const computedKey = expr.args.front()->kind != ExprKind::Literal; - return catalogued(expr, key, fallback, *named, computedKey); - } - - /// `refusalText`: the sentence for an action refusal `{code, args}`. - Value refusalText(Expr const& expr, Value const& refusal) { - ValueRecord const* const record = refusal.asRecord(); - auto const field = [record](char const* name) -> Value const* { - if (record == nullptr) { - return nullptr; - } - auto const found = record->find(name); - return found == record->end() ? nullptr : &found->second; - }; - Value const* const code = field("code"); - Value const* const list = field("args"); - if (code == nullptr || code->asString() == nullptr) { - return mismatch(expr, "`refusalText` takes a refusal, a record with a string `code`"); - } - ValueRecord named; - if (list != nullptr && list->asList() != nullptr) { - named = namedArguments(expr, *list->asList()); - } - FormatContext const& context = _env->formatting(); - std::string const& codeText = *code->asString(); - bool const hasCode = context.translations && context.translations(codeText, context.locale).has_value(); - if (hasCode) { - return catalogued(expr, codeText, std::string{kBuiltInRefusal}, named, false); - } - _env->report(expr.path, "the catalogue has no message for the refusal code `" + codeText + "`"); - // Each dotted prefix of the code, longest first, with `.generic` after it. - for (std::string prefix = codeText; prefix.rfind('.') != std::string::npos;) { - prefix.erase(prefix.rfind('.')); - std::string const classKey = prefix + ".generic"; - if (context.translations && context.translations(classKey, context.locale)) { - return catalogued(expr, classKey, std::string{kBuiltInRefusal}, named, false); - } - } - return std::string{kBuiltInRefusal}; - } - - Value listFunction(Expr const& expr, ValueList const& items) { - FunctionId const function = expr.function; - if (function == FunctionId::Count) { - return static_cast(items.size()); - } - if (function == FunctionId::First) { - if (items.empty()) { - return Value{}; - } - return items.front(); - } - if (function == FunctionId::Any || function == FunctionId::All) { - bool const dominant = function == FunctionId::Any; - bool sawNull = false; - for (Value const& item : items) { - bool const* const flag = item.asBool(); - if (flag != nullptr && *flag == dominant) { - return dominant; - } - if (flag == nullptr && !item.isNull()) { - return mismatch(expr, "an element is not a bool"); - } - sawNull = sawNull || item.isNull(); - } - if (sawNull) { - return Value{}; - } - return !dominant; - } - if (function == FunctionId::Min || function == FunctionId::Max) { - return extreme(expr, items); - } - return aggregate(expr, items); - } - - Value extreme(Expr const& expr, ValueList const& items) { - if (items.empty()) { - return Value{}; - } - Value const* best = &items.front(); - for (Value const& item : items) { - if (item.isNull()) { - return Value{}; - } - auto const ordering = order(item, *best); - if (!ordering) { - return mismatch(expr, "the elements are not of one comparable kind"); - } - bool const better = expr.function == FunctionId::Min ? std::is_lt(*ordering) : std::is_gt(*ordering); - if (better) { - best = &item; - } - } - return *best; - } - - Value aggregate(Expr const& expr, ValueList const& items) { - bool const mean = expr.function == FunctionId::Mean; - if (items.empty()) { - return mean ? Value{} : Value{std::int64_t{0}}; - } - math::Rational total{0, math::DecimalPlaces{0}}; - bool integer = true; - std::string const* unit = nullptr; - std::uint32_t places = 0; - for (std::size_t index = 0; index < items.size(); ++index) { - Value const& item = items.at(index); - if (item.isNull()) { - return Value{}; - } - auto const number = numeric(item); - if (!number) { - return mismatch(expr, "an element is not a number"); - } - if (index == 0) { - unit = number->unit; - } else if ((unit == nullptr) != (number->unit == nullptr)) { - return mismatch(expr, "quantities and plain numbers do not sum together"); - } - math::Rational value = number->value; - if (unit != nullptr) { - auto converted = convertUnit(value, *number->unit, *unit, _env->formatting().units); - if (!converted) { - return mismatch(expr, "the elements' units do not convert"); - } - value = *converted; - } - places = std::max(places, value.decimalPlaces.value); - integer = integer && number->integer; - auto next = math::checkedAdd(total, value); - if (!next) { - return mismatch(expr, "the sum overflows"); - } - total = *next; - } - if (!mean) { - return makeNumber(total, integer, unit); - } - auto const quotient = - math::checkedDiv(total, math::Rational{static_cast(items.size()), math::DecimalPlaces{0}}); - auto const rounded = quotient ? math::checkedRoundToDecimalPlaces(*quotient, math::DecimalPlaces{places}, - math::RoundingMode::HalfEven) - : std::nullopt; - if (!rounded) { - return mismatch(expr, "the result overflows"); - } - return makeNumber(*rounded, integer, unit); - } - - Value call(Expr const& expr) { - FunctionId const function = expr.function; - if (function == FunctionId::And || function == FunctionId::Or) { - return kleene(expr, function == FunctionId::Or); - } - if (function == FunctionId::Coalesce) { - for (ExprPtr const& arg : expr.args) { - Value value = eval(*arg); - if (!value.isNull()) { - return value; - } - } - return Value{}; - } - if (function == FunctionId::Engaged) { - return !eval(*expr.args.front()).isNull(); - } - std::vector args; - args.reserve(expr.args.size()); - for (ExprPtr const& arg : expr.args) { - args.push_back(eval(*arg)); - if (args.back().isNull()) { - return Value{}; - } - } - return strict(expr, args); - } - - /// The functions whose every argument is required: any `null` argument has already made the result `null`. - // GCC's -Wstrict-overflow fires on this whole function at -O3, attributing it to the function's opening line - // rather than a specific statement -- a known false positive from its range analysis across the switch's many - // checked-arithmetic calls (Rational's own checkedAdd/checkedSub/checkedMul are all free of signed-overflow UB). -#if defined(__GNUC__) && !defined(__clang__) -#pragma GCC diagnostic push -#pragma GCC diagnostic ignored "-Wstrict-overflow" -#endif - // NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per function of the library. - Value strict(Expr const& expr, std::vector const& args) { - FormatContext const& context = _env->formatting(); - switch (expr.function) { - case FunctionId::Not: { - bool const* const flag = args.front().asBool(); - if (flag == nullptr) { - return mismatch(expr, "`not` takes a bool"); - } - return !*flag; - } - case FunctionId::Eq: - return equal(args.at(0), args.at(1)); - case FunctionId::Ne: - return !equal(args.at(0), args.at(1)); - case FunctionId::Lt: - case FunctionId::Le: - case FunctionId::Gt: - case FunctionId::Ge: { - auto const ordering = order(args.at(0), args.at(1)); - if (!ordering) { - return mismatch(expr, "the operands are not of one comparable kind"); - } - if (expr.function == FunctionId::Lt) { - return std::is_lt(*ordering); - } - if (expr.function == FunctionId::Le) { - return std::is_lteq(*ordering); - } - if (expr.function == FunctionId::Gt) { - return std::is_gt(*ordering); - } - return std::is_gteq(*ordering); - } - case FunctionId::Add: - case FunctionId::Sub: - case FunctionId::Mul: - case FunctionId::Div: - return arithmetic(expr, args.at(0), args.at(1)); - case FunctionId::Neg: { - auto const number = numeric(args.front()); - if (!number) { - return mismatch(expr, "`neg` takes a number"); - } - auto negated = math::checkedSub(math::Rational{0, number->value.decimalPlaces}, number->value); - if (!negated) { - return mismatch(expr, "the result overflows"); - } - return makeNumber(*negated, number->integer, number->unit); - } - case FunctionId::Round: { - auto const number = numeric(args.at(0)); - std::int64_t const* const places = args.at(1).asInt(); - if (!number || places == nullptr || *places < 0 || - std::cmp_greater(*places, math::kMaxDecimalPlaces)) { - return mismatch(expr, "`round` takes a number and places from 0 to 18"); - } - auto const mode = modeOf(args); - if (!mode) { - return mismatch(expr, "the rounding mode is `halfEven` or `halfUp`"); - } - if (number->integer) { - return args.at(0); - } - auto const rounded = math::checkedRoundToDecimalPlaces( - number->value, math::DecimalPlaces{static_cast(*places)}, *mode); - if (!rounded) { - return mismatch(expr, "the result overflows"); - } - return makeNumber(*rounded, false, number->unit); - } - case FunctionId::Concat: { - std::string out; - for (Value const& arg : args) { - std::string const* const text = arg.asString(); - if (text == nullptr) { - return mismatch(expr, "`concat` takes strings"); - } - out += *text; - } - return out; - } - case FunctionId::Format: - if (args.front().asString() == nullptr) { - return mismatch(expr, "`format`'s template is a string"); - } - return formatTemplate(expr, args); - case FunctionId::Trim: { - std::string const* const text = args.front().asString(); - if (text == nullptr) { - return mismatch(expr, "`trim` takes a string"); - } - constexpr std::string_view kSpace = " \t\n\r\f\v"; - std::size_t const first = text->find_first_not_of(kSpace); - if (first == std::string::npos) { - return std::string{}; - } - return text->substr(first, text->find_last_not_of(kSpace) - first + 1); - } - case FunctionId::Length: { - std::string const* const text = args.front().asString(); - if (text == nullptr) { - return mismatch(expr, "`length` takes a string"); - } - std::int64_t points = 0; - for (char const chr : *text) { - points += (static_cast(chr) & 0xC0U) == 0x80U ? 0 : 1; - } - return points; - } - case FunctionId::IsEmpty: { - if (std::string const* const text = args.front().asString()) { - return text->empty(); - } - if (ValueList const* const items = args.front().asList()) { - return items->empty(); - } - return mismatch(expr, "`isEmpty` takes a string or a list"); - } - case FunctionId::Contains: { - std::string const* const text = args.at(0).asString(); - std::string const* const part = args.at(1).asString(); - if (text == nullptr || part == nullptr) { - return mismatch(expr, "`contains` takes two strings"); - } - return text->contains(*part); - } - case FunctionId::Count: - case FunctionId::Sum: - case FunctionId::Mean: - case FunctionId::Min: - case FunctionId::Max: - case FunctionId::Any: - case FunctionId::All: - case FunctionId::First: { - ValueList const* const items = args.front().asList(); - if (items == nullptr) { - return mismatch(expr, "the argument is not a list"); - } - return listFunction(expr, *items); - } - case FunctionId::Includes: - case FunctionId::IndexOf: { - ValueList const* const items = args.at(0).asList(); - if (items == nullptr) { - return mismatch(expr, "the first argument is not a list"); - } - for (std::size_t index = 0; index < items->size(); ++index) { - if (!items->at(index).isNull() && equal(items->at(index), args.at(1))) { - return expr.function == FunctionId::Includes ? Value{true} - : Value{static_cast(index)}; - } - } - return expr.function == FunctionId::Includes ? Value{false} : Value{}; - } - case FunctionId::Number: { - auto text = formatNumber(args.front(), context.numeric); - if (!text) { - return mismatch(expr, numeric(args.front()) ? "the result overflows" : "`number` takes a number"); - } - return std::move(*text); - } - case FunctionId::DecimalText: { - auto const number = numeric(args.at(0)); - std::int64_t const* const places = args.at(1).asInt(); - if (!number || places == nullptr || *places < 0 || - std::cmp_greater(*places, math::kMaxDecimalPlaces)) { - return mismatch(expr, "`decimal` takes a number and places from 0 to 18"); - } - auto const mode = modeOf(args); - if (!mode) { - return mismatch(expr, "the rounding mode is `halfEven` or `halfUp`"); - } - auto const text = decimalText(number->value, static_cast(*places), *mode); - if (!text) { - return mismatch(expr, "the result overflows"); - } - return render::formatCanonicalNumber(*text, context.numeric); - } - case FunctionId::QuantityText: { - Quantity const* const quantity = args.at(0).asQuantity(); - if (quantity == nullptr) { - return mismatch(expr, "`quantity` takes a quantity"); - } - Quantity shown = *quantity; - if (args.size() > 1) { - std::string const* const unit = args.at(1).asString(); - auto converted = unit == nullptr - ? std::nullopt - : convertUnit(quantity->value, quantity->unit, *unit, context.units); - if (!converted) { - return mismatch(expr, "the quantity does not convert to that unit"); - } - shown = Quantity{.value = *converted, .unit = *unit}; - } - auto const text = formatNumber(shown, context.numeric); - if (!text) { - return mismatch(expr, "the result overflows"); - } - return *text + " " + unitDisplay(shown.unit, context.units); - } - case FunctionId::Money: { - auto const number = numeric(args.at(0)); - std::string const* const currency = args.at(1).asString(); - if (!number || number->unit != nullptr || currency == nullptr) { - return mismatch(expr, "`money` takes an amount and a currency code"); - } - auto const text = decimalText(number->value, currencyDigits(*currency)); - if (!text) { - return mismatch(expr, "the result overflows"); - } - MoneyForm form = MoneyForm::Symbol; - if (args.size() > 2) { - std::string const* const named = args.at(2).asString(); - if (named == nullptr || (*named != "symbol" && *named != "code")) { - return mismatch(expr, "`money`'s form is \"symbol\" or \"code\""); - } - form = *named == "code" ? MoneyForm::Code : MoneyForm::Symbol; - } - return placeCurrency(render::formatCanonicalNumber(*text, context.numeric), *currency, - context.currency, context.numeric, form); - } - case FunctionId::Date: - case FunctionId::DateTime: { - DateValue const reading = readDateValue(args.at(0)); - // `""` is a date not given yet, as a cleared date input writes: nothing to show, nothing to report. - if (reading.form == DateForm::Absent) { - return Value{}; - } - std::string const* const style = args.size() > 1 ? args.at(1).asString() : nullptr; - std::string_view const shownStyle = style == nullptr ? std::string_view{"medium"} : *style; - bool const withTime = expr.function == FunctionId::DateTime; - std::optional text; - if (args.size() > 1 && style == nullptr) { - text = std::nullopt; - } else if (reading.form == DateForm::Date) { - // A date is that calendar day at any offset: its midnight is already local. - text = localDateText(time::DateTime{std::chrono::sys_days{reading.date}}, shownStyle, withTime); - } else if (reading.form != DateForm::Unreadable) { - text = dateText(reading.instant, shownStyle, withTime); - } - if (!text) { - return mismatch(expr, "the date functions take a date, a timestamp or ISO text, and a style"); - } - return std::move(*text); - } - case FunctionId::DateAdd: - return addToDate(expr, args); - case FunctionId::DateRange: - return dateRange(expr, args); - case FunctionId::ParseDecimal: { - std::string const* const text = args.at(0).asString(); - std::optional declared; - if (args.size() > 1) { - std::int64_t const* const places = args.at(1).asInt(); - if (places == nullptr || !std::in_range(*places) || - std::cmp_greater(*places, math::kMaxDecimalPlaces)) { - return mismatch(expr, "`parseDecimal` takes text and places from 0 to 18"); - } - declared = static_cast(*places); - } - if (text == nullptr) { - return mismatch(expr, "`parseDecimal` takes text and places from 0 to 18"); - } - // Text that does not spell a number is what an entry holds while it is typed: `null`, not an error. - if (auto parsed = render::parseDecimal(*text, _env->entryFormatting().numeric, declared)) { - return Decimal{*parsed}; - } - return Value{}; - } - case FunctionId::Abs: { - auto const number = numeric(args.front()); - if (!number) { - return mismatch(expr, "`abs` takes a number"); - } - if (!number->value.isNegative()) { - return args.front(); - } - auto magnitude = math::checkedSub(math::Rational{0, number->value.decimalPlaces}, number->value); - if (!magnitude) { - return mismatch(expr, "the result overflows"); - } - return makeNumber(*magnitude, number->integer, number->unit); - } - case FunctionId::Sqrt: - return squareRoot(expr, args); - case FunctionId::Stdev: - case FunctionId::Rsd: - return statistic(expr, args); - case FunctionId::ConcatLists: { - ValueList out; - for (Value const& arg : args) { - ValueList const* const items = arg.asList(); - if (items == nullptr) { - return mismatch(expr, "`concatLists` takes lists"); - } - out.insert(out.end(), items->begin(), items->end()); - } - return out; - } - case FunctionId::Slice: - return sliced(expr, args); - case FunctionId::RefusalText: - return refusalText(expr, args.front()); - case FunctionId::Translate: - if (args.at(0).asString() == nullptr || args.at(1).asString() == nullptr) { - return mismatch(expr, "`t` takes a key and a fallback string"); - } - return translate(expr, args); - case FunctionId::And: - case FunctionId::Or: - case FunctionId::Coalesce: - case FunctionId::Engaged: - default: - return Value{}; - } - } -#if defined(__GNUC__) && !defined(__clang__) -#pragma GCC diagnostic pop -#endif - - Environment const* _env; - std::vector> _locals; - // The mismatches reported so far, so a form can tell that an operand failed rather than gave `null`. - std::size_t _mismatches = 0; - // NOLINTEND(misc-no-recursion) + struct Impl; + std::unique_ptr _impl; }; } // namespace detail @@ -3062,14 +524,12 @@ class Evaluator { /// @param expr The expression. /// @param env What it reads. /// @return Its value. -[[nodiscard]] inline Value evaluate(Expr const& expr, Environment const& env) { - return detail::Evaluator{env}.eval(expr); -} +[[nodiscard]] MORPH_API Value evaluate(Expr const& expr, Environment const& env); /// @brief An environment that holds its values: for tests, and for evaluating outside a mounted screen. /// /// Each runtime error is recorded once per expression path in `diagnostics`. -class StaticEnvironment final : public Environment { +class MORPH_API StaticEnvironment final : public Environment { public: /// @brief The values `ref` reads, by head name. ValueRecord names; @@ -3119,24 +579,7 @@ class StaticEnvironment final : public Environment { /// @param form The form. /// @param name The query or mutation. /// @return The value. - [[nodiscard]] Value control(ExprKind form, std::string_view name) const override { - if (form == ExprKind::Pending) { - return pendingNames.contains(name); - } - if (form == ExprKind::Can) { - return permitted.contains(name); - } - if (form == ExprKind::Error) { - return lookup(errors, name, {}); - } - if (form == ExprKind::ErrorKind) { - return lookup(errorKinds, name, {}); - } - if (form == ExprKind::Refusal) { - return lookup(refusals, name, {}); - } - return lookup(form == ExprKind::Result ? results : queries, name, {}); - } + [[nodiscard]] Value control(ExprKind form, std::string_view name) const override; /// @brief Reads a customization choice. /// @param point The point. @@ -3164,14 +607,7 @@ class StaticEnvironment final : public Environment { /// @brief Records a runtime error, once per path. /// @param path The expression node's path. /// @param reason What went wrong. - void report(std::string_view path, std::string_view reason) const override { - for (Refusal const& seen : diagnostics) { - if (seen.path == path) { - return; - } - } - diagnostics.push_back(Refusal{.document = {}, .path = std::string{path}, .reason = std::string{reason}}); - } + void report(std::string_view path, std::string_view reason) const override; private: [[nodiscard]] static Value lookup(ValueRecord const& values, std::string_view name, diff --git a/scripts/branch_partial_allowlist.json b/scripts/branch_partial_allowlist.json index 39a1dc737..bd04c686c 100644 --- a/scripts/branch_partial_allowlist.json +++ b/scripts/branch_partial_allowlist.json @@ -147,22 +147,22 @@ "reason": "The default arm is unreachable: the switch names every enumerator of NameCategory, so no value reaches `default`. The project's strict warnings require both at once -- -Wswitch-enum wants every enumerator listed and -Wswitch-default wants a default label -- so the default shares the last enumerator's body and is never the label taken. It is ScopeResolver::ref's switch over what a name declares." }, { - "file": "include/morph/ui/expression.hpp", - "line": 573, + "file": "src/ui/expression.cpp", + "line": 399, "source": "default:", "context": "return comprehension(made, object, path);", "reason": "The default arm is unreachable: the switch names every enumerator of ExprKind, so no value reaches `default`. The project's strict warnings require both at once -- -Wswitch-enum wants every enumerator listed and -Wswitch-default wants a default label -- so the default shares the last enumerator's body and is never the label taken. It is ExprParser::form's switch over the expression forms." }, { - "file": "include/morph/ui/expression.hpp", - "line": 1039, + "file": "src/ui/expression.cpp", + "line": 743, "source": "default:", "context": "return Type::of(TypeKind::List);", "reason": "The default arm is unreachable: the switch names every enumerator of ExprKind, so no value reaches `default`. The project's strict warnings require both at once -- -Wswitch-enum wants every enumerator listed and -Wswitch-default wants a default label -- so the default shares the last enumerator's body and is never the label taken. It is ExprChecker::check's switch." }, { - "file": "include/morph/ui/expression.hpp", - "line": 1826, + "file": "src/ui/expression.cpp", + "line": 1231, "source": "default:", "context": "return items;", "reason": "The default arm is unreachable: the switch names every enumerator of ExprKind, so no value reaches `default`. The project's strict warnings require both at once -- -Wswitch-enum wants every enumerator listed and -Wswitch-default wants a default label -- so the default shares the last enumerator's body and is never the label taken. It is Evaluator::eval's switch." diff --git a/scripts/check_install_export.sh b/scripts/check_install_export.sh index 31fcb59a5..8394fa664 100755 --- a/scripts/check_install_export.sh +++ b/scripts/check_install_export.sh @@ -278,6 +278,22 @@ int main() { if (morph::ui::detail::base64Size("AQID") != 3) { return 1; } + // Calls into the document loader's and the expression language's compiled halves. + auto const loaded = + morph::ui::loadDocumentText(R"({"vocab": "ui/1", "id": "t", "view": {"kind": "text", "text": "x"}})"); + if (!loaded.has_value() || loaded->view->kind != "text") { + return 1; + } + auto const json = morph::ui::parseJson(R"({"fn": "add", "args": [1, 2]})"); + auto const expr = json ? morph::ui::parseExpression(*json) : std::unexpected(morph::ui::Refusal{}); + morph::ui::StaticEnvironment const env; + if (!expr.has_value()) { + return 1; + } + auto const sum = morph::ui::evaluate(**expr, env); + if (sum.asInt() == nullptr || *sum.asInt() != 3) { + return 1; + } std::printf("morph %d.%d.%d consumed from the install prefix\n", MORPH_VERSION_MAJOR, MORPH_VERSION_MINOR, MORPH_VERSION_PATCH); return 0; diff --git a/src/ui/expression.cpp b/src/ui/expression.cpp new file mode 100644 index 000000000..1b2901a5e --- /dev/null +++ b/src/ui/expression.cpp @@ -0,0 +1,2702 @@ +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace morph::ui { + +namespace detail { + +namespace { + +/// @brief A set of type kinds, as bits. +using KindSet = std::uint16_t; + +/// @brief The bit of one kind. +/// @param kind The kind. +/// @return Its bit. +[[nodiscard]] constexpr KindSet kindBit(TypeKind kind) noexcept { + return static_cast(1U << static_cast(kind)); +} + +/// @brief Every kind. +constexpr KindSet kAllKinds = 0xFFFF; +/// @brief The numbers. +// NOLINTNEXTLINE(bugprone-signed-bitwise): the operands are `uint16_t` values promoted to `int`, never negative. +constexpr KindSet kNumeric = kindBit(TypeKind::Int) | kindBit(TypeKind::Decimal) | kindBit(TypeKind::Quantity); +/// @brief The ordered kinds. +// NOLINTNEXTLINE(bugprone-signed-bitwise): the operands are `uint16_t` values promoted to `int`, never negative. +constexpr KindSet kOrdered = kNumeric | kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String); + +/// @brief The sentence `refusalText` shows when the catalogue has neither a refusal's code nor a class of it. +constexpr std::string_view kBuiltInRefusal = "This was refused."; + +/// @brief The signature of a library function. +struct FunctionSpec { + /// @brief The name a document calls it by. + std::string_view name; + /// @brief The fewest arguments. + std::uint8_t minArgs; + /// @brief The most arguments; 255 for any number. + std::uint8_t maxArgs; + /// @brief The kinds the first, second and every further argument accept. + std::array accepts; + /// @brief The result's kind; `Any` when it depends on the arguments. + TypeKind result; +}; + +/// @brief The library, indexed by `FunctionId`. +// NOLINTBEGIN(modernize-use-designated-initializers,readability-trailing-comma): one row per function reads as a table; names on every field would not. A trailing comma would put every row member on a line of its own. +constexpr std::array kFunctions = {{ + {"and", 1, 255, {kindBit(TypeKind::Bool), kindBit(TypeKind::Bool), kindBit(TypeKind::Bool)}, TypeKind::Bool}, + {"or", 1, 255, {kindBit(TypeKind::Bool), kindBit(TypeKind::Bool), kindBit(TypeKind::Bool)}, TypeKind::Bool}, + {"not", 1, 1, {kindBit(TypeKind::Bool), 0, 0}, TypeKind::Bool}, + {"eq", 2, 2, {kAllKinds, kAllKinds, 0}, TypeKind::Bool}, + {"ne", 2, 2, {kAllKinds, kAllKinds, 0}, TypeKind::Bool}, + {"lt", 2, 2, {kOrdered, kOrdered, 0}, TypeKind::Bool}, + {"le", 2, 2, {kOrdered, kOrdered, 0}, TypeKind::Bool}, + {"gt", 2, 2, {kOrdered, kOrdered, 0}, TypeKind::Bool}, + {"ge", 2, 2, {kOrdered, kOrdered, 0}, TypeKind::Bool}, + {"add", 2, 2, {kNumeric, kNumeric, 0}, TypeKind::Any}, + {"sub", 2, 2, {kNumeric, kNumeric, 0}, TypeKind::Any}, + {"mul", 2, 2, {kNumeric, kNumeric, 0}, TypeKind::Any}, + {"div", 2, 2, {kNumeric, kNumeric, 0}, TypeKind::Any}, + {"neg", 1, 1, {kNumeric, 0, 0}, TypeKind::Any}, + {"round", 2, 3, {kNumeric, kindBit(TypeKind::Int), kindBit(TypeKind::String)}, TypeKind::Any}, + {"engaged", 1, 1, {kAllKinds, 0, 0}, TypeKind::Bool}, + {"coalesce", 1, 255, {kAllKinds, kAllKinds, kAllKinds}, TypeKind::Any}, + {"concat", + 1, + 255, + {kindBit(TypeKind::String), kindBit(TypeKind::String), kindBit(TypeKind::String)}, + TypeKind::String}, + {"format", 1, 255, {kindBit(TypeKind::String), kAllKinds, kAllKinds}, TypeKind::String}, + {"trim", 1, 1, {kindBit(TypeKind::String), 0, 0}, TypeKind::String}, + {"length", 1, 1, {kindBit(TypeKind::String), 0, 0}, TypeKind::Int}, + {"isEmpty", 1, 1, {kindBit(TypeKind::String) | kindBit(TypeKind::List), 0, 0}, TypeKind::Bool}, + {"contains", 2, 2, {kindBit(TypeKind::String), kindBit(TypeKind::String), 0}, TypeKind::Bool}, + {"count", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Int}, + {"sum", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Any}, + {"mean", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Any}, + {"min", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Any}, + {"max", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Any}, + {"any", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Bool}, + {"all", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Bool}, + {"first", 1, 1, {kindBit(TypeKind::List), 0, 0}, TypeKind::Any}, + {"includes", 2, 2, {kindBit(TypeKind::List), kAllKinds, 0}, TypeKind::Bool}, + {"indexOf", 2, 2, {kindBit(TypeKind::List), kAllKinds, 0}, TypeKind::Int}, + {"number", 1, 1, {kNumeric, 0, 0}, TypeKind::String}, + {"decimal", 2, 3, {kNumeric, kindBit(TypeKind::Int), kindBit(TypeKind::String)}, TypeKind::String}, + {"quantity", 1, 2, {kindBit(TypeKind::Quantity), kindBit(TypeKind::String), 0}, TypeKind::String}, + {"money", + 2, + 3, + {kindBit(TypeKind::Int) | kindBit(TypeKind::Decimal), kindBit(TypeKind::String), kindBit(TypeKind::String)}, + TypeKind::String}, + {"date", + 1, + 2, + {kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String), kindBit(TypeKind::String), 0}, + TypeKind::String}, + {"dateTime", + 1, + 2, + {kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String), kindBit(TypeKind::String), 0}, + TypeKind::String}, + {"t", + 2, + 3, + {kindBit(TypeKind::String), kindBit(TypeKind::String), kindBit(TypeKind::Record) | kindBit(TypeKind::List)}, + TypeKind::String}, + {"parseDecimal", 1, 2, {kindBit(TypeKind::String), kindBit(TypeKind::Int), 0}, TypeKind::Decimal}, + {"concatLists", + 1, + 255, + {kindBit(TypeKind::List), kindBit(TypeKind::List), kindBit(TypeKind::List)}, + TypeKind::Any}, + {"slice", 2, 3, {kindBit(TypeKind::List), kindBit(TypeKind::Int), kindBit(TypeKind::Int)}, TypeKind::Any}, + {"abs", 1, 1, {kNumeric, 0, 0}, TypeKind::Any}, + {"sqrt", + 2, + 3, + {kindBit(TypeKind::Int) | kindBit(TypeKind::Decimal), kindBit(TypeKind::Int), kindBit(TypeKind::String)}, + TypeKind::Decimal}, + {"stdev", 2, 3, {kindBit(TypeKind::List), kindBit(TypeKind::Int), kindBit(TypeKind::String)}, TypeKind::Any}, + {"rsd", 2, 3, {kindBit(TypeKind::List), kindBit(TypeKind::Int), kindBit(TypeKind::String)}, TypeKind::Decimal}, + {"dateAdd", + 3, + 3, + {kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String), kindBit(TypeKind::Int), kindBit(TypeKind::String)}, + TypeKind::Any}, + {"dateRange", + 2, + 2, + {kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String), + kindBit(TypeKind::Timestamp) | kindBit(TypeKind::String), 0}, + TypeKind::String}, + {"refusalText", 1, 1, {kindBit(TypeKind::Record), 0, 0}, TypeKind::String}, +}}; +// NOLINTEND(modernize-use-designated-initializers,readability-trailing-comma) + +/// @brief The signature of a function. +/// @param function The function. +/// @return Its entry in `kFunctions`. +[[nodiscard]] constexpr FunctionSpec const& functionSpec(FunctionId function) { + return kFunctions.at(static_cast(function)); +} + +/// @brief The position of a function's optional rounding mode, `"halfEven"` or `"halfUp"`. +/// @param function The function. +/// @return The argument index of its mode, or empty for a function that does not round. +[[nodiscard]] constexpr std::optional modeArgument(FunctionId function) noexcept { + if (function == FunctionId::Round || function == FunctionId::DecimalText || function == FunctionId::Sqrt || + function == FunctionId::Stdev || function == FunctionId::Rsd) { + return 2; + } + return std::nullopt; +} + +/// @brief Reads a rounding mode: `"halfEven"`, ties to the even neighbour, or `"halfUp"`, ties away from zero. +/// @param mode The mode's value. +/// @return The mode, or empty for any other value. +[[nodiscard]] std::optional roundingMode(Value const& mode) { + std::string const* const name = mode.asString(); + if (name != nullptr && *name == "halfEven") { + return math::RoundingMode::HalfEven; + } + if (name != nullptr && *name == "halfUp") { + return math::RoundingMode::HalfAwayFromZero; + } + return std::nullopt; +} + +/// @brief The units `dateAdd` adds. +constexpr std::array kDateUnits = {"days", "weeks", "months", "years", "hours", "minutes"}; + +/// @brief The names `{"env": ...}` reads. +constexpr std::array kEnvNames = { + "widthClass", "locale", "platform", "online", "backend", "context", +}; + +/// @brief The names `{"session": ...}` reads. +constexpr std::array kSessionNames = { + "principal", "userName", "displayName", "userKey", "tenant", "authenticated", +}; + +/// @brief Whether a name is one of a closed set. +/// @param names The set. +/// @param name The candidate. +/// @return Whether @p name is in @p names. +template +[[nodiscard]] constexpr bool oneOf(std::array const& names, std::string_view name) noexcept { + return std::ranges::find(names, name) != names.end(); +} + +/// @brief Reads one JSON expression tree into `Expr` nodes, counting them against the size bound. +// NOLINTBEGIN(misc-no-recursion): an expression is a tree and parsing descends it; the node bound limits the depth. +class ExprParser { +public: + /// @brief The keys a form may carry beside its own. + struct FormKeys { + /// @brief The form's own key. + std::string_view key; + /// @brief The form. + ExprKind kind; + /// @brief The keys allowed beside it. + std::array companions; + }; + + /// @brief Parses @p json, whose JSON Pointer is @p path. + /// @param json The expression. + /// @param path Its JSON Pointer. + /// @return The expression, or the refusal. + [[nodiscard]] std::expected parse(Json const& json, std::string const& path) { + return node(json, path); + } + +private: + // NOLINTBEGIN(modernize-use-designated-initializers,readability-trailing-comma): one row per form reads as a table. A trailing comma would put every row member on a line of its own. + static constexpr std::array kForms = {{ + {"lit", ExprKind::Literal, {}}, + {"ref", ExprKind::Ref, {}}, + {"row", ExprKind::Row, {}}, + {"query", ExprKind::Query, {}}, + {"pending", ExprKind::Pending, {}}, + {"error", ExprKind::Error, {}}, + {"result", ExprKind::Result, {}}, + {"errorKind", ExprKind::ErrorKind, {}}, + {"refusal", ExprKind::Refusal, {}}, + {"can", ExprKind::Can, {}}, + {"pref", ExprKind::Pref, {}}, + {"fn", ExprKind::Call, {"args", ""}}, + {"t", ExprKind::Call, {"fallback", "args"}}, + {"if", ExprKind::If, {}}, + {"obj", ExprKind::Object, {}}, + {"list", ExprKind::List, {}}, + {"map", ExprKind::Map, {"as", "to"}}, + {"filter", ExprKind::Filter, {"as", "where"}}, + {"sort", ExprKind::Sort, {"as", "by", "order"}}, + {"runs", ExprKind::Runs, {"as", "by"}}, + {"env", ExprKind::Env, {}}, + {"session", ExprKind::Session, {}}, + {"host", ExprKind::Host, {}}, + {"get", ExprKind::Get, {"path", ""}}, + }}; + // NOLINTEND(modernize-use-designated-initializers,readability-trailing-comma) + + [[nodiscard]] static std::unexpected refuse(std::string const& path, std::string reason) { + return std::unexpected(Refusal{.document = {}, .path = path, .reason = std::move(reason)}); + } + + [[nodiscard]] static std::string const* text(Json const& json) { return std::get_if(&json.data); } + + [[nodiscard]] static Json const* member(Json::object_t const& object, std::string_view key) { + auto const* const found = object.find(key); + return found == object.end() ? nullptr : &found->second; + } + + [[nodiscard]] static ExprPtr literal(Value value, std::string path) { + auto made = std::make_shared(); + made->kind = ExprKind::Literal; + made->literal = std::move(value); + made->path = std::move(path); + return made; + } + + [[nodiscard]] std::expected node(Json const& json, std::string const& path) { + if (++_count > kMaxExpressionNodes) { + return refuse(path, "the expression has more than " + std::to_string(kMaxExpressionNodes) + + " nodes, the bound of expr/1"); + } + if (std::holds_alternative(json.data)) { + return refuse(path, R"(a list is written {"list": [...]}, a constant list {"lit": [...]})"); + } + auto const* const object = std::get_if(&json.data); + if (object == nullptr) { + auto value = valueFromJson(json); + if (!value) { + return refuse(path, value.error()); + } + return literal(std::move(*value), path); + } + auto made = std::make_shared(); + made->path = path; + if (auto refused = form(*made, *object, path)) { + return std::unexpected(std::move(*refused)); + } + return made; + } + + [[nodiscard]] std::optional form(Expr& made, Json::object_t const& object, std::string const& path) { + FormKeys const* chosen = nullptr; + for (auto const& [key, value] : object) { + static_cast(value); + for (FormKeys const& candidate : kForms) { + if (candidate.key != key) { + continue; + } + if (chosen != nullptr) { + return refuse(path, "an expression has one form; found `" + std::string{chosen->key} + "` and `" + + key + "`") + .error(); + } + chosen = &candidate; + } + } + if (chosen == nullptr) { + if (object.empty()) { + return refuse(path, "an empty object is not an expression; a constant record is {\"lit\": {}}") + .error(); + } + return refuse(path, "`" + object.begin()->first + "` is not an expression form of expr/1").error(); + } + for (auto const& [key, value] : object) { + static_cast(value); + if (key != chosen->key && !std::ranges::contains(chosen->companions, key)) { + return refuse(pointerAppend(path, key), + "`" + key + "` does not belong to the `" + std::string{chosen->key} + "` form") + .error(); + } + } + Json const& primary = *member(object, chosen->key); + std::string const primaryPath = pointerAppend(path, chosen->key); + made.kind = chosen->kind; + switch (chosen->kind) { + case ExprKind::Literal: { + auto value = valueFromJson(primary); + if (!value) { + return refuse(primaryPath, value.error()).error(); + } + made.literal = std::move(*value); + return std::nullopt; + } + case ExprKind::Ref: + case ExprKind::Pref: + return dotted(made, primary, primaryPath); + case ExprKind::Row: + return rowPath(made, primary, primaryPath); + case ExprKind::Query: + case ExprKind::Pending: + case ExprKind::Error: + case ExprKind::Result: + case ExprKind::ErrorKind: + case ExprKind::Refusal: + case ExprKind::Can: + return controlName(made, primary, primaryPath, chosen->key); + case ExprKind::Env: + case ExprKind::Session: + case ExprKind::Host: + return clientName(made, primary, primaryPath, chosen->key); + case ExprKind::Call: + if (chosen->key == "t") { + return translate(made, object, path); + } + return call(made, object, path); + case ExprKind::If: + return operands(made.args, primary, primaryPath, 3, "`if` takes [condition, then, else]"); + case ExprKind::List: + return operands(made.args, primary, primaryPath, 0, "`list` takes an array of expressions"); + case ExprKind::Object: + return fields(made.fields, primary, primaryPath); + case ExprKind::Get: + return get(made, object, path); + case ExprKind::Map: + case ExprKind::Filter: + case ExprKind::Sort: + case ExprKind::Runs: + default: + return comprehension(made, object, path); + } + } + + [[nodiscard]] static std::optional dotted(Expr& made, Json const& primary, std::string const& path) { + std::string const* const dottedPath = text(primary); + if (dottedPath == nullptr) { + return refuse(path, "a name and path is written as a string `name.path`").error(); + } + auto segments = splitPath(*dottedPath); + if (!segments) { + return refuse(path, segments.error()).error(); + } + if (!isName(segments->front())) { + return refuse(path, "`" + segments->front() + "` is not a name").error(); + } + made.name = std::move(segments->front()); + made.fieldPath.assign(std::make_move_iterator(segments->begin() + 1), + std::make_move_iterator(segments->end())); + return std::nullopt; + } + + [[nodiscard]] static std::optional rowPath(Expr& made, Json const& primary, std::string const& path) { + std::string const* const dottedPath = text(primary); + if (dottedPath == nullptr) { + return refuse(path, "`row` names a field path as a string, \"\" for the whole row").error(); + } + if (dottedPath->empty()) { + return std::nullopt; + } + auto segments = splitPath(*dottedPath); + if (!segments) { + return refuse(path, segments.error()).error(); + } + made.fieldPath = std::move(*segments); + return std::nullopt; + } + + [[nodiscard]] static std::optional controlName(Expr& made, Json const& primary, std::string const& path, + std::string_view key) { + std::string const* const name = text(primary); + bool const can = made.kind == ExprKind::Can; + bool const hostCommand = can && name != nullptr && name->starts_with("host:") && name->size() > 5; + if (name == nullptr || (!isName(*name) && !hostCommand)) { + return refuse(path, "`" + std::string{key} + "` takes the name of a " + + (can ? "mutation, query or `host:` command" : "query or mutation")) + .error(); + } + made.name = *name; + return std::nullopt; + } + + [[nodiscard]] static std::optional clientName(Expr& made, Json const& primary, std::string const& path, + std::string_view key) { + std::string const* const name = text(primary); + bool known = name != nullptr && !name->empty(); + if (known && made.kind == ExprKind::Env) { + known = oneOf(kEnvNames, *name); + } else if (known && made.kind == ExprKind::Session) { + known = oneOf(kSessionNames, *name); + } + if (!known) { + return refuse(path, "`" + std::string{key} + "` does not read this name").error(); + } + made.name = *name; + return std::nullopt; + } + + [[nodiscard]] std::optional operands(std::vector& out, Json const& primary, + std::string const& path, std::size_t exactly, char const* shape) { + auto const* const array = std::get_if(&primary.data); + if (array == nullptr || (exactly != 0 && array->size() != exactly)) { + return refuse(path, shape).error(); + } + for (std::size_t index = 0; index < array->size(); ++index) { + auto operand = node(array->at(index), pointerAppend(path, index)); + if (!operand) { + return std::move(operand.error()); + } + out.push_back(std::move(*operand)); + } + return std::nullopt; + } + + [[nodiscard]] std::optional fields(std::vector>& out, Json const& primary, + std::string const& path) { + auto const* const object = std::get_if(&primary.data); + if (object == nullptr) { + return refuse(path, "`obj` takes an object of expressions").error(); + } + for (auto const& [key, value] : *object) { + auto field = node(value, pointerAppend(path, key)); + if (!field) { + return std::move(field.error()); + } + out.emplace_back(key, std::move(*field)); + } + return std::nullopt; + } + + [[nodiscard]] std::optional call(Expr& made, Json::object_t const& object, std::string const& path) { + std::string const* const name = text(*member(object, "fn")); + std::string const namePath = pointerAppend(path, "fn"); + if (name == nullptr) { + return refuse(namePath, "`fn` names a function as a string").error(); + } + auto const index = + std::ranges::distance(kFunctions.begin(), std::ranges::find(kFunctions, *name, &FunctionSpec::name)); + if (std::cmp_equal(index, kFunctions.size())) { + return refuse(namePath, "the function `" + *name + "` is not in expr/1").error(); + } + FunctionSpec const& spec = *std::next(kFunctions.begin(), index); + made.function = static_cast(index); + if (Json const* const args = member(object, "args")) { + if (auto refused = operands(made.args, *args, pointerAppend(path, "args"), 0, + "`args` takes an array of expressions")) { + return refused; + } + } + if (made.args.size() < spec.minArgs || made.args.size() > spec.maxArgs) { + std::string arity = std::to_string(static_cast(spec.minArgs)); + if (spec.maxArgs == 255) { + arity += " or more"; + } else if (spec.maxArgs != spec.minArgs) { + arity += " to " + std::to_string(static_cast(spec.maxArgs)); + } + return refuse(path, + "`" + *name + "` takes " + arity + " arguments, not " + std::to_string(made.args.size())) + .error(); + } + return std::nullopt; + } + + [[nodiscard]] std::optional translate(Expr& made, Json::object_t const& object, std::string const& path) { + made.function = FunctionId::Translate; + Json const& keyJson = *member(object, "t"); + std::string const* const key = text(keyJson); + Json const* const fallback = member(object, "fallback"); + std::string const* const fallbackText = fallback == nullptr ? nullptr : text(*fallback); + std::string const keyPath = pointerAppend(path, "t"); + Json const* const keyExpression = wrapped(keyJson); + if (keyExpression == nullptr && (key == nullptr || key->empty())) { + return refuse(keyPath, R"(`t` names a message key as a string, or as {"expr": e} for an expression)") + .error(); + } + if (fallbackText == nullptr) { + return refuse(pointerAppend(path, "fallback"), "`t` needs its `fallback` text as a string").error(); + } + if (keyExpression != nullptr) { + auto computed = node(*keyExpression, pointerAppend(keyPath, "expr")); + if (!computed) { + return std::move(computed.error()); + } + made.args.push_back(std::move(*computed)); + } else { + made.args.push_back(literal(*key, keyPath)); + } + made.args.push_back(literal(*fallbackText, pointerAppend(path, "fallback"))); + if (Json const* const args = member(object, "args"); args != nullptr && wrapped(*args) != nullptr) { + auto list = node(*wrapped(*args), pointerAppend(pointerAppend(path, "args"), "expr")); + if (!list) { + return std::move(list.error()); + } + made.args.push_back(std::move(*list)); + } else if (args != nullptr) { + auto record = std::make_shared(); + record->kind = ExprKind::Object; + record->path = pointerAppend(path, "args"); + if (auto refused = fields(record->fields, *args, record->path)) { + return refused; + } + made.args.push_back(std::move(record)); + } + return std::nullopt; + } + + /// The expression in `{"expr": e}`, the wrapper `t` takes a computed key or argument list in; null when @p json + /// is anything else. + [[nodiscard]] static Json const* wrapped(Json const& json) { + auto const* const object = std::get_if(&json.data); + if (object == nullptr || object->size() != 1) { + return nullptr; + } + return member(*object, "expr"); + } + + [[nodiscard]] std::optional get(Expr& made, Json::object_t const& object, std::string const& path) { + Json const* const fieldPath = member(object, "path"); + if (fieldPath == nullptr) { + return refuse(path, "`get` needs `path`").error(); + } + std::string const* const dottedPath = text(*fieldPath); + std::string const pathPointer = pointerAppend(path, "path"); + if (dottedPath == nullptr || dottedPath->empty()) { + return refuse(pathPointer, "`get` reads a `path` written as a string `a.b.0`").error(); + } + auto segments = splitPath(*dottedPath); + if (!segments) { + return refuse(pathPointer, segments.error()).error(); + } + auto source = node(*member(object, "get"), pointerAppend(path, "get")); + if (!source) { + return std::move(source.error()); + } + made.fieldPath = std::move(*segments); + made.args.push_back(std::move(*source)); + return std::nullopt; + } + + [[nodiscard]] std::optional comprehension(Expr& made, Json::object_t const& object, + std::string const& path) { + std::string_view sourceKey = "filter"; + std::string_view bodyKey = "where"; + if (made.kind == ExprKind::Map) { + sourceKey = "map"; + bodyKey = "to"; + } else if (made.kind == ExprKind::Sort) { + sourceKey = "sort"; + bodyKey = "by"; + } else if (made.kind == ExprKind::Runs) { + sourceKey = "runs"; + bodyKey = "by"; + } + Json const* const variable = member(object, "as"); + Json const* const body = member(object, bodyKey); + std::string const* const name = variable == nullptr ? nullptr : text(*variable); + if (name == nullptr || !isName(*name)) { + return refuse(pointerAppend(path, "as"), "`" + std::string{sourceKey} + "` names its element with `as`") + .error(); + } + if (body == nullptr) { + return refuse(path, "`" + std::string{sourceKey} + "` needs `" + std::string{bodyKey} + "`").error(); + } + made.name = *name; + auto source = node(*member(object, sourceKey), pointerAppend(path, sourceKey)); + if (!source) { + return std::move(source.error()); + } + auto each = node(*body, pointerAppend(path, bodyKey)); + if (!each) { + return std::move(each.error()); + } + made.args.push_back(std::move(*source)); + made.args.push_back(std::move(*each)); + if (Json const* const order = member(object, "order"); order != nullptr && made.kind == ExprKind::Sort) { + auto direction = node(*order, pointerAppend(path, "order")); + if (!direction) { + return std::move(direction.error()); + } + made.args.push_back(std::move(*direction)); + } + return std::nullopt; + } + + std::size_t _count = 0; + // NOLINTEND(misc-no-recursion) +}; + +/// @brief The static type of a literal. +/// @param value The literal. +/// @return Its type; `any` for `null`. +[[nodiscard]] Type typeOfValue(Value const& value) { + // The type kind of each value kind, indexed by `ValueKind`; `null` has no type of its own. + constexpr std::array kTypes = { + TypeKind::Any, TypeKind::Bool, TypeKind::Int, TypeKind::String, TypeKind::Decimal, + TypeKind::Quantity, TypeKind::Timestamp, TypeKind::List, TypeKind::Record, + }; + return Type::of(kTypes.at(static_cast(value.kind()))); +} + +/// @brief Walks an expression once, resolving names and checking the statically known types. +// NOLINTBEGIN(misc-no-recursion): an expression is a tree and checking descends it; the node bound limits the depth. +class ExprChecker { +public: + /// @brief Checks against @p resolver. + /// @param resolver What the names resolve to. + explicit ExprChecker(NameResolver const& resolver) : _resolver{&resolver} {} + + /// @brief Checks one node and its operands. + /// @param expr The node. + /// @return Its static type, or the refusal. + [[nodiscard]] std::expected check(Expr const& expr) { + switch (expr.kind) { + case ExprKind::Literal: + return typeOfValue(expr.literal); + case ExprKind::Ref: + return reference(expr); + case ExprKind::Row: + return wrap(expr, _resolver->row(expr.fieldPath)); + case ExprKind::Query: + case ExprKind::Pending: + case ExprKind::Error: + case ExprKind::Result: + case ExprKind::ErrorKind: + case ExprKind::Refusal: + case ExprKind::Can: + return wrap(expr, _resolver->control(expr.kind, expr.name)); + case ExprKind::Pref: + return wrap(expr, _resolver->pref(expr.name, expr.fieldPath)); + case ExprKind::Env: + return Type::of(expr.name == "online" ? TypeKind::Bool : TypeKind::String, expr.name != "online"); + case ExprKind::Session: + return Type::of(expr.name == "authenticated" ? TypeKind::Bool : TypeKind::String, + expr.name != "authenticated"); + case ExprKind::Host: + return Type::any(); + case ExprKind::If: + return choice(expr); + case ExprKind::Object: { + for (auto const& [name, field] : expr.fields) { + static_cast(name); + auto checked = check(*field); + if (!checked) { + return checked; + } + } + return Type::of(TypeKind::Record); + } + case ExprKind::List: { + for (ExprPtr const& item : expr.args) { + auto checked = check(*item); + if (!checked) { + return checked; + } + } + return Type::of(TypeKind::List); + } + case ExprKind::Map: + case ExprKind::Filter: + case ExprKind::Sort: + case ExprKind::Runs: + return comprehension(expr); + case ExprKind::Get: { + auto source = check(*expr.args.at(0)); + if (!source) { + return source; + } + if (!admitsKind(*source, kindBit(TypeKind::Record) | kindBit(TypeKind::List))) { + return refuse(expr, "`get` reads a path out of a record or a list, not " + source->name()); + } + return Type::any(); + } + case ExprKind::Call: + default: + return call(expr); + } + } + +private: + [[nodiscard]] static std::expected wrap(Expr const& expr, std::expected type) { + if (!type) { + return std::unexpected(Refusal{.document = {}, .path = expr.path, .reason = std::move(type.error())}); + } + return std::move(*type); + } + + [[nodiscard]] static std::unexpected refuse(Expr const& expr, std::string reason) { + return std::unexpected(Refusal{.document = {}, .path = expr.path, .reason = std::move(reason)}); + } + + [[nodiscard]] std::expected reference(Expr const& expr) { + for (auto const& [name, type] : std::views::reverse(_locals)) { + if (name == expr.name) { + return wrap(expr, typeAlong(type, expr.name, expr.fieldPath)); + } + } + return wrap(expr, _resolver->ref(expr.name, expr.fieldPath)); + } + + [[nodiscard]] static bool admitsKind(Type const& type, KindSet accepted) { + return type.kind == TypeKind::Any || (accepted & kindBit(type.kind)) != 0; + } + + [[nodiscard]] std::expected condition(Expr const& expr, std::string_view what) { + auto type = check(expr); + if (type && !admitsKind(*type, kindBit(TypeKind::Bool))) { + return refuse(expr, std::string{what} + " is " + type->name() + "; expected bool"); + } + return type; + } + + [[nodiscard]] std::expected choice(Expr const& expr) { + auto cond = condition(*expr.args.at(0), "the condition of `if`"); + if (!cond) { + return cond; + } + auto then = check(*expr.args.at(1)); + if (!then) { + return then; + } + auto otherwise = check(*expr.args.at(2)); + if (!otherwise) { + return otherwise; + } + if (then->kind == otherwise->kind && then->kind != TypeKind::List) { + return Type::of(then->kind, then->optional || otherwise->optional); + } + return Type::any(); + } + + [[nodiscard]] std::expected comprehension(Expr const& expr) { + auto source = check(*expr.args.at(0)); + if (!source) { + return source; + } + std::string_view form = "filter"; + if (expr.kind == ExprKind::Map) { + form = "map"; + } else if (expr.kind == ExprKind::Sort) { + form = "sort"; + } else if (expr.kind == ExprKind::Runs) { + form = "runs"; + } + if (!admitsKind(*source, kindBit(TypeKind::List))) { + return refuse(*expr.args.at(0), "`" + std::string{form} + "` runs over a list, not " + source->name()); + } + Type element = source->element ? *source->element : Type::any(); + _locals.emplace_back(expr.name, element); + auto body = expr.kind == ExprKind::Filter ? condition(*expr.args.at(1), "the `where` of `filter`") + : check(*expr.args.at(1)); + _locals.pop_back(); + if (!body) { + return body; + } + if (expr.kind == ExprKind::Map) { + return Type::listOf(*body); + } + if (expr.kind == ExprKind::Runs) { + return Type::listOf(Type::of(TypeKind::Record)); + } + if (expr.kind == ExprKind::Sort && expr.args.size() > 2) { + auto order = check(*expr.args.at(2)); + if (!order) { + return order; + } + if (!admitsKind(*order, kindBit(TypeKind::String))) { + return refuse(*expr.args.at(2), "the `order` of `sort` is " + order->name() + "; expected string"); + } + } + return Type::listOf(std::move(element)); + } + + [[nodiscard]] std::expected call(Expr const& expr) { + FunctionSpec const& spec = functionSpec(expr.function); + std::vector types; + for (std::size_t index = 0; index < expr.args.size(); ++index) { + auto type = check(*expr.args.at(index)); + if (!type) { + return type; + } + KindSet const accepted = spec.accepts.at(std::min(index, 2)); + if (!admitsKind(*type, accepted)) { + return refuse(*expr.args.at(index), "argument " + std::to_string(index + 1) + " of `" + + std::string{spec.name} + "` is " + type->name() + + ", which it does not take"); + } + types.push_back(std::move(*type)); + } + if (auto refused = literalRefusal(expr)) { + return std::unexpected(std::move(*refused)); + } + if (spec.result != TypeKind::Any) { + return Type::of(spec.result, true); + } + if (expr.function == FunctionId::ConcatLists) { + return concatenated(types); + } + if (expr.function == FunctionId::Slice) { + Type const& source = types.front(); + return Type::listOf(source.element ? *source.element : Type::any(), true); + } + return numericResult(expr.function, types); + } + + /// The checks of an argument written as a literal: a rounding mode and a `dateAdd` unit are checked at load, + /// because a wrong one is a wrong value, not a wrong look; a `t` fallback must be in the message subset. + [[nodiscard]] static std::optional literalRefusal(Expr const& expr) { + auto const literalText = [&expr](std::size_t index) -> std::string const* { + if (index >= expr.args.size() || expr.args.at(index)->kind != ExprKind::Literal) { + return nullptr; + } + return expr.args.at(index)->literal.asString(); + }; + if (auto const position = modeArgument(expr.function)) { + std::string const* const mode = literalText(*position); + if (mode != nullptr && !roundingMode(Value{*mode})) { + return refuse(*expr.args.at(*position), "the rounding mode is `halfEven` or `halfUp`").error(); + } + } + if (std::string const* const unit = literalText(2); + expr.function == FunctionId::DateAdd && unit != nullptr && !oneOf(kDateUnits, *unit)) { + return refuse(*expr.args.at(2), "the unit is `days`, `weeks`, `months`, `years`, `hours` or `minutes`") + .error(); + } + if (std::string const* const pattern = literalText(1); + expr.function == FunctionId::Translate && pattern != nullptr) { + auto parsed = parseMessage(*pattern); + if (!parsed) { + return refuse(*expr.args.at(1), "the fallback is outside the ui/1 message subset: " + parsed.error()) + .error(); + } + } + return std::nullopt; + } + + /// `concatLists`'s type: `list` when every element type that is known is `T`, else `list`. + [[nodiscard]] static Type concatenated(std::vector const& types) { + std::optional common; + for (Type const& type : types) { + if (type.isAny() || !type.element || type.element->isAny()) { + continue; + } + if (!common) { + common = *type.element; + } else if (!(*common == *type.element)) { + return Type::listOf(Type::any(), true); + } + } + return Type::listOf(common.value_or(Type::any()), true); + } + + [[nodiscard]] static Type numericResult(FunctionId function, std::vector const& types) { + if (function == FunctionId::Coalesce || function == FunctionId::Sum || function == FunctionId::Mean || + function == FunctionId::Min || function == FunctionId::Max || function == FunctionId::First || + function == FunctionId::Stdev) { + return Type::any(); + } + if (function == FunctionId::DateAdd) { + // The result keeps the value's form: a timestamp stays one, a date or ISO text stays text. + Type const& value = types.front(); + bool const known = value.kind == TypeKind::Timestamp || value.kind == TypeKind::String; + return known ? Type::of(value.kind, true) : Type::any(); + } + if (function == FunctionId::Neg || function == FunctionId::Round || function == FunctionId::Abs) { + return Type::of(types.front().kind, true); + } + Type const& lhs = types.at(0); + Type const& rhs = types.at(1); + if (lhs.isAny() || rhs.isAny()) { + return Type::any(); + } + bool const lhsQuantity = lhs.kind == TypeKind::Quantity; + bool const rhsQuantity = rhs.kind == TypeKind::Quantity; + if (lhsQuantity || rhsQuantity) { + if (function == FunctionId::Div && lhsQuantity && rhsQuantity) { + return Type::of(TypeKind::Decimal, true); + } + return Type::of(TypeKind::Quantity, true); + } + if (lhs.kind == TypeKind::Int && rhs.kind == TypeKind::Int && function != FunctionId::Div) { + return Type::of(TypeKind::Int, true); + } + return function == FunctionId::Div ? Type::any() : Type::of(TypeKind::Decimal, true); + } + + NameResolver const* _resolver; + std::vector> _locals; + // NOLINTEND(misc-no-recursion) +}; + +/// @brief Builds a numeric value. +/// @param value The exact value. +/// @param integer Whether every operand was an `int`. +/// @param unit The unit, or `nullptr`. +/// @return A quantity with a unit; an `int` when integral and every operand was one; a decimal otherwise. +[[nodiscard]] Value makeNumber(math::Rational const& value, bool integer, std::string const* unit) { + if (unit != nullptr) { + return Quantity{.value = value, .unit = *unit}; + } + if (integer && value.isInteger()) { + return Value{value.numerator}; + } + return Decimal{value}; +} + +/// @brief The fraction digits a currency shows (ISO 4217's minor unit). +/// @param currency The currency code. +/// @return 0, 2 or 3. +[[nodiscard]] std::uint32_t currencyDigits(std::string_view currency) { + static constexpr std::array kNone = { + "JPY", "KRW", "VND", "CLP", "ISK", "UGX", "XAF", "XOF", "PYG", + }; + static constexpr std::array kThree = {"BHD", "KWD", "OMR", "JOD", "TND", "IQD", "LYD"}; + if (oneOf(kNone, currency)) { + return 0; + } + return oneOf(kThree, currency) ? 3U : 2U; +} + +/// @brief A calendar day moved by whole months, its day of the month clamped to the target month's last day. +/// @param date The day. +/// @param months The months, negative to go back; bounded by the caller to the span of years 1 to 9999. +/// @return The moved day: `2026-01-31` plus one month is `2026-02-28`. +[[nodiscard]] std::chrono::year_month_day addMonths(std::chrono::year_month_day const& date, std::int64_t months) { + std::chrono::year_month_day const moved = date + std::chrono::months{static_cast(months)}; + if (moved.ok()) { + return moved; + } + return std::chrono::year_month_day{ + std::chrono::year_month_day_last{moved.year(), std::chrono::month_day_last{moved.month()}}}; +} + +/// @brief The largest amount of each `dateAdd` unit that can stay within years 1 to 9999, in `kDateUnits` order. +/// +/// Compared with the amount before any `std::chrono` arithmetic, whose day and month counts are narrower than +/// `int64`, so a huge amount is reported rather than narrowed into a date. +constexpr std::array kDateSpans = {3'652'059, 521'723, 119'988, 9'999, 87'649'416, 5'258'964'960}; + +/// @brief Whether a calendar day lies in years 1 to 9999, the years ISO text can write. +/// @param date The day. +/// @return Whether it is in range. +[[nodiscard]] bool inIsoRange(std::chrono::year_month_day const& date) { + return date.year() >= std::chrono::year{1} && date.year() <= std::chrono::year{9999}; +} + +/// @brief A calendar day as ISO text. +/// @param date The day. +/// @return `yyyy-MM-dd`. +[[nodiscard]] std::string isoDate(std::chrono::year_month_day const& date) { + return std::format("{:04}-{:02}-{:02}", static_cast(date.year()), static_cast(date.month()), + static_cast(date.day())); +} + +/// @brief A sample's exact moments over one denominator: the elements as integers `X = x * D`, their sum and the sum +/// of their squares, in 128 bits. +struct Moments { + /// @brief The count. + std::uint64_t count = 0; + /// @brief The common denominator `D`, the least common multiple of the elements' denominators. + std::uint64_t scale = 1; + /// @brief `|sum X|`. + math::detail::U128 sumMagnitude; + /// @brief `sum X^2`. + math::detail::U128 squares; + /// @brief The unit of a sample of quantities, the first element's; `nullptr` for plain numbers. + std::string const* unit = nullptr; +}; + +/// @brief The least common multiple of exact values' denominators, over which each value is an integer. +/// @param values The values, canonical. +/// @return The common denominator, or empty past `int64`. +[[nodiscard]] std::optional commonDenominator(std::vector const& values) { + std::uint64_t common = 1; + for (math::Rational const& value : values) { + auto const denominator = static_cast(value.denominator); + math::detail::U128 const product = math::detail::mulU64(common, denominator / std::gcd(common, denominator)); + if (product.hi != 0 || product.lo > static_cast(std::numeric_limits::max())) { + return std::nullopt; + } + common = product.lo; + } + return common; +} + +/// @brief A sample read for `stdev` and `rsd`: its moments, `null` without a report, or the reason to report. +using SampleReading = std::expected, std::string>; + +/// @brief The exact moments of a sample of numbers, or of quantities converted to the first element's unit. +/// +/// A `null` element makes the sample `null`; an element that is not a number, a quantity among plain numbers or units +/// that do not convert is a mismatch; a common denominator, an element or a sum that leaves its width overflows. +/// @param items The sample. +/// @param units The unit table. +/// @return The moments; empty for a `null` element; the reason for a mismatch or an overflow. +[[nodiscard]] SampleReading momentsOf(ValueList const& items, UnitTable const& units) { + using math::detail::U128; + std::vector values; + values.reserve(items.size()); + Moments moments; + for (std::size_t index = 0; index < items.size(); ++index) { + auto const number = numeric(items.at(index)); + if (items.at(index).isNull()) { + return std::optional{}; + } + if (!number) { + return std::unexpected(std::string{"an element is not a number"}); + } + if (index == 0) { + moments.unit = number->unit; + } else if ((moments.unit == nullptr) != (number->unit == nullptr)) { + return std::unexpected(std::string{"quantities and plain numbers do not combine"}); + } + auto converted = moments.unit == nullptr ? std::optional{number->value} + : convertUnit(number->value, *number->unit, *moments.unit, units); + if (!converted) { + return std::unexpected(std::string{"the elements' units do not convert"}); + } + values.push_back(*converted); + } + auto const scale = commonDenominator(values); + if (!scale) { + return std::unexpected(std::string{"the statistics overflow"}); + } + moments.scale = *scale; + U128 positive{}; + U128 negative{}; + for (math::Rational const& value : values) { + auto const denominator = static_cast(value.denominator); + U128 const scaled = math::detail::mulU64(math::detail::absU64(value.numerator), moments.scale / denominator); + auto squares = scaled.hi == 0 + ? math::detail::checkedAddU128(moments.squares, math::detail::mulU64(scaled.lo, scaled.lo)) + : std::nullopt; + auto sum = math::detail::checkedAddU128(value.numerator < 0 ? negative : positive, scaled); + if (!squares || !sum) { + return std::unexpected(std::string{"the statistics overflow"}); + } + moments.squares = *squares; + (value.numerator < 0 ? negative : positive) = *sum; + } + moments.count = values.size(); + moments.sumMagnitude = positive >= negative ? math::detail::wrappingSubU128(positive, negative) + : math::detail::wrappingSubU128(negative, positive); + return std::optional{moments}; +} + +/// @brief The standard deviation or the RSD of a sample, correctly rounded at @p places. +/// +/// With `n` elements `X = x * D`, `V = n * sum X^2 - (sum X)^2`: the sample standard deviation is the root of +/// `V * 10^(2 * places) / (n * (n - 1) * D^2)`, and the RSD in percent the root of +/// `10^(4 + 2 * places) * n * V / ((n - 1) * (sum X)^2)`, where `D` cancels. Nothing is rounded before the root. +/// @param moments The sample's moments, two or more elements. +/// @param relative Whether to compute the RSD. +/// @param places The places of the result. +/// @param mode The tie-breaking rule. +/// @return The result, or the reason it cannot be computed. +[[nodiscard]] std::expected spreadOf(Moments const& moments, bool relative, + std::uint32_t places, math::RoundingMode mode) { + using math::detail::checkedMulU128; + using math::detail::U128; + std::string const overflow = "the statistics overflow"; + U128 const count{.hi = 0, .lo = moments.count}; + U128 const degrees{.hi = 0, .lo = moments.count - 1}; + auto const scaledSquares = checkedMulU128(count, moments.squares); + auto const squaredSum = checkedMulU128(moments.sumMagnitude, moments.sumMagnitude); + // n * sum X^2 >= (sum X)^2 by Cauchy-Schwarz, so the difference is never negative. + auto const spread = + scaledSquares && squaredSum ? math::detail::checkedSubU128(*scaledSquares, *squaredSum) : std::nullopt; + if (!spread) { + return std::unexpected(overflow); + } + std::optional numerator; + std::optional denominator; + if (relative) { + if (moments.sumMagnitude == U128{}) { + return std::unexpected(std::string{"the RSD of values whose mean is zero"}); + } + auto const power = math::detail::powerOfTenU128(4 + (2 * places)); + auto const scaled = power ? checkedMulU128(*power, count) : std::nullopt; + numerator = scaled ? checkedMulU128(*scaled, *spread) : std::nullopt; + denominator = checkedMulU128(degrees, *squaredSum); + } else { + auto const power = math::detail::powerOfTenU128(2 * places); + numerator = power ? checkedMulU128(*spread, *power) : std::nullopt; + auto const pairs = checkedMulU128(count, degrees); + denominator = + pairs ? checkedMulU128(*pairs, math::detail::mulU64(moments.scale, moments.scale)) : std::nullopt; + } + auto const root = numerator && denominator + ? math::detail::roundSqrtOfFraction(*numerator, *denominator, places, mode) + : std::nullopt; + if (!root) { + return std::unexpected(overflow); + } + return *root; +} + +/// @brief Evaluates expressions against an environment, with the comprehension variables in scope. +// NOLINTBEGIN(misc-no-recursion): an expression is a tree and evaluating it descends it; the node bound limits the depth. +class EvaluatorCore { +public: + /// @brief Evaluates against @p env. + /// @param env What the expression reads. + explicit EvaluatorCore(Environment const& env) : _env{&env} {} + + /// @brief Evaluates one node. + /// @param expr The node. + /// @return Its value; `null` on a runtime error, which is reported. + [[nodiscard]] Value eval(Expr const& expr) { + switch (expr.kind) { + case ExprKind::Literal: + return expr.literal; + case ExprKind::Ref: + for (auto const& [name, value] : std::views::reverse(_locals)) { + if (name == expr.name) { + return walk(value, expr.fieldPath); + } + } + return _env->ref(expr.name, expr.fieldPath); + case ExprKind::Row: + return _env->row(expr.fieldPath); + case ExprKind::Query: + case ExprKind::Pending: + case ExprKind::Error: + case ExprKind::Result: + case ExprKind::ErrorKind: + case ExprKind::Refusal: + case ExprKind::Can: + return _env->control(expr.kind, expr.name); + case ExprKind::Pref: + return _env->pref(expr.name, expr.fieldPath); + case ExprKind::Env: + case ExprKind::Session: + case ExprKind::Host: + return _env->client(expr.kind, expr.name); + case ExprKind::If: + return choice(expr); + case ExprKind::Object: { + ValueRecord record; + for (auto const& [name, field] : expr.fields) { + record.insert_or_assign(name, eval(*field)); + } + return record; + } + case ExprKind::List: { + ValueList items; + items.reserve(expr.args.size()); + for (ExprPtr const& item : expr.args) { + items.push_back(eval(*item)); + } + return items; + } + case ExprKind::Map: + case ExprKind::Filter: + return comprehension(expr); + case ExprKind::Sort: + return sorted(expr); + case ExprKind::Runs: + return grouped(expr); + case ExprKind::Get: + return walk(eval(*expr.args.at(0)), expr.fieldPath); + case ExprKind::Call: + default: + return call(expr); + } + } + + /// @brief Orders two values as sorting does: as `lt` orders them, except that strings compare case-folded as + /// the table engine's default collator folds them, and by their own bytes when they fold the same, so + /// the order never depends on the source order. + /// @param lhs A value, not `null`. + /// @param rhs A value, not `null`. + /// @return The ordering; `nullopt` when the two are not of one comparable kind. + [[nodiscard]] std::optional sortOrder(Value const& lhs, Value const& rhs) { + std::string const* const lhsText = lhs.asString(); + std::string const* const rhsText = rhs.asString(); + if (lhsText != nullptr && rhsText != nullptr) { + table::CodePointCollator const collator; + std::strong_ordering const folded = collator.fold(*lhsText) <=> collator.fold(*rhsText); + return folded != std::strong_ordering::equal ? folded : *lhsText <=> *rhsText; + } + return order(lhs, rhs); + } + + /// @brief A stable order of rows by their sort keys: by each key in turn, `null` last in either direction, and + /// a descending key reversing the comparison, not the rows, so rows with equal keys keep their order. + /// @param keys Each row's keys, most significant first; every row has one per entry of @p descending. + /// @param descending Whether each key sorts descending. + /// @return The rows' indices in sorted order; `nullopt` when a key's values are not of one comparable kind. + [[nodiscard]] std::optional> sortRows(std::vector> const& keys, + std::vector const& descending) { + // Every value of a key is checked against the key's first value, so the comparison below never meets a + // pair it cannot order and the sort's ordering is strict and weak. + for (std::size_t level = 0; level < descending.size(); ++level) { + if (!orderable(keys, level)) { + return std::nullopt; + } + } + std::vector indices(keys.size()); + // NOLINTNEXTLINE(modernize-use-ranges): std::ranges::iota is missing from Emscripten's libc++. + std::iota(indices.begin(), indices.end(), std::size_t{0}); + std::ranges::stable_sort(indices, [&](std::size_t left, std::size_t right) { + for (std::size_t level = 0; level < descending.size(); ++level) { + std::strong_ordering const ordering = + keyOrder(keys.at(left).at(level), keys.at(right).at(level), descending.at(level)); + if (ordering != std::strong_ordering::equal) { + return ordering == std::strong_ordering::less; + } + } + return false; + }); + return indices; + } + + /// @brief Whether two `by` values put their elements in one run: `eq`'s comparison, except that `null` equals + /// `null`, so the elements without the value make one run. + /// @param lhs A value. + /// @param rhs A value. + /// @return Whether they are the same run's. + [[nodiscard]] bool sameRun(Value const& lhs, Value const& rhs) { return sameElement(lhs, rhs); } + +private: + Value mismatch(Expr const& expr, std::string_view reason) { + ++_mismatches; + _env->report(expr.path, reason); + return Value{}; + } + + /// The calendar day of a reading in the display zone: a date as it is, an instant shifted by the display offset. + [[nodiscard]] std::chrono::year_month_day localDay(DateValue const& reading) { + if (reading.form == DateForm::Date) { + return reading.date; + } + auto const local = reading.instant + std::chrono::minutes{_env->formatting().utcOffsetMinutes}; + return std::chrono::year_month_day{std::chrono::floor(local.value)}; + } + + /// `dateRange(from, to)`: the span of two days in the shortest form that stays unambiguous, `20–24 Oct 2026` + /// within a month, `28 Oct – 3 Nov 2026` within a year, and both days in full across years. It is one fixed + /// English form, not the application's date pattern, because the pattern writes a single day. + Value dateRange(Expr const& expr, std::vector const& args) { + DateValue const from = readDateValue(args.at(0)); + DateValue const until = readDateValue(args.at(1)); + if (from.form == DateForm::Unreadable || until.form == DateForm::Unreadable) { + return mismatch(expr, "`dateRange` takes two dates, timestamps or ISO text"); + } + if (from.form == DateForm::Absent || until.form == DateForm::Absent) { + return Value{}; + } + auto const first = localDay(from); + auto const last = localDay(until); + auto const month = [](std::chrono::year_month_day day) { + return std::string{detail::dates::kMonths.at(static_cast(day.month()) - 1)}; + }; + auto const dayOf = [](std::chrono::year_month_day day) { + return std::to_string(static_cast(day.day())); + }; + auto const yearOf = [](std::chrono::year_month_day day) { + return std::to_string(static_cast(day.year())); + }; + // U+2013 EN DASH, written as bytes so the source's character set cannot change it. + std::string const dash = "\xE2\x80\x93"; + std::string const separator = " " + dash + " "; + if (first.year() != last.year()) { + return dayOf(first) + " " + month(first) + " " + yearOf(first) + separator + dayOf(last) + " " + + month(last) + " " + yearOf(last); + } + if (first.month() != last.month()) { + return dayOf(first) + " " + month(first) + separator + dayOf(last) + " " + month(last) + " " + + yearOf(last); + } + if (first.day() == last.day()) { + return dayOf(last) + " " + month(last) + " " + yearOf(last); + } + return dayOf(first) + dash + dayOf(last) + " " + month(last) + " " + yearOf(last); + } + + /// `dateAdd(value, amount, unit)`: a date or an instant moved by whole units, in the value's own form. + Value addToDate(Expr const& expr, std::vector const& args) { + DateValue const reading = readDateValue(args.at(0)); + if (reading.form == DateForm::Absent) { + return Value{}; + } + std::int64_t const* const amount = args.at(1).asInt(); + std::string const* const unit = args.at(2).asString(); + auto const unitIndex = unit == nullptr ? kDateUnits.size() + : static_cast(std::ranges::distance( + kDateUnits.begin(), std::ranges::find(kDateUnits, *unit))); + if (reading.form == DateForm::Unreadable || amount == nullptr || unitIndex == kDateUnits.size()) { + return mismatch(expr, "`dateAdd` takes a date, a timestamp or ISO text, an int and a unit"); + } + bool const clock = unitIndex >= 4; + if (reading.form == DateForm::Date && clock) { + return mismatch(expr, "a date has no time of day; add hours to a timestamp"); + } + std::string_view const outOfRange = "the date is out of range"; + if (*amount > kDateSpans.at(unitIndex) || *amount < -kDateSpans.at(unitIndex)) { + return mismatch(expr, outOfRange); + } + bool const calendar = unitIndex == 2 || unitIndex == 3; + std::int64_t const months = unitIndex == 3 ? *amount * 12 : *amount; + std::int64_t const days = unitIndex == 1 ? *amount * 7 : *amount; + if (reading.form == DateForm::Date) { + std::chrono::year_month_day const moved = + calendar ? addMonths(reading.date, months) + : std::chrono::year_month_day{std::chrono::sys_days{reading.date} + + std::chrono::days{static_cast(days)}}; + if (!inIsoRange(moved)) { + return mismatch(expr, outOfRange); + } + return isoDate(moved); + } + time::DateTime moved = reading.instant; + if (calendar) { + // The calendar is the one at the display offset: the wall-clock time there is kept. + std::chrono::minutes const offset{_env->formatting().utcOffsetMinutes}; + auto const local = reading.instant.value + offset; + auto const day = std::chrono::floor(local); + std::chrono::year_month_day const date = addMonths(std::chrono::year_month_day{day}, months); + moved = time::DateTime{std::chrono::sys_days{date} + (local - day) - offset}; + } else if (unitIndex == 4) { + moved = time::DateTime{reading.instant.value + std::chrono::hours{*amount}}; + } else if (unitIndex == 5) { + moved = time::DateTime{reading.instant.value + std::chrono::minutes{*amount}}; + } else { + moved = time::DateTime{reading.instant.value + std::chrono::days{static_cast(days)}}; + } + if (!inIsoRange(std::chrono::year_month_day{std::chrono::floor(moved.value)})) { + return mismatch(expr, outOfRange); + } + if (reading.form == DateForm::Timestamp) { + return moved; + } + return moved.toIso8601(); + } + + /// `sqrt(x, dp, mode?)`: the root of a plain number, correctly rounded at `dp` places. + Value squareRoot(Expr const& expr, std::vector const& args) { + auto const number = numeric(args.at(0)); + std::int64_t const* const places = args.at(1).asInt(); + auto const mode = modeOf(args); + if (!number || number->unit != nullptr || places == nullptr || *places < 0 || + std::cmp_greater(*places, math::kMaxDecimalPlaces) || !mode) { + return mismatch(expr, "`sqrt` takes a plain number, places from 0 to 18 and a rounding mode"); + } + if (number->value.isNegative()) { + return mismatch(expr, "the square root of a negative number"); + } + auto const digits = static_cast(*places); + auto const power = math::detail::powerOfTenU128(2 * digits); + auto const scaled = + power ? math::detail::checkedMulU128( + math::detail::U128{.hi = 0, .lo = static_cast(number->value.numerator)}, *power) + : std::nullopt; + auto const root = + scaled ? math::detail::roundSqrtOfFraction( + *scaled, + math::detail::U128{.hi = 0, .lo = static_cast(number->value.denominator)}, + digits, *mode) + : std::nullopt; + if (!root) { + return mismatch(expr, "the result overflows"); + } + return Decimal{*root}; + } + + /// `stdev(list, dp, mode?)` and `rsd(list, dp, mode?)`: exact, rounded once at `dp` places. + Value statistic(Expr const& expr, std::vector const& args) { + ValueList const* const items = args.at(0).asList(); + std::int64_t const* const places = args.at(1).asInt(); + auto const mode = modeOf(args); + if (items == nullptr || places == nullptr || *places < 0 || + std::cmp_greater(*places, math::kMaxDecimalPlaces) || !mode) { + return mismatch(expr, "the statistics take a list, places from 0 to 18 and a rounding mode"); + } + SampleReading const sample = momentsOf(*items, _env->formatting().units); + if (!sample) { + return mismatch(expr, sample.error()); + } + // Fewer than two values is a worksheet still being filled: no spread yet, and nothing to report. + if (!sample->has_value() || (*sample)->count < 2) { + return Value{}; + } + bool const relative = expr.function == FunctionId::Rsd; + auto const spread = spreadOf(**sample, relative, static_cast(*places), *mode); + if (!spread) { + return mismatch(expr, spread.error()); + } + if (!relative && (*sample)->unit != nullptr) { + return Quantity{.value = *spread, .unit = *(*sample)->unit}; + } + return Decimal{*spread}; + } + + /// The rounding mode of a call whose mode is its third argument: half to even when it is absent. + static std::optional modeOf(std::vector const& args) { + if (args.size() < 3) { + return math::RoundingMode::HalfEven; + } + return roundingMode(args.at(2)); + } + + Value choice(Expr const& expr) { + Value const cond = eval(*expr.args.at(0)); + if (cond.isNull()) { + return Value{}; + } + bool const* const flag = cond.asBool(); + if (flag == nullptr) { + return mismatch(expr, "the condition of `if` is not a bool"); + } + return eval(*expr.args.at(*flag ? 1 : 2)); + } + + Value comprehension(Expr const& expr) { + Value const source = eval(*expr.args.at(0)); + if (source.isNull()) { + return Value{}; + } + ValueList const* const items = source.asList(); + if (items == nullptr) { + return mismatch(expr, "a comprehension runs over a list"); + } + ValueList out; + for (Value const& item : *items) { + _locals.emplace_back(expr.name, item); + Value body = eval(*expr.args.at(1)); + _locals.pop_back(); + if (expr.kind == ExprKind::Map) { + out.push_back(std::move(body)); + continue; + } + bool const* const keep = body.asBool(); + if (keep == nullptr && !body.isNull()) { + return mismatch(expr, "the `where` of `filter` is not a bool"); + } + if (keep != nullptr && *keep) { + out.push_back(item); + } + } + return out; + } + + /// Whether every value of one sort key orders against the key's first value; `null`s aside. + bool orderable(std::vector> const& keys, std::size_t level) { + Value const* first = nullptr; + for (std::vector const& row : keys) { + Value const& value = row.at(level); + if (value.isNull()) { + continue; + } + if (first == nullptr) { + first = &value; + } else if (!sortOrder(*first, value)) { + return false; + } + } + return true; + } + + /// Where @p lhs sorts against @p rhs for one key: `null` last either way, and a descending key reverses the + /// comparison, so equal values compare equal and keep their order. + std::strong_ordering keyOrder(Value const& lhs, Value const& rhs, bool descending) { + if (lhs.isNull() || rhs.isNull()) { + if (lhs.isNull() == rhs.isNull()) { + return std::strong_ordering::equal; + } + return lhs.isNull() ? std::strong_ordering::greater : std::strong_ordering::less; + } + std::strong_ordering const ordering = sortOrder(lhs, rhs).value_or(std::strong_ordering::equal); + if (!descending || ordering == std::strong_ordering::equal) { + return ordering; + } + return ordering == std::strong_ordering::less ? std::strong_ordering::greater : std::strong_ordering::less; + } + + /// `runs`: the list split into runs of adjacent elements whose `by` values are equal. + Value grouped(Expr const& expr) { + Value const source = eval(*expr.args.at(0)); + if (source.isNull()) { + return Value{}; + } + ValueList const* const items = source.asList(); + if (items == nullptr) { + return mismatch(expr, "`runs` runs over a list"); + } + ValueList out; + Value key; + ValueList run; + for (Value const& item : *items) { + std::size_t const before = _mismatches; + _locals.emplace_back(expr.name, item); + Value value = eval(*expr.args.at(1)); + _locals.pop_back(); + // A `by` that fails for an element fails the whole form, as a mismatch inside any operand does. + if (_mismatches != before) { + return Value{}; + } + if (run.empty()) { + key = std::move(value); + } else if (!sameRun(key, value)) { + out.push_back(runRecord(std::exchange(key, std::move(value)), std::exchange(run, {}))); + } + run.push_back(item); + } + if (!run.empty()) { + out.push_back(runRecord(std::move(key), std::move(run))); + } + return out; + } + + /// `sort`: the list ordered by `by`, ascending unless `order` is `"desc"`. + Value sorted(Expr const& expr) { + Value const source = eval(*expr.args.at(0)); + if (source.isNull()) { + return Value{}; + } + ValueList const* const items = source.asList(); + if (items == nullptr) { + return mismatch(expr, "`sort` runs over a list"); + } + bool descending = false; + if (expr.args.size() > 2) { + Value const given = eval(*expr.args.at(2)); + std::string const* const direction = given.asString(); + if (!given.isNull() && (direction == nullptr || (*direction != "asc" && *direction != "desc"))) { + return mismatch(expr, R"(the `order` of `sort` is "asc" or "desc")"); + } + descending = direction != nullptr && *direction == "desc"; + } + std::vector> keys; + keys.reserve(items->size()); + for (Value const& item : *items) { + _locals.emplace_back(expr.name, item); + keys.emplace_back(1, eval(*expr.args.at(1))); + _locals.pop_back(); + } + auto const ranked = sortRows(keys, {descending}); + if (!ranked) { + return mismatch(expr, "the `by` values of `sort` are not of one comparable kind"); + } + ValueList out; + out.reserve(items->size()); + for (std::size_t const index : *ranked) { + out.push_back(items->at(index)); + } + return out; + } + + /// `slice`: `count` elements of the list from `start`, or every element from it. + Value sliced(Expr const& expr, std::vector const& args) { + ValueList const* const items = args.at(0).asList(); + std::int64_t const* const start = args.at(1).asInt(); + std::int64_t const* const count = args.size() > 2 ? args.at(2).asInt() : nullptr; + bool const badCount = args.size() > 2 && (count == nullptr || *count < 0); + if (items == nullptr || start == nullptr || *start < 0 || badCount) { + return mismatch(expr, "`slice` takes a list, a start and a count of 0 or more"); + } + auto const from = static_cast(std::min(*start, std::ssize(*items))); + std::size_t const left = items->size() - from; + std::size_t const taken = count == nullptr ? left : std::min(left, static_cast(*count)); + auto const first = items->begin() + static_cast(from); + return ValueList{first, first + static_cast(taken)}; + } + + /// Three-valued `and` / `or`: the dominant value wins over `null`. + Value kleene(Expr const& expr, bool dominant) { + bool sawNull = false; + for (ExprPtr const& arg : expr.args) { + Value const value = eval(*arg); + if (bool const* const flag = value.asBool()) { + if (*flag == dominant) { + return dominant; + } + continue; + } + if (!value.isNull()) { + _env->report(arg->path, "a logical operand is not a bool"); + } + sawNull = true; + } + if (sawNull) { + return Value{}; + } + return !dominant; + } + + // NOLINTNEXTLINE(readability-function-cognitive-complexity): the four operators over plain numbers and quantities, one rule each. + Value arithmetic(Expr const& expr, Value const& lhsValue, Value const& rhsValue) { + auto const lhs = numeric(lhsValue); + auto const rhs = numeric(rhsValue); + if (!lhs || !rhs) { + return mismatch(expr, "an arithmetic operand is not a number"); + } + UnitTable const& units = _env->formatting().units; + FunctionId const function = expr.function; + math::Rational right = rhs->value; + std::string const* unit = nullptr; + if (lhs->unit != nullptr && rhs->unit != nullptr) { + if (function == FunctionId::Mul) { + return mismatch(expr, "a product of two quantities has no declared unit"); + } + auto converted = convertUnit(rhs->value, *rhs->unit, *lhs->unit, units); + if (!converted) { + return mismatch(expr, "the units `" + *lhs->unit + "` and `" + *rhs->unit + "` do not convert"); + } + right = *converted; + unit = function == FunctionId::Div ? nullptr : lhs->unit; + } else if (lhs->unit != nullptr || rhs->unit != nullptr) { + bool const scales = function == FunctionId::Mul || (function == FunctionId::Div && lhs->unit != nullptr); + if (!scales) { + return mismatch(expr, "a quantity and a plain number do not combine this way"); + } + unit = lhs->unit != nullptr ? lhs->unit : rhs->unit; + } + if (function == FunctionId::Div && right.isZero()) { + return mismatch(expr, "division by zero"); + } + std::expected result = math::Rational{}; + if (function == FunctionId::Add) { + result = math::checkedAdd(lhs->value, right); + } else if (function == FunctionId::Sub) { + result = math::checkedSub(lhs->value, right); + } else if (function == FunctionId::Mul) { + result = math::checkedMul(lhs->value, right); + } else { + result = math::checkedDiv(lhs->value, right); + } + if (!result) { + return mismatch(expr, "the result overflows"); + } + // A quantity is never an `int`, so a ratio of two quantities comes back a decimal. + return makeNumber(*result, lhs->integer && rhs->integer, unit); + } + + /// Orders two values of one comparable kind: numbers exactly (quantities converted), timestamps, strings. + std::optional order(Value const& lhs, Value const& rhs) { + auto const lhsNumber = numeric(lhs); + auto const rhsNumber = numeric(rhs); + if (lhsNumber && rhsNumber) { + if ((lhsNumber->unit == nullptr) != (rhsNumber->unit == nullptr)) { + return std::nullopt; + } + math::Rational right = rhsNumber->value; + if (lhsNumber->unit != nullptr) { + auto converted = convertUnit(right, *rhsNumber->unit, *lhsNumber->unit, _env->formatting().units); + if (!converted) { + return std::nullopt; + } + right = *converted; + } + return lhsNumber->value <=> right; + } + if (time::DateTime const* const lhsTime = lhs.asTimestamp()) { + if (time::DateTime const* const rhsTime = rhs.asTimestamp()) { + return *lhsTime <=> *rhsTime; + } + return std::nullopt; + } + if (std::string const* const lhsText = lhs.asString()) { + if (std::string const* const rhsText = rhs.asString()) { + return *lhsText <=> *rhsText; + } + } + return std::nullopt; + } + + /// Equality over non-null values: numbers by value, lists and records element-wise, other kinds by identity. + bool equal(Value const& lhs, Value const& rhs) { + if (numeric(lhs) && numeric(rhs)) { + auto const ordering = order(lhs, rhs); + return ordering.has_value() && *ordering == std::strong_ordering::equal; + } + if (lhs.kind() != rhs.kind()) { + return false; + } + if (ValueList const* const lhsItems = lhs.asList()) { + return std::ranges::equal(*lhsItems, *rhs.asList(), [this](Value const& left, Value const& right) { + return sameElement(left, right); + }); + } + if (ValueRecord const* const lhsFields = lhs.asRecord()) { + // Records are ordered by field name, so equal records have equal sequences of fields. + return std::ranges::equal(*lhsFields, *rhs.asRecord(), [this](auto const& left, auto const& right) { + return left.first == right.first && sameElement(left.second, right.second); + }); + } + return lhs == rhs; + } + + /// Equality of two elements of a list or record, where `null` equals only `null`. + bool sameElement(Value const& left, Value const& right) { + if (left.isNull() || right.isNull()) { + return left.isNull() && right.isNull(); + } + return equal(left, right); + } + + /// The display text of a value, as `format` shows an argument. + std::optional display(Value const& value) { + FormatContext const& context = _env->formatting(); + if (std::string const* const text = value.asString()) { + return *text; + } + if (bool const* const flag = value.asBool()) { + return std::string{*flag ? "true" : "false"}; + } + if (Quantity const* const quantity = value.asQuantity()) { + auto number = formatNumber(value, withoutGrouping(context.numeric)); + if (!number) { + return std::nullopt; + } + return *number + " " + unitDisplay(quantity->unit, context.units); + } + if (auto number = formatNumber(value, withoutGrouping(context.numeric))) { + return number; + } + if (time::DateTime const* const instant = value.asTimestamp()) { + return dateText(*instant, "medium", true); + } + return std::nullopt; + } + + std::optional dateText(time::DateTime instant, std::string_view style, bool withTime) { + return localDateText(instant + std::chrono::minutes{_env->formatting().utcOffsetMinutes}, style, withTime); + } + + /// The text of a wall-clock time already in the display zone. + std::optional localDateText(time::DateTime local, std::string_view style, bool withTime) { + if (style != "short" && style != "medium" && style != "long") { + return std::nullopt; + } + FormatContext const& context = _env->formatting(); + if (context.dates) { + return context.dates(local, style, withTime); + } + // One pattern for every style, so a screen never mixes two forms of a date; the style chooses a form only + // while no pattern is set. + if (std::string const& pattern = withTime ? context.dateTimePattern : context.datePattern; !pattern.empty()) { + return formatDate(pattern, local, context.utcOffsetMinutes); + } + std::string const iso = local.toIso8601(); + if (!withTime) { + return iso.substr(0, 10); + } + return iso.substr(0, 10) + " " + iso.substr(11, style == "long" ? 8 : 5); + } + + /// Why `format` cannot show an argument: a number that overflows at its places, or a value it has no text for. + Value cannotShow(Expr const& expr, Value const& arg, std::size_t index) { + if (numeric(arg)) { + return mismatch(expr, "the result overflows"); + } + return mismatch(expr, "`format` cannot show argument " + std::to_string(index + 1)); + } + + Value formatTemplate(Expr const& expr, std::vector const& args) { + std::string const& pattern = *args.front().asString(); + std::vector shown; + for (std::size_t index = 1; index < args.size(); ++index) { + auto text = display(args.at(index)); + if (!text) { + return cannotShow(expr, args.at(index), index); + } + shown.push_back(std::move(*text)); + } + std::string out; + for (std::size_t pos = 0; pos < pattern.size(); ++pos) { + char const chr = pattern.at(pos); + if ((chr == '{' || chr == '}') && pos + 1 < pattern.size() && pattern.at(pos + 1) == chr) { + out += chr; + ++pos; + continue; + } + if (chr == '}') { + return mismatch(expr, "`format`'s template has an unmatched `}`"); + } + if (chr != '{') { + out += chr; + continue; + } + std::size_t const close = pattern.find('}', pos); + std::string_view const digits = close == std::string::npos + ? std::string_view{} + : std::string_view{pattern}.substr(pos + 1, close - pos - 1); + std::size_t index = 0; + bool valid = !digits.empty() && digits.size() < 4; + for (char const digit : digits) { + valid = valid && digit >= '0' && digit <= '9'; + index = valid ? (index * 10) + static_cast(digit - '0') : index; + } + if (!valid || index >= shown.size()) { + return mismatch(expr, "`format`'s template has a placeholder with no argument"); + } + out += shown.at(index); + pos = close; + } + return out; + } + + /// The named arguments a list of `{name, value}` records gives a message, each value as text. An element that is + /// not such a record is reported and left out. + ValueRecord namedArguments(Expr const& expr, ValueList const& list) { + ValueRecord named; + for (Value const& item : list) { + ValueRecord const* const entry = item.asRecord(); + auto const text = [entry](char const* field) -> std::string const* { + if (entry == nullptr) { + return nullptr; + } + auto const found = entry->find(field); + return found == entry->end() ? nullptr : found->second.asString(); + }; + std::string const* const argName = text("name"); + std::string const* const argValue = text("value"); + if (argName == nullptr || argValue == nullptr) { + _env->report(expr.path, "an argument of the message is a record of a string `name` and `value`"); + continue; + } + named.insert_or_assign(*argName, Value{*argValue}); + } + return named; + } + + /// Formats the catalogue's message for @p key in the active locale with @p named, else @p fallback. + /// @param reportMissing Whether a key the catalogue lacks is a problem (a key known only at run time). + std::string catalogued(Expr const& expr, std::string const& key, std::string const& fallback, + ValueRecord const& named, bool reportMissing) { + FormatContext const& context = _env->formatting(); + std::optional message; + if (context.translations) { + if (auto const pattern = context.translations(key, context.locale)) { + auto parsed = parseMessage(*pattern); + if (parsed) { + message = std::move(*parsed); + } else { + _env->report(expr.path, "the catalogue's message `" + key + + "` is outside the ui/1 subset: " + parsed.error()); + } + } + } + if (!message && reportMissing) { + _env->report(expr.path, "the catalogue has no message for the key `" + key + "`"); + } + if (!message) { + auto parsed = parseMessage(fallback); + if (!parsed) { + _env->report(expr.path, "the fallback is outside the ui/1 subset: " + parsed.error()); + return fallback; + } + message = std::move(*parsed); + } + FormattedMessage formatted = + formatMessage(*message, named, MessageLocale{.locale = context.locale, .numeric = context.numeric}); + for (std::string const& error : formatted.errors) { + _env->report(expr.path, error); + } + return std::move(formatted.text); + } + + Value translate(Expr const& expr, std::vector const& args) { + std::string const& key = *args.at(0).asString(); + std::string const& fallback = *args.at(1).asString(); + ValueRecord const empty; + ValueRecord listed; + ValueRecord const* named = ∅ + if (args.size() > 2) { + if (ValueList const* const list = args.at(2).asList()) { + listed = namedArguments(expr, *list); + named = &listed; + } else { + named = args.at(2).asRecord(); + } + if (named == nullptr) { + return mismatch(expr, "the arguments of `t` are a record, or a list of `{name, value}` records"); + } + } + bool const computedKey = expr.args.front()->kind != ExprKind::Literal; + return catalogued(expr, key, fallback, *named, computedKey); + } + + /// `refusalText`: the sentence for an action refusal `{code, args}`. + Value refusalText(Expr const& expr, Value const& refusal) { + ValueRecord const* const record = refusal.asRecord(); + auto const field = [record](char const* name) -> Value const* { + if (record == nullptr) { + return nullptr; + } + auto const found = record->find(name); + return found == record->end() ? nullptr : &found->second; + }; + Value const* const code = field("code"); + Value const* const list = field("args"); + if (code == nullptr || code->asString() == nullptr) { + return mismatch(expr, "`refusalText` takes a refusal, a record with a string `code`"); + } + ValueRecord named; + if (list != nullptr && list->asList() != nullptr) { + named = namedArguments(expr, *list->asList()); + } + FormatContext const& context = _env->formatting(); + std::string const& codeText = *code->asString(); + bool const hasCode = context.translations && context.translations(codeText, context.locale).has_value(); + if (hasCode) { + return catalogued(expr, codeText, std::string{kBuiltInRefusal}, named, false); + } + _env->report(expr.path, "the catalogue has no message for the refusal code `" + codeText + "`"); + // Each dotted prefix of the code, longest first, with `.generic` after it. + for (std::string prefix = codeText; prefix.rfind('.') != std::string::npos;) { + prefix.erase(prefix.rfind('.')); + std::string const classKey = prefix + ".generic"; + if (context.translations && context.translations(classKey, context.locale)) { + return catalogued(expr, classKey, std::string{kBuiltInRefusal}, named, false); + } + } + return std::string{kBuiltInRefusal}; + } + + Value listFunction(Expr const& expr, ValueList const& items) { + FunctionId const function = expr.function; + if (function == FunctionId::Count) { + return static_cast(items.size()); + } + if (function == FunctionId::First) { + if (items.empty()) { + return Value{}; + } + return items.front(); + } + if (function == FunctionId::Any || function == FunctionId::All) { + bool const dominant = function == FunctionId::Any; + bool sawNull = false; + for (Value const& item : items) { + bool const* const flag = item.asBool(); + if (flag != nullptr && *flag == dominant) { + return dominant; + } + if (flag == nullptr && !item.isNull()) { + return mismatch(expr, "an element is not a bool"); + } + sawNull = sawNull || item.isNull(); + } + if (sawNull) { + return Value{}; + } + return !dominant; + } + if (function == FunctionId::Min || function == FunctionId::Max) { + return extreme(expr, items); + } + return aggregate(expr, items); + } + + Value extreme(Expr const& expr, ValueList const& items) { + if (items.empty()) { + return Value{}; + } + Value const* best = &items.front(); + for (Value const& item : items) { + if (item.isNull()) { + return Value{}; + } + auto const ordering = order(item, *best); + if (!ordering) { + return mismatch(expr, "the elements are not of one comparable kind"); + } + bool const better = expr.function == FunctionId::Min ? std::is_lt(*ordering) : std::is_gt(*ordering); + if (better) { + best = &item; + } + } + return *best; + } + + Value aggregate(Expr const& expr, ValueList const& items) { + bool const mean = expr.function == FunctionId::Mean; + if (items.empty()) { + return mean ? Value{} : Value{std::int64_t{0}}; + } + math::Rational total{0, math::DecimalPlaces{0}}; + bool integer = true; + std::string const* unit = nullptr; + std::uint32_t places = 0; + for (std::size_t index = 0; index < items.size(); ++index) { + Value const& item = items.at(index); + if (item.isNull()) { + return Value{}; + } + auto const number = numeric(item); + if (!number) { + return mismatch(expr, "an element is not a number"); + } + if (index == 0) { + unit = number->unit; + } else if ((unit == nullptr) != (number->unit == nullptr)) { + return mismatch(expr, "quantities and plain numbers do not sum together"); + } + math::Rational value = number->value; + if (unit != nullptr) { + auto converted = convertUnit(value, *number->unit, *unit, _env->formatting().units); + if (!converted) { + return mismatch(expr, "the elements' units do not convert"); + } + value = *converted; + } + places = std::max(places, value.decimalPlaces.value); + integer = integer && number->integer; + auto next = math::checkedAdd(total, value); + if (!next) { + return mismatch(expr, "the sum overflows"); + } + total = *next; + } + if (!mean) { + return makeNumber(total, integer, unit); + } + auto const quotient = + math::checkedDiv(total, math::Rational{static_cast(items.size()), math::DecimalPlaces{0}}); + auto const rounded = quotient ? math::checkedRoundToDecimalPlaces(*quotient, math::DecimalPlaces{places}, + math::RoundingMode::HalfEven) + : std::nullopt; + if (!rounded) { + return mismatch(expr, "the result overflows"); + } + return makeNumber(*rounded, integer, unit); + } + + Value call(Expr const& expr) { + FunctionId const function = expr.function; + if (function == FunctionId::And || function == FunctionId::Or) { + return kleene(expr, function == FunctionId::Or); + } + if (function == FunctionId::Coalesce) { + for (ExprPtr const& arg : expr.args) { + Value value = eval(*arg); + if (!value.isNull()) { + return value; + } + } + return Value{}; + } + if (function == FunctionId::Engaged) { + return !eval(*expr.args.front()).isNull(); + } + std::vector args; + args.reserve(expr.args.size()); + for (ExprPtr const& arg : expr.args) { + args.push_back(eval(*arg)); + if (args.back().isNull()) { + return Value{}; + } + } + return strict(expr, args); + } + + /// The functions whose every argument is required: any `null` argument has already made the result `null`. + // GCC's -Wstrict-overflow fires on this whole function at -O3, attributing it to the function's opening line + // rather than a specific statement -- a known false positive from its range analysis across the switch's many + // checked-arithmetic calls (Rational's own checkedAdd/checkedSub/checkedMul are all free of signed-overflow UB). +#if defined(__GNUC__) && !defined(__clang__) +#pragma GCC diagnostic push +#pragma GCC diagnostic ignored "-Wstrict-overflow" +#endif + // NOLINTNEXTLINE(readability-function-cognitive-complexity): one case per function of the library. + Value strict(Expr const& expr, std::vector const& args) { + FormatContext const& context = _env->formatting(); + switch (expr.function) { + case FunctionId::Not: { + bool const* const flag = args.front().asBool(); + if (flag == nullptr) { + return mismatch(expr, "`not` takes a bool"); + } + return !*flag; + } + case FunctionId::Eq: + return equal(args.at(0), args.at(1)); + case FunctionId::Ne: + return !equal(args.at(0), args.at(1)); + case FunctionId::Lt: + case FunctionId::Le: + case FunctionId::Gt: + case FunctionId::Ge: { + auto const ordering = order(args.at(0), args.at(1)); + if (!ordering) { + return mismatch(expr, "the operands are not of one comparable kind"); + } + if (expr.function == FunctionId::Lt) { + return std::is_lt(*ordering); + } + if (expr.function == FunctionId::Le) { + return std::is_lteq(*ordering); + } + if (expr.function == FunctionId::Gt) { + return std::is_gt(*ordering); + } + return std::is_gteq(*ordering); + } + case FunctionId::Add: + case FunctionId::Sub: + case FunctionId::Mul: + case FunctionId::Div: + return arithmetic(expr, args.at(0), args.at(1)); + case FunctionId::Neg: { + auto const number = numeric(args.front()); + if (!number) { + return mismatch(expr, "`neg` takes a number"); + } + auto negated = math::checkedSub(math::Rational{0, number->value.decimalPlaces}, number->value); + if (!negated) { + return mismatch(expr, "the result overflows"); + } + return makeNumber(*negated, number->integer, number->unit); + } + case FunctionId::Round: { + auto const number = numeric(args.at(0)); + std::int64_t const* const places = args.at(1).asInt(); + if (!number || places == nullptr || *places < 0 || + std::cmp_greater(*places, math::kMaxDecimalPlaces)) { + return mismatch(expr, "`round` takes a number and places from 0 to 18"); + } + auto const mode = modeOf(args); + if (!mode) { + return mismatch(expr, "the rounding mode is `halfEven` or `halfUp`"); + } + if (number->integer) { + return args.at(0); + } + auto const rounded = math::checkedRoundToDecimalPlaces( + number->value, math::DecimalPlaces{static_cast(*places)}, *mode); + if (!rounded) { + return mismatch(expr, "the result overflows"); + } + return makeNumber(*rounded, false, number->unit); + } + case FunctionId::Concat: { + std::string out; + for (Value const& arg : args) { + std::string const* const text = arg.asString(); + if (text == nullptr) { + return mismatch(expr, "`concat` takes strings"); + } + out += *text; + } + return out; + } + case FunctionId::Format: + if (args.front().asString() == nullptr) { + return mismatch(expr, "`format`'s template is a string"); + } + return formatTemplate(expr, args); + case FunctionId::Trim: { + std::string const* const text = args.front().asString(); + if (text == nullptr) { + return mismatch(expr, "`trim` takes a string"); + } + constexpr std::string_view kSpace = " \t\n\r\f\v"; + std::size_t const first = text->find_first_not_of(kSpace); + if (first == std::string::npos) { + return std::string{}; + } + return text->substr(first, text->find_last_not_of(kSpace) - first + 1); + } + case FunctionId::Length: { + std::string const* const text = args.front().asString(); + if (text == nullptr) { + return mismatch(expr, "`length` takes a string"); + } + std::int64_t points = 0; + for (char const chr : *text) { + points += (static_cast(chr) & 0xC0U) == 0x80U ? 0 : 1; + } + return points; + } + case FunctionId::IsEmpty: { + if (std::string const* const text = args.front().asString()) { + return text->empty(); + } + if (ValueList const* const items = args.front().asList()) { + return items->empty(); + } + return mismatch(expr, "`isEmpty` takes a string or a list"); + } + case FunctionId::Contains: { + std::string const* const text = args.at(0).asString(); + std::string const* const part = args.at(1).asString(); + if (text == nullptr || part == nullptr) { + return mismatch(expr, "`contains` takes two strings"); + } + return text->contains(*part); + } + case FunctionId::Count: + case FunctionId::Sum: + case FunctionId::Mean: + case FunctionId::Min: + case FunctionId::Max: + case FunctionId::Any: + case FunctionId::All: + case FunctionId::First: { + ValueList const* const items = args.front().asList(); + if (items == nullptr) { + return mismatch(expr, "the argument is not a list"); + } + return listFunction(expr, *items); + } + case FunctionId::Includes: + case FunctionId::IndexOf: { + ValueList const* const items = args.at(0).asList(); + if (items == nullptr) { + return mismatch(expr, "the first argument is not a list"); + } + for (std::size_t index = 0; index < items->size(); ++index) { + if (!items->at(index).isNull() && equal(items->at(index), args.at(1))) { + return expr.function == FunctionId::Includes ? Value{true} + : Value{static_cast(index)}; + } + } + return expr.function == FunctionId::Includes ? Value{false} : Value{}; + } + case FunctionId::Number: { + auto text = formatNumber(args.front(), context.numeric); + if (!text) { + return mismatch(expr, numeric(args.front()) ? "the result overflows" : "`number` takes a number"); + } + return std::move(*text); + } + case FunctionId::DecimalText: { + auto const number = numeric(args.at(0)); + std::int64_t const* const places = args.at(1).asInt(); + if (!number || places == nullptr || *places < 0 || + std::cmp_greater(*places, math::kMaxDecimalPlaces)) { + return mismatch(expr, "`decimal` takes a number and places from 0 to 18"); + } + auto const mode = modeOf(args); + if (!mode) { + return mismatch(expr, "the rounding mode is `halfEven` or `halfUp`"); + } + auto const text = decimalText(number->value, static_cast(*places), *mode); + if (!text) { + return mismatch(expr, "the result overflows"); + } + return render::formatCanonicalNumber(*text, context.numeric); + } + case FunctionId::QuantityText: { + Quantity const* const quantity = args.at(0).asQuantity(); + if (quantity == nullptr) { + return mismatch(expr, "`quantity` takes a quantity"); + } + Quantity shown = *quantity; + if (args.size() > 1) { + std::string const* const unit = args.at(1).asString(); + auto converted = unit == nullptr + ? std::nullopt + : convertUnit(quantity->value, quantity->unit, *unit, context.units); + if (!converted) { + return mismatch(expr, "the quantity does not convert to that unit"); + } + shown = Quantity{.value = *converted, .unit = *unit}; + } + auto const text = formatNumber(shown, context.numeric); + if (!text) { + return mismatch(expr, "the result overflows"); + } + return *text + " " + unitDisplay(shown.unit, context.units); + } + case FunctionId::Money: { + auto const number = numeric(args.at(0)); + std::string const* const currency = args.at(1).asString(); + if (!number || number->unit != nullptr || currency == nullptr) { + return mismatch(expr, "`money` takes an amount and a currency code"); + } + auto const text = decimalText(number->value, currencyDigits(*currency)); + if (!text) { + return mismatch(expr, "the result overflows"); + } + MoneyForm form = MoneyForm::Symbol; + if (args.size() > 2) { + std::string const* const named = args.at(2).asString(); + if (named == nullptr || (*named != "symbol" && *named != "code")) { + return mismatch(expr, R"(`money`'s form is "symbol" or "code")"); + } + form = *named == "code" ? MoneyForm::Code : MoneyForm::Symbol; + } + return placeCurrency(render::formatCanonicalNumber(*text, context.numeric), *currency, + context.currency, context.numeric, form); + } + case FunctionId::Date: + case FunctionId::DateTime: { + DateValue const reading = readDateValue(args.at(0)); + // `""` is a date not given yet, as a cleared date input writes: nothing to show, nothing to report. + if (reading.form == DateForm::Absent) { + return Value{}; + } + std::string const* const style = args.size() > 1 ? args.at(1).asString() : nullptr; + std::string_view const shownStyle = style == nullptr ? std::string_view{"medium"} : *style; + bool const withTime = expr.function == FunctionId::DateTime; + std::optional text; + if (args.size() > 1 && style == nullptr) { + text = std::nullopt; + } else if (reading.form == DateForm::Date) { + // A date is that calendar day at any offset: its midnight is already local. + text = localDateText(time::DateTime{std::chrono::sys_days{reading.date}}, shownStyle, withTime); + } else if (reading.form != DateForm::Unreadable) { + text = dateText(reading.instant, shownStyle, withTime); + } + if (!text) { + return mismatch(expr, "the date functions take a date, a timestamp or ISO text, and a style"); + } + return std::move(*text); + } + case FunctionId::DateAdd: + return addToDate(expr, args); + case FunctionId::DateRange: + return dateRange(expr, args); + case FunctionId::ParseDecimal: { + std::string const* const text = args.at(0).asString(); + std::optional declared; + if (args.size() > 1) { + std::int64_t const* const places = args.at(1).asInt(); + if (places == nullptr || !std::in_range(*places) || + std::cmp_greater(*places, math::kMaxDecimalPlaces)) { + return mismatch(expr, "`parseDecimal` takes text and places from 0 to 18"); + } + declared = static_cast(*places); + } + if (text == nullptr) { + return mismatch(expr, "`parseDecimal` takes text and places from 0 to 18"); + } + // Text that does not spell a number is what an entry holds while it is typed: `null`, not an error. + if (auto parsed = render::parseDecimal(*text, _env->entryFormatting().numeric, declared)) { + return Decimal{*parsed}; + } + return Value{}; + } + case FunctionId::Abs: { + auto const number = numeric(args.front()); + if (!number) { + return mismatch(expr, "`abs` takes a number"); + } + if (!number->value.isNegative()) { + return args.front(); + } + auto magnitude = math::checkedSub(math::Rational{0, number->value.decimalPlaces}, number->value); + if (!magnitude) { + return mismatch(expr, "the result overflows"); + } + return makeNumber(*magnitude, number->integer, number->unit); + } + case FunctionId::Sqrt: + return squareRoot(expr, args); + case FunctionId::Stdev: + case FunctionId::Rsd: + return statistic(expr, args); + case FunctionId::ConcatLists: { + ValueList out; + for (Value const& arg : args) { + ValueList const* const items = arg.asList(); + if (items == nullptr) { + return mismatch(expr, "`concatLists` takes lists"); + } + out.insert(out.end(), items->begin(), items->end()); + } + return out; + } + case FunctionId::Slice: + return sliced(expr, args); + case FunctionId::RefusalText: + return refusalText(expr, args.front()); + case FunctionId::Translate: + if (args.at(0).asString() == nullptr || args.at(1).asString() == nullptr) { + return mismatch(expr, "`t` takes a key and a fallback string"); + } + return translate(expr, args); + case FunctionId::And: + case FunctionId::Or: + case FunctionId::Coalesce: + case FunctionId::Engaged: + default: + return Value{}; + } + } +#if defined(__GNUC__) && !defined(__clang__) +#pragma GCC diagnostic pop +#endif + + Environment const* _env; + std::vector> _locals; + // The mismatches reported so far, so a form can tell that an operand failed rather than gave `null`. + std::size_t _mismatches = 0; + // NOLINTEND(misc-no-recursion) +}; + +} // namespace + +std::expected, std::string> splitPath(std::string_view text) { + std::vector segments; + std::size_t start = 0; + for (;;) { + std::size_t const dot = text.find('.', start); + std::string_view const segment = + text.substr(start, dot == std::string_view::npos ? std::string_view::npos : dot - start); + if (segment.empty()) { + return std::unexpected("`" + std::string{text} + "` has an empty segment"); + } + segments.emplace_back(segment); + if (dot == std::string_view::npos) { + return segments; + } + start = dot + 1; + } +} + +std::expected typeAlong(Type const& type, std::string_view head, + std::span path) { + if (path.empty()) { + return type; + } + if (type.kind == TypeKind::Any || type.kind == TypeKind::Record || type.kind == TypeKind::List) { + return Type::any(); + } + return std::unexpected("`" + std::string{head} + "` is " + type.name() + " and has no field `" + path.front() + + "`"); +} + +std::optional numeric(Value const& value) { + if (std::int64_t const* const whole = value.asInt()) { + return Number{.value = math::Rational{*whole, math::DecimalPlaces{0}}, .integer = true, .unit = nullptr}; + } + if (Decimal const* const decimal = value.asDecimal()) { + return Number{.value = decimal->value, .integer = false, .unit = nullptr}; + } + if (Quantity const* const quantity = value.asQuantity()) { + return Number{.value = quantity->value, .integer = false, .unit = &quantity->unit}; + } + return std::nullopt; +} + +std::optional convertUnit(math::Rational const& value, std::string_view from, std::string_view target, + UnitTable const& units) { + if (from == target) { + return value; + } + auto const factor = [&units](std::string_view unit) { + auto const found = units.find(unit); + if (found == units.end()) { + return std::pair{std::string{unit}, math::Rational{1, math::DecimalPlaces{0}}}; + } + return std::pair{found->second.canonical, found->second.toCanonical}; + }; + auto const [fromBase, fromFactor] = factor(from); + auto const [toBase, toFactor] = factor(target); + if (fromBase != toBase) { + return std::nullopt; + } + auto const ratio = + math::checkedDiv(math::Rational{math::Numerator{fromFactor.numerator}, + math::Denominator{fromFactor.denominator}, math::DecimalPlaces{0}}, + math::Rational{math::Numerator{toFactor.numerator}, math::Denominator{toFactor.denominator}, + math::DecimalPlaces{0}}); + if (!ratio) { + return std::nullopt; + } + auto converted = math::checkedMul(value, *ratio); + if (!converted) { + return std::nullopt; + } + // The places widen by the ratio's own decimal places, so 1500 mg shows as 1.500 g rather than rounding to 2 g; + // a ratio that is not a terminating decimal adds none. + auto denominator = static_cast(ratio->denominator); + std::uint32_t twos = 0; + std::uint32_t fives = 0; + for (; denominator % 2U == 0; denominator /= 2U) { + ++twos; + } + for (; denominator % 5U == 0; denominator /= 5U) { + ++fives; + } + std::uint32_t const extra = denominator == 1 ? std::max(twos, fives) : 0U; + converted->decimalPlaces = + math::DecimalPlaces{std::min(value.decimalPlaces.value + extra, math::kMaxDecimalPlaces)}; + return *converted; +} + +std::string unitDisplay(std::string const& unit, UnitTable const& units) { + auto const found = units.find(unit); + return found == units.end() || found->second.display.empty() ? unit : found->second.display; +} + +struct Evaluator::Impl { + explicit Impl(Environment const& env) : core{env} {} + EvaluatorCore core; +}; + +Evaluator::Evaluator(Environment const& env) : _impl{std::make_unique(env)} {} + +Evaluator::~Evaluator() = default; + +Value Evaluator::eval(Expr const& expr) { return _impl->core.eval(expr); } + +std::optional Evaluator::sortOrder(Value const& lhs, Value const& rhs) { + return _impl->core.sortOrder(lhs, rhs); +} + +std::optional> Evaluator::sortRows(std::vector> const& keys, + std::vector const& descending) { + return _impl->core.sortRows(keys, descending); +} + +bool Evaluator::sameRun(Value const& lhs, Value const& rhs) { return _impl->core.sameRun(lhs, rhs); } + +} // namespace detail + +Value runRecord(Value key, ValueList items) { + ValueRecord record; + record.insert_or_assign("key", std::move(key)); + record.insert_or_assign("count", static_cast(items.size())); + record.insert_or_assign("first", items.front()); + record.insert_or_assign("last", items.back()); + record.insert_or_assign("items", Value{std::move(items)}); + return Value{std::move(record)}; +} + +std::expected parseExpression(Json const& json, std::string const& path) { + return detail::ExprParser{}.parse(json, path); +} + +std::vector functionNames() { + std::vector names; + names.reserve(detail::kFunctions.size()); + for (auto const& spec : detail::kFunctions) { + names.push_back(spec.name); + } + return names; +} + +std::expected checkExpression(Expr const& expr, NameResolver const& resolver) { + return detail::ExprChecker{resolver}.check(expr); +} + +Value walk(Value const& value, std::span path) { + Value const* current = &value; + for (std::string const& segment : path) { + if (ValueList const* const items = current->asList()) { + // A segment past the largest index is out of range, not wrapped onto an element that exists. + std::size_t index = 0; + char const* const end = std::to_address(segment.end()); + auto const [stop, error] = std::from_chars(std::to_address(segment.begin()), end, index); + if (error != std::errc{} || stop != end || index >= items->size()) { + return Value{}; + } + current = &items->at(index); + continue; + } + current = current->field(segment); + if (current == nullptr) { + return Value{}; + } + } + return *current; +} + +DateValue readDateValue(Value const& value) { + if (value.isNull()) { + return {}; + } + if (time::DateTime const* const instant = value.asTimestamp()) { + return {.form = DateForm::Timestamp, .date = {}, .instant = *instant}; + } + std::string const* const text = value.asString(); + if (text == nullptr) { + return {.form = DateForm::Unreadable, .date = {}, .instant = {}}; + } + if (text->empty()) { + return {}; + } + if (text->size() == 10 && text->at(4) == '-' && text->at(7) == '-') { + auto const field = [&text](std::size_t offset, std::size_t count) -> std::optional { + unsigned parsed = 0; + std::string_view const digits = std::string_view{*text}.substr(offset, count); + char const* const end = std::to_address(digits.end()); + auto const [stop, error] = std::from_chars(std::to_address(digits.begin()), end, parsed); + if (error != std::errc{} || stop != end) { + return std::nullopt; + } + return parsed; + }; + auto const year = field(0, 4); + auto const month = field(5, 2); + auto const day = field(8, 2); + if (year && month && day) { + std::chrono::year_month_day const date{std::chrono::year{static_cast(*year)}, + std::chrono::month{*month}, std::chrono::day{*day}}; + if (date.ok()) { + return {.form = DateForm::Date, .date = date, .instant = {}}; + } + return {.form = DateForm::Unreadable, .date = {}, .instant = {}}; + } + } + if (auto const parsed = time::DateTime::fromIso8601(*text)) { + return {.form = DateForm::InstantText, .date = {}, .instant = *parsed}; + } + return {.form = DateForm::Unreadable, .date = {}, .instant = {}}; +} + +Value evaluate(Expr const& expr, Environment const& env) { return detail::EvaluatorCore{env}.eval(expr); } + +Value StaticEnvironment::control(ExprKind form, std::string_view name) const { + if (form == ExprKind::Pending) { + return pendingNames.contains(name); + } + if (form == ExprKind::Can) { + return permitted.contains(name); + } + if (form == ExprKind::Error) { + return lookup(errors, name, {}); + } + if (form == ExprKind::ErrorKind) { + return lookup(errorKinds, name, {}); + } + if (form == ExprKind::Refusal) { + return lookup(refusals, name, {}); + } + return lookup(form == ExprKind::Result ? results : queries, name, {}); +} + +void StaticEnvironment::report(std::string_view path, std::string_view reason) const { + for (Refusal const& seen : diagnostics) { + if (seen.path == path) { + return; + } + } + diagnostics.push_back(Refusal{.document = {}, .path = std::string{path}, .reason = std::string{reason}}); +} + +} // namespace morph::ui From 998f461f7f093a0e72c3bda3daacd00e955d6487 Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 01:23:48 +0100 Subject: [PATCH 08/38] Move the UI service's non-template code into src/ui/service.cpp UiRegistry's and UiService's member bodies of two or more lines move to the compiled library, and both classes carry MORPH_API. The `detail` helpers (checkServable, checkEntry, DocumentActions, permitsAll) have no user outside the moved bodies, so they live in the .cpp's unnamed namespace. UiService's screenAdmits is declared in the header and defined in the .cpp, because it calls one of them. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- CMakeLists.txt | 1 + include/morph/ui/service.hpp | 917 ++------------------------------- src/ui/service.cpp | 960 +++++++++++++++++++++++++++++++++++ 3 files changed, 1003 insertions(+), 875 deletions(-) create mode 100644 src/ui/service.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 6514fcc3d..fd4d2ebfb 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -416,6 +416,7 @@ add_library(morph STATIC src/ui/expression.cpp src/ui/interpreter.cpp src/ui/library.cpp + src/ui/service.cpp ) add_library(morph::morph ALIAS morph) diff --git a/include/morph/ui/service.hpp b/include/morph/ui/service.hpp index 1bacd5df7..85dbbbdc5 100644 --- a/include/morph/ui/service.hpp +++ b/include/morph/ui/service.hpp @@ -9,6 +9,7 @@ #include #include #include +#include #include #include #include @@ -127,145 +128,6 @@ struct ServedBundle { std::optional>> wizards; }; -namespace detail { - -/// @brief Whether @p bytes can be served: within `kMaxFileBytes`, and within the envelope bound once escaped into -/// an `ok` reply. -/// @param bytes The file. -/// @return Why it cannot, or nothing. -[[nodiscard]] inline std::optional checkServable(std::string const& bytes) { - if (bytes.size() > kMaxFileBytes) { - return "the file is larger than " + std::to_string(kMaxFileBytes) + " bytes"; - } - if (::morph::wire::encode(::morph::wire::makeOk(0, bytes)).size() > ::morph::wire::kMaxEnvelopeBytes) { - return std::string{"the file does not fit one envelope once escaped"}; - } - return std::nullopt; -} - -/// @brief Checks a catalog entry's own fields. -/// @param entry The entry. -/// @return Why it is refused, or nothing. -[[nodiscard]] inline std::optional checkEntry(CatalogEntry const& entry) { - if (entry.id.empty()) { - return std::string{"a catalog entry has an id"}; - } - if (auto reason = checkName(entry.id, "a catalog entry id")) { - return reason; - } - if (entry.whenDenied != "hide" && entry.whenDenied != "disable") { - return "`whenDenied` is `hide` or `disable`, not `" + entry.whenDenied + "`"; - } - return std::nullopt; -} - -// NOLINTBEGIN(misc-no-recursion): view nodes nest, and the walk follows them; parseJson bounds the depth at 64. - -/// @brief Collects the actions and model types a loaded document names, resolving each query's, mutation's and -/// model-bound node's alias through the enclosing scopes. -/// -/// Load-time validation has already resolved every alias and requires every alias to name a type, so each lookup -/// here finds one. -class DocumentActions { -public: - /// @brief Walks @p document. - /// @param document The loaded document. - explicit DocumentActions(Document const& document) { - enter(document.scope, true); - if (document.view) { - node(*document.view); - } - } - - /// @brief The top-level queries. - /// @return Them, in declaration order. - [[nodiscard]] std::vector const& topQueries() const noexcept { return _top; } - - /// @brief Every action named. - /// @return Them, sorted and unique. - [[nodiscard]] std::vector actions() const { return {_all.begin(), _all.end()}; } - - /// @brief Every model type named. - /// @return Them, sorted and unique. - [[nodiscard]] std::vector modelTypes() const { return {_models.begin(), _models.end()}; } - -private: - void enter(ScopeDecl const& scope, bool top) { - for (ModelDecl const& model : scope.models) { - _types.try_emplace(model.name).first->second.push_back(model.type); - _models.insert(model.type); - } - for (QueryDecl const& query : scope.queries) { - ActionRef ref{.modelType = resolve(query.model), .action = query.action}; - if (top) { - _top.push_back(ref); - } - _all.insert(std::move(ref)); - } - for (MutationDecl const& mutation : scope.mutations) { - _all.insert(ActionRef{.modelType = resolve(mutation.model), .action = mutation.action}); - } - } - - void leave(ScopeDecl const& scope) { - for (ModelDecl const& model : scope.models) { - _types.at(model.name).pop_back(); - } - } - - void node(DocNode const& view) { - if (view.scope) { - enter(*view.scope, false); - } - if (std::string_view const model = view.name("model"); !model.empty()) { - _all.insert(ActionRef{.modelType = resolve(model), .action = std::string{view.name("action")}}); - } - for (auto const& [key, children] : view.children) { - static_cast(key); - for (DocNodePtr const& child : children) { - node(*child); - } - } - for (auto const& [key, parts] : view.parts) { - static_cast(key); - for (DocNodePtr const& part : parts) { - node(*part); - } - } - if (view.scope) { - leave(*view.scope); - } - } - - /// @brief The type of the innermost alias named @p alias. Load-time validation has resolved it already, so the - /// lookup cannot miss; `at` throws rather than read past the end if that ever changes. - [[nodiscard]] std::string const& resolve(std::string_view alias) const { - std::vector const& types = _types.at(std::string{alias}); - return types.at(types.size() - 1); - } - - /// @brief The types an alias names in the open scopes, innermost last. - std::map, std::less<>> _types; - std::vector _top; - std::set _all; - std::set _models; -}; - -// NOLINTEND(misc-no-recursion) - -/// @brief Whether the principal of @p session may run every action of @p refs. -/// @param authorizer The authoriser. -/// @param session The session, its principal verified. -/// @param refs The actions. -/// @return Whether it may run all of them; `true` for none. -[[nodiscard]] inline bool permitsAll(::morph::session::IAuthorizer const& authorizer, - ::morph::session::Context const& session, std::vector const& refs) { - return std::ranges::all_of( - refs, [&](ActionRef const& ref) { return authorizer.authorize(session, ref.modelType, ref.action); }); -} - -} // namespace detail - /// @brief A file of the bundle that is not a screen, as `UiRegistry::addFile` takes it. struct BundleFile { /// @brief `app`, `theme`, `messages`, `component` or `icon`. @@ -283,7 +145,7 @@ struct BundleFile { /// Built once, before the service answers anything; `build` copies everything into an immutable `ServedBundle`. /// A screen authored with the C++ builders is added by its emitted text, so an authoring registry feeds this one /// through `addScreen` without either depending on the other. -class UiRegistry { +class MORPH_API UiRegistry { public: /// @brief An empty registry. /// @param application The application `ui-hello` names. @@ -302,17 +164,7 @@ class UiRegistry { /// @param entry The catalog entry. /// @param text The document's JSON text, served byte for byte. /// @return Nothing, or the refusal. - std::expected addScreen(CatalogEntry entry, std::string text) { - std::string const screenId = entry.id; - std::size_t const size = text.size(); - auto added = addScreenImpl(std::move(entry), std::move(text)); - if (added) { - ::morph::log::logDebug("[ui-serve] added the screen `{}` ({} bytes)", screenId, size); - } else { - ::morph::log::logWarn("[ui-serve] refused a screen: {}", added.error().message()); - } - return added; - } + std::expected addScreen(CatalogEntry entry, std::string text); /// @brief Lists an entry that has no document: a host screen (`host`), or one the application has not built /// (`available: false`). @@ -320,16 +172,7 @@ class UiRegistry { /// Refused on the same entry rules as `addScreen`, and when the entry is neither a host screen nor unavailable. /// @param entry The catalog entry. /// @return Nothing, or the refusal. - std::expected addEntry(CatalogEntry entry) { - std::string const entryId = entry.id; - auto added = addEntryImpl(std::move(entry)); - if (added) { - ::morph::log::logDebug("[ui-serve] added the entry `{}`", entryId); - } else { - ::morph::log::logWarn("[ui-serve] refused an entry: {}", added.error().message()); - } - return added; - } + std::expected addEntry(CatalogEntry entry); /// @brief Adds a file that is not a screen: the app document (`app`, whose id is `app`), a theme (`theme`), a /// message catalogue (`messages`), a delivered component (`component`) or an icon (`icon`). @@ -341,18 +184,7 @@ class UiRegistry { /// icon that is not SVG text or is larger than `kMaxIconBytes`. /// @param file The file. /// @return Nothing, or the refusal. - std::expected addFile(BundleFile file) { - std::string const kind = file.kind; - std::string const fileId = file.id; - std::size_t const size = file.bytes.size(); - auto added = addFileImpl(std::move(file)); - if (added) { - ::morph::log::logDebug("[ui-serve] added the {} `{}` ({} bytes)", kind, fileId, size); - } else { - ::morph::log::logWarn("[ui-serve] refused a file: {}", added.error().message()); - } - return added; - } + std::expected addFile(BundleFile file); /// @brief Declares the shell's parts (`docs/spec/ui/shell_parts.md`): a scope switcher, /// module counts, search, an inbox and the person's menu. They are written into the app document's `shell` @@ -372,24 +204,7 @@ class UiRegistry { /// @param reads The facts of the models and actions the parts read; their lookups are consulted after the /// registry's own. Empty: the parts read only what a screen already names. /// @return Nothing, or the refusal. - std::expected setShellParts(ShellParts parts, Catalog reads = {}) { - // A refused call leaves the parts and the catalog as they were, so the next app document is not judged by - // them. - Catalog previousCatalog = _catalog; - std::optional previous = std::exchange(_shellParts, std::move(parts)); - _catalog = withReads(_baseCatalog, std::move(reads)); - std::expected outcome = [&]() -> std::expected { - if (auto named = checkShellNames()) { - return std::unexpected(std::move(*named)); - } - return applyShellParts(previous.has_value()); - }(); - if (!outcome) { - _shellParts = std::move(previous); - _catalog = std::move(previousCatalog); - } - return outcome; - } + std::expected setShellParts(ShellParts parts, Catalog reads = {}); /// @brief Adds a vocabulary the bundle needs beyond `ui/1` and `expr/1`, such as `forms/1` or `files/1`. A /// client that does not speak it is refused at `ui-hello`. @@ -403,179 +218,37 @@ class UiRegistry { /// vocabularies or a vocabulary name longer than `kMaxNameBytes`. A theme file's token that nothing reads is /// logged at warn and does not refuse the build. /// @return The bundle, or the refusal. - [[nodiscard]] std::expected, Refusal> build() const { - auto built = buildImpl(); - if (built) { - logThemeProblems(); - ::morph::log::logDebug("[ui-serve] built the bundle of `{}`: {} files, digest {}", _application.id, - (*built)->files.size(), (*built)->digest); - } else { - ::morph::log::logWarn("[ui-serve] refused to build: {}", built.error().message()); - } - return built; - } + [[nodiscard]] std::expected, Refusal> build() const; private: /// @brief Logs, at warn, what each theme index's files hold that nothing reads or that cannot be read /// (`themeProblems`); the bundle is still built. - void logThemeProblems() const { - TokenFileLookup const lookup = [this](std::string_view fileId) -> TokenSet const* { - auto const found = _tokenFiles.find(fileId); - return found == _tokenFiles.end() ? nullptr : &found->second; - }; - for (auto const& [indexId, index] : _themeIndexes) { - for (std::string const& problem : themeProblems(index, lookup)) { - ::morph::log::logWarn("[ui-serve] theme {}: {}", indexId, problem); - } - } - } + void logThemeProblems() const; /// @brief Registers a screen; the public `addScreen` logs its outcome. /// @param entry The catalog entry. /// @param text The document's JSON text. /// @return Nothing, or the refusal. - std::expected addScreenImpl(CatalogEntry entry, std::string text) { - if (auto refusal = checkNewEntry(entry)) { - return std::unexpected(std::move(*refusal)); - } - if (entry.host) { - return refuse(entry.id, "a host screen has no document; it is added with addEntry"); - } - if (auto reason = detail::checkServable(text)) { - return refuse(entry.id, std::move(*reason)); - } - auto loaded = loadDocumentText(text, LoadOptions{.catalog = _catalog}); - if (!loaded) { - return std::unexpected(std::move(loaded.error())); - } - if (loaded->id != entry.id) { - return refuse(entry.id, "the entry's id is not the document's id `" + loaded->id + "`"); - } - if (!loaded->view) { - return refuse(entry.id, "the app document is added with addFile"); - } - logWarnings(*loaded); - detail::DocumentActions const named{*loaded}; - Screen screen{.served = ServedScreen{.entry = std::move(entry), - .hash = contentHash(text), - .topQueries = named.topQueries(), - .actions = named.actions(), - .modelTypes = named.modelTypes()}, - .text = std::move(text), - .components = {}}; - for (auto const& [name, component] : loaded->components) { - static_cast(name); - if (!component.qml.empty()) { - screen.components.emplace_back(pointerAppend(component.path, "qml"), component.qml); - } - } - _screens.push_back(std::move(screen)); - return {}; - } + std::expected addScreenImpl(CatalogEntry entry, std::string text); /// @brief Registers an entry that has no document; the public `addEntry` logs its outcome. /// @param entry The catalog entry. /// @return Nothing, or the refusal. - std::expected addEntryImpl(CatalogEntry entry) { - if (auto refusal = checkNewEntry(entry)) { - return std::unexpected(std::move(*refusal)); - } - if (!entry.host && entry.available) { - return refuse(entry.id, "an entry without a document is a host screen or unavailable"); - } - _screens.push_back(Screen{ - .served = - ServedScreen{.entry = std::move(entry), .hash = {}, .topQueries = {}, .actions = {}, .modelTypes = {}}, - .text = {}, - .components = {}}); - return {}; - } + std::expected addEntryImpl(CatalogEntry entry); /// @brief Adds a file; the public `addFile` logs its outcome. /// @param file The file. /// @return Nothing, or the refusal. - std::expected addFileImpl(BundleFile file) { - if (file.kind != kAppFile && file.kind != kThemeFile && file.kind != kMessagesFile && - file.kind != kComponentFile && file.kind != kIconFile) { - return refuse(file.id, - "a file is an app document, a theme, a message catalogue, a component or an icon, " - "not `" + - file.kind + "`"); - } - if (file.id.empty()) { - return refuse(file.id, "a file has an id"); - } - if (auto reason = detail::checkName(file.id, "a file id")) { - return refuse(file.id, std::move(*reason)); - } - if (file.kind == kAppFile && _appSynthesised) { - // The app document `setShellParts` made stands in until the application adds its own. - std::erase_if(_files, [](BundleFile const& held) { return held.kind == kAppFile; }); - _appSynthesised = false; - } - if (std::ranges::any_of( - _files, [&file](BundleFile const& added) { return added.kind == file.kind && added.id == file.id; })) { - return refuse(file.id, "the " + file.kind + " `" + file.id + "` is already added"); - } - if (auto reason = detail::checkServable(file.bytes)) { - return refuse(file.id, std::move(*reason)); - } - if (file.kind == kAppFile && _shellParts) { - auto patched = withShellParts(std::move(file), false); - if (!patched) { - return std::unexpected(std::move(patched.error())); - } - file = std::move(*patched); - } - if (auto added = addKind(file); !added) { - return added; - } - _files.push_back(std::move(file)); - return {}; - } + std::expected addFileImpl(BundleFile file); /// @brief Builds the bundle; the public `build` logs its outcome. /// @return The bundle, or the refusal. - [[nodiscard]] std::expected, Refusal> buildImpl() const { - if (auto refusal = checkBuildable()) { - return std::unexpected(std::move(*refusal)); - } - auto bundle = std::make_shared(); - bundle->application = _application; - bundle->vocabularies.assign(_vocabularies.begin(), _vocabularies.end()); - bundle->appActions = _appActions; - bundle->appModelTypes = _appModelTypes; - serveFiles(*bundle); - addFacts(*bundle); - return bundle; - } + [[nodiscard]] std::expected, Refusal> buildImpl() const; /// @brief Checks every theme index: each combination of its variants, densities and surfaces over `base` /// resolves from the bundle's token files (`checkTheme`). /// @return The refusal, naming the index and the combination, or nothing. - [[nodiscard]] std::optional checkThemes() const { - TokenFileLookup const lookup = [this](std::string_view fileId) -> TokenSet const* { - auto const found = _tokenFiles.find(fileId); - return found == _tokenFiles.end() ? nullptr : &found->second; - }; - for (auto const& [indexId, index] : _themeIndexes) { - if (auto reason = checkTheme(index, lookup)) { - return Refusal{.document = indexId, .path = {}, .reason = "the theme: " + std::move(*reason)}; - } - for (auto const& [name, fileId] : index.icons) { - bool const held = std::ranges::any_of( - _files, [&fileId](BundleFile const& file) { return file.kind == kIconFile && file.id == fileId; }); - if (!held) { - return Refusal{.document = indexId, - .path = {}, - .reason = std::format("the theme index names the icon `{}` as `{}`, which is not " - "an icon file of the bundle", - name, fileId)}; - } - } - } - return std::nullopt; - } + [[nodiscard]] std::optional checkThemes() const; /// @brief A registered screen and what `build` needs of its document. struct Screen { @@ -588,135 +261,28 @@ class UiRegistry { }; // The checks and the indexing one kind of file adds to addFile's common ones. - std::expected addKind(BundleFile const& file) { - if (file.kind == kMessagesFile) { - return checkCatalogue(file); - } - if (file.kind == kThemeFile) { - return addTheme(file); - } - if (file.kind == kAppFile) { - return addApp(file); - } - if (file.kind == kIconFile) { - return checkIcon(file); - } - return {}; - } + std::expected addKind(BundleFile const& file); // An icon is SVG text, small enough for a theme to carry a set of them. - [[nodiscard]] static std::expected checkIcon(BundleFile const& file) { - if (file.bytes.size() > kMaxIconBytes) { - return refuse(file.id, std::format("an icon is at most {} bytes of SVG; this one is {}", kMaxIconBytes, - file.bytes.size())); - } - if (!file.bytes.contains(" element"); - } - return {}; - } + [[nodiscard]] static std::expected checkIcon(BundleFile const& file); - [[nodiscard]] static std::expected checkCatalogue(BundleFile const& file) { - if (!catalogueLocale(file.id)) { - return refuse(file.id, "a message catalogue's id is i18n/.json"); - } - auto catalogue = parseCatalogue(file.bytes); - if (!catalogue) { - return refuse(file.id, std::move(catalogue.error())); - } - if (!catalogue->dropped.empty()) { - return refuse(file.id, "a message is outside the ui/1 subset: " + catalogue->dropped.front()); - } - return {}; - } + [[nodiscard]] static std::expected checkCatalogue(BundleFile const& file); - std::expected addTheme(BundleFile const& file) { - if (isThemeIndex(file.bytes)) { - auto index = parseThemeIndex(file.bytes); - if (!index) { - return refuse(file.id, "the theme index: " + index.error()); - } - _themeIndexes.emplace_back(file.id, std::move(*index)); - return {}; - } - auto tokens = parseTokens(file.bytes); - if (!tokens) { - return refuse(file.id, "the token file: " + tokens.error()); - } - _tokenFiles.emplace(file.id, std::move(*tokens)); - return {}; - } + std::expected addTheme(BundleFile const& file); // Writes `_shellParts` into the app document, or into a synthesised one. @p replace says the app document may // already hold parts this registry wrote. - std::expected applyShellParts(bool replace) { - auto found = std::ranges::find_if(_files, [](BundleFile const& file) { return file.kind == kAppFile; }); - if (found == _files.end()) { - BundleFile file{.kind = std::string{kAppFile}, - .id = std::string{kAppFile}, - .bytes = R"({"vocab":"ui/1","id":"app"})", - .isPublic = true}; - auto patched = withShellParts(std::move(file), false); - if (!patched) { - return std::unexpected(std::move(patched.error())); - } - if (auto added = addApp(*patched); !added) { - return added; - } - _files.push_back(std::move(*patched)); - _appSynthesised = true; - return {}; - } - auto patched = withShellParts(*found, replace); - if (!patched) { - return std::unexpected(std::move(patched.error())); - } - if (auto added = addApp(*patched); !added) { - return added; - } - *found = std::move(*patched); - return {}; - } + std::expected applyShellParts(bool replace); // The app document with the shell's parts written into its `shell` member. A document that already declares // `shell` is refused unless @p replace says the registry wrote it. - [[nodiscard]] std::expected withShellParts(BundleFile file, bool replace) const { - auto document = parseJson(file.bytes); - auto* const object = document ? std::get_if(&document->data) : nullptr; - auto shell = parseJson(glz::write_json(*_shellParts).value_or("{}")); - if (object == nullptr || !shell) { - return refuse(file.id, "the app document is a JSON object"); - } - if (!replace && object->contains("shell")) { - return refuse(file.id, "the app document declares its own `shell`, and the registry was given parts too"); - } - object->insert_or_assign("shell", std::move(*shell)); - file.bytes = glz::write_json(*document).value_or(file.bytes); - return file; - } + [[nodiscard]] std::expected withShellParts(BundleFile file, bool replace) const; - std::expected addApp(BundleFile const& file) { - auto loaded = loadDocumentText(file.bytes, LoadOptions{.catalog = _catalog}); - if (!loaded) { - return std::unexpected(std::move(loaded.error())); - } - if (loaded->id != kAppFile) { - return refuse(file.id, "the app document's id is `app`"); - } - logWarnings(*loaded); - detail::DocumentActions const named{*loaded}; - _appActions = named.actions(); - _appModelTypes = named.modelTypes(); - return {}; - } + std::expected addApp(BundleFile const& file); /// @brief Logs what load-time validation found in @p document that does not refuse it. /// @param document The loaded document. - static void logWarnings(Document const& document) { - for (LoadWarning const& warning : document.warnings) { - morph::log::logWarn(warning.message(document.id)); - } - } + static void logWarnings(Document const& document); /// @brief A refusal of the registration of @p document. /// @param document The screen or file id. @@ -730,190 +296,32 @@ class UiRegistry { /// @brief Checks an entry about to be registered: its own fields, and that its id is new. /// @param entry The entry. /// @return The refusal, or nothing. - [[nodiscard]] std::optional checkNewEntry(CatalogEntry const& entry) const { - if (auto reason = detail::checkEntry(entry)) { - return Refusal{.document = entry.id, .path = {}, .reason = std::move(*reason)}; - } - if (std::ranges::any_of(_screens, [&](Screen const& screen) { return screen.served.entry.id == entry.id; })) { - return Refusal{.document = entry.id, .path = {}, .reason = "a catalog entry with this id is registered"}; - } - return std::nullopt; - } + [[nodiscard]] std::optional checkNewEntry(CatalogEntry const& entry) const; /// @brief @p base with the model and action lookups of @p reads behind its own. /// @param base The catalog held. /// @param reads The facts to add. /// @return The catalog that answers from @p base first and from @p reads where @p base does not know. - [[nodiscard]] static Catalog withReads(Catalog base, Catalog reads) { - if (reads.model) { - base.model = [first = std::move(base.model), - second = std::move(reads.model)](std::string_view typeId) -> std::optional { - auto found = first ? first(typeId) : std::nullopt; - return found ? found : second(typeId); - }; - } - if (reads.action) { - base.action = [first = std::move(base.action), - second = std::move(reads.action)](std::string_view actionId) -> std::optional { - auto found = first ? first(actionId) : std::nullopt; - return found ? found : second(actionId); - }; - } - return base; - } + [[nodiscard]] static Catalog withReads(Catalog base, Catalog reads); /// @brief Checks the modules and screens the shell's parts name against every screen registered. /// /// An action a part names is checked by the app document's load, against the catalog. /// @return The refusal for the first name no screen has, or nothing. - [[nodiscard]] std::optional checkShellNames() const { - if (!_shellParts) { - return std::nullopt; - } - auto const hasModule = [this](std::string const& module) { - return module.empty() || std::ranges::any_of(_screens, [&module](Screen const& screen) { - return screen.served.entry.module == module; - }); - }; - auto const hasScreen = [this](std::string const& id) { - return std::ranges::any_of(_screens, [&id](Screen const& screen) { return screen.served.entry.id == id; }); - }; - auto const unknown = [](std::string path, std::string const& kind, std::string const& name) { - return Refusal{ - .document = std::string{kAppFile}, - .path = std::move(path), - .reason = "the shell names the " + kind + " `" + name + "`, which no screen registered has"}; - }; - for (std::size_t index = 0; index < _shellParts->modules.size(); ++index) { - if (auto const& module = _shellParts->modules.at(index).module; !hasModule(module)) { - return unknown("/shell/modules/" + std::to_string(index) + "/module", "module", module); - } - } - for (std::size_t index = 0; index < _shellParts->search.size(); ++index) { - if (auto const& module = _shellParts->search.at(index).module; !hasModule(module)) { - return unknown("/shell/search/" + std::to_string(index) + "/module", "module", module); - } - } - if (_shellParts->inbox && !hasScreen(_shellParts->inbox->screen)) { - return unknown("/shell/inbox/screen", "screen", _shellParts->inbox->screen); - } - if (_shellParts->help && !_shellParts->help->screen.empty() && !hasScreen(_shellParts->help->screen)) { - return unknown("/shell/help/screen", "screen", _shellParts->help->screen); - } - return std::nullopt; - } + [[nodiscard]] std::optional checkShellNames() const; /// @brief What `build` refuses: a delivered component missing from the bundle, a theme some combination of which /// does not resolve, and the bounds. /// @return The refusal, or nothing. - [[nodiscard]] std::optional checkBuildable() const { - if (auto refusal = checkThemes()) { - return refusal; - } - std::set> componentHashes; - for (BundleFile const& file : _files) { - if (file.kind == kComponentFile) { - componentHashes.insert(contentHash(file.bytes)); - } - } - for (Screen const& screen : _screens) { - for (auto const& [path, hash] : screen.components) { - if (!componentHashes.contains(hash)) { - return Refusal{.document = screen.served.entry.id, - .path = path, - .reason = "the delivered component is not in the bundle"}; - } - } - } - if (_screens.size() > kMaxBundleFiles || _screens.size() + _files.size() > kMaxBundleFiles) { - return Refusal{ - .document = {}, - .path = {}, - .reason = "the bundle holds more than " + std::to_string(kMaxBundleFiles) + " files or entries"}; - } - std::vector const vocabularies{_vocabularies.begin(), _vocabularies.end()}; - if (auto reason = detail::checkNames(vocabularies, kMaxListItems, "the vocabularies", "a vocabulary")) { - return Refusal{.document = {}, .path = {}, .reason = std::move(*reason)}; - } - return std::nullopt; - } + [[nodiscard]] std::optional checkBuildable() const; /// @brief Fills @p bundle's screens, files, manifest and digest. /// @param bundle The bundle being built. - void serveFiles(ServedBundle& bundle) const { - Manifest manifest{.application = _application.id, .version = _application.version, .files = {}}; - auto serve = [&bundle, &manifest](BundleFile const& file, std::optional screen) { - std::string const hash = contentHash(file.bytes); - manifest.files.push_back(ManifestFile{ - .id = file.id, .kind = file.kind, .hash = hash, .size = file.bytes.size(), .isPublic = file.isPublic}); - ServedFile& served = bundle.files.try_emplace(hash).first->second; - served.bytes = file.bytes; - served.holders.push_back( - ServedFile::Holder{.kind = file.kind, .id = file.id, .isPublic = file.isPublic, .screen = screen}); - }; - for (Screen const& screen : _screens) { - if (!screen.served.hash.empty()) { - serve(BundleFile{.kind = std::string{kScreenFile}, - .id = screen.served.entry.id, - .bytes = screen.text, - .isPublic = screen.served.entry.isPublic}, - bundle.screens.size()); - } - bundle.screens.push_back(screen.served); - } - for (BundleFile const& file : _files) { - serve(file, std::nullopt); - } - std::ranges::sort(manifest.files, [](ManifestFile const& lhs, ManifestFile const& rhs) { - return std::tie(lhs.kind, lhs.id) < std::tie(rhs.kind, rhs.id); - }); - bundle.manifest = manifestText(manifest); - bundle.digest = contentHash(bundle.manifest); - bundle.files.insert_or_assign( - bundle.digest, - ServedFile{.bytes = bundle.manifest, - .holders = {ServedFile::Holder{ - .kind = "manifest", .id = _application.id, .isPublic = true, .screen = std::nullopt}}}); - } + void serveFiles(ServedBundle& bundle) const; /// @brief Fills @p bundle's action candidates and, from the registry's catalog, its facts. /// @param bundle The bundle being built, its screens already served. - void addFacts(ServedBundle& bundle) const { - std::set all{_appActions.begin(), _appActions.end()}; - std::set> modelTypes{_appModelTypes.begin(), _appModelTypes.end()}; - for (ServedScreen const& screen : bundle.screens) { - all.insert(screen.actions.begin(), screen.actions.end()); - modelTypes.insert(screen.modelTypes.begin(), screen.modelTypes.end()); - } - bundle.allActions.assign(all.begin(), all.end()); - if (_catalog.model) { - auto& known = bundle.models.emplace(); - for (std::string const& type : modelTypes) { - // Load-time validation refused every document naming a type the lookup does not know. - known.emplace(type, _catalog.model(type).value_or(ModelInfo{})); - } - } - if (_catalog.action) { - auto& known = bundle.actions.emplace(); - for (ActionRef const& ref : all) { - // Load-time validation refused every document naming an action the lookup does not know. - known.emplace(ref.action, _catalog.action(ref.action).value_or(ActionInfo{})); - } - } - auto const documents = [&all](auto const& lookup, auto& out) { - if (!lookup) { - return; - } - auto& known = out.emplace(); - for (ActionRef const& ref : all) { - if (std::optional document = lookup(ref.action)) { - known.emplace(ref.action, std::move(*document)); - } - } - }; - documents(_catalog.view, bundle.views); - documents(_catalog.wizard, bundle.wizards); - } + void addFacts(ServedBundle& bundle) const; ApplicationInfo _application; // The catalog given at construction, and the one the registry reads: that one behind the facts of the last @@ -962,7 +370,7 @@ class UiRegistry { /// /// A refusal is `err "unauthorized"`. A request body that is too large, malformed or carries a must-understand key /// is refused with the parser's reason. -class UiService final : public ::morph::backend::IEnvelopeService { +class MORPH_API UiService final : public ::morph::backend::IEnvelopeService { public: /// @brief Serves @p bundle, and evaluates through @p dispatcher. /// @param bundle The bundle; shared, never changed. @@ -973,20 +381,12 @@ class UiService final : public ::morph::backend::IEnvelopeService { explicit UiService(std::shared_ptr bundle, ::morph::model::detail::ActionDispatcher& dispatcher MORPH_LIFETIMEBOUND = ::morph::model::detail::defaultDispatcher(), - std::shared_ptr files = nullptr) - : _bundle{std::move(bundle)}, _dispatcher{&dispatcher}, _files{std::move(files)} { - if (!_bundle) { - throw std::invalid_argument("UiService: the bundle is null"); - } - } + std::shared_ptr files = nullptr); /// @brief Whether @p kind is one of the service's kinds. /// @param kind The envelope kind. /// @return `true` for `ui-hello`, `ui-catalog`, `ui-fetch` and `ui-evaluate`. - [[nodiscard]] bool serves(std::string_view kind) const override { - return kind == kHelloKind || kind == kCatalogKind || kind == kFetchKind || kind == kEvaluateKind || - (kind == kFileKind && _files != nullptr); - } + [[nodiscard]] bool serves(std::string_view kind) const override; /// @brief Answers one request with no connection behind it: a `ui-hello` offer of events is accepted in the /// reply, and recorded nowhere. @@ -994,10 +394,7 @@ class UiService final : public ::morph::backend::IEnvelopeService { /// @param authorizer The server's authoriser. /// @return The encoded reply. [[nodiscard]] std::string handle(::morph::wire::Envelope const& request, - ::morph::session::IAuthorizer const& authorizer) override { - ::morph::backend::ConnectionFacts facts; - return handle(request, authorizer, facts); - } + ::morph::session::IAuthorizer const& authorizer) override; /// @brief Answers one request; a `ui-hello` that offers events and is answered `ok` sets `facts.events`. /// @@ -1009,21 +406,7 @@ class UiService final : public ::morph::backend::IEnvelopeService { /// @return The encoded reply. [[nodiscard]] std::string handle(::morph::wire::Envelope const& request, ::morph::session::IAuthorizer const& authorizer, - ::morph::backend::ConnectionFacts& facts) override { - if (request.kind == kHelloKind) { - return hello(request, authorizer, facts); - } - if (request.kind == kCatalogKind) { - return catalog(request, authorizer); - } - if (request.kind == kEvaluateKind) { - return evaluate(request, authorizer); - } - if (request.kind == kFileKind) { - return file(request, authorizer); - } - return fetch(request, authorizer); - } + ::morph::backend::ConnectionFacts& facts) override; private: /// @brief The model types and actions of the documents a principal may fetch, whose facts the catalog carries. @@ -1062,11 +445,7 @@ class UiService final : public ::morph::backend::IEnvelopeService { /// @return The encoded reply. [[nodiscard]] std::string hello(::morph::wire::Envelope const& request, ::morph::session::IAuthorizer const& authorizer, - ::morph::backend::ConnectionFacts& facts) const { - Answer answer = helloAnswer(request, authorizer, facts); - ::morph::log::logDebug("[ui-hello] `{}`: {}", answer.subject, answer.outcome); - return std::move(answer.encoded); - } + ::morph::backend::ConnectionFacts& facts) const; /// @brief Answers a `ui-hello` without logging it. /// @param request The envelope. @@ -1075,39 +454,7 @@ class UiService final : public ::morph::backend::IEnvelopeService { /// @return The reply and its log fields. [[nodiscard]] Answer helloAnswer(::morph::wire::Envelope const& request, ::morph::session::IAuthorizer const& authorizer, - ::morph::backend::ConnectionFacts& facts) const { - std::string const application = _bundle->application.id; - if (!gate(authorizer, request, kHelloAction)) { - return Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), - .subject = application, - .outcome = "refused: unauthorized"}; - } - auto client = parseHelloRequest(request.body); - if (!client) { - std::string const reason = std::move(client.error()); - return Answer{.encoded = err(request, reason), .subject = application, .outcome = "refused: " + reason}; - } - std::string missing; - for (std::string const& vocabulary : _bundle->vocabularies) { - if (std::ranges::find(client->vocabularies, vocabulary) == client->vocabularies.end()) { - missing += (missing.empty() ? "" : ", ") + vocabulary; - } - } - if (!missing.empty()) { - std::string const reason = "missing vocabulary: " + missing; - return Answer{.encoded = err(request, reason), .subject = application, .outcome = "refused: " + reason}; - } - if (client->events) { - facts.events = true; - } - return Answer{.encoded = ok(request, detail::writeMessage(HelloReply{.application = _bundle->application.id, - .version = _bundle->application.version, - .vocabularies = _bundle->vocabularies, - .digest = _bundle->digest, - .events = client->events})), - .subject = application, - .outcome = "ok, digest " + _bundle->digest}; - } + ::morph::backend::ConnectionFacts& facts) const; /// @brief Evaluates the action body @p request carries (spec 5 §7): decoded, reconciled and recomputed, never /// executed, and answered with its field errors. Synchronous on the server strand, like the other kinds. @@ -1115,20 +462,7 @@ class UiService final : public ::morph::backend::IEnvelopeService { /// @param authorizer The server's authoriser. /// @return The encoded reply: an `EvaluateReply`, or `err` for a refusal or a body that does not decode. [[nodiscard]] std::string evaluate(::morph::wire::Envelope const& request, - ::morph::session::IAuthorizer const& authorizer) const { - if (request.modelType.empty() || request.actionType.empty()) { - return err(request, "ui-evaluate names no modelType and actionType"); - } - if (!authorizer.authorize(request.session, request.modelType, request.actionType)) { - return err(request, std::string{::morph::wire::kUnauthorizedMessage}); - } - auto evaluation = _dispatcher->evaluate(request.modelType, request.actionType, request.body); - EvaluateReply reply{.body = {}, .errors = std::move(evaluation.errors), .ready = evaluation.ready}; - if (auto const error = glz::read_json(reply.body, evaluation.body)) { - return err(request, "ui-evaluate: " + glz::format_error(error, evaluation.body)); - } - return ok(request, detail::writeMessage(reply)); - } + ::morph::session::IAuthorizer const& authorizer) const; /// @brief One step of an upload or a download through the file side channel (spec 6 §18). /// @@ -1139,124 +473,21 @@ class UiService final : public ::morph::backend::IEnvelopeService { /// @param authorizer The server's authoriser. /// @return The encoded reply: a `FileReply`, or `err`. [[nodiscard]] std::string file(::morph::wire::Envelope const& request, - ::morph::session::IAuthorizer const& authorizer) const { - auto parsed = parseFileRequest(request.body); - if (!parsed) { - return err(request, std::move(parsed.error())); - } - FileRequest& step = *parsed; - std::string const& principal = request.session.principal; - auto const refused = [&request](FileError error) { return err(request, std::string{fileErrorText(error)}); }; - FileReply reply; - if (step.op == "begin") { - if (step.model.empty() || step.action.empty()) { - return err(request, "ui-file begin names no model and action"); - } - if (!authorizer.authorize(request.session, step.model, step.action)) { - return err(request, std::string{::morph::wire::kUnauthorizedMessage}); - } - auto upload = _files->begin( - principal, FileInfo{.name = std::move(step.name), .type = std::move(step.type), .size = step.size}); - if (!upload) { - return refused(upload.error()); - } - reply.upload = std::move(*upload); - } else if (step.op == "chunk") { - auto bytes = ::morph::session::detail::base64UrlDecode(step.data); - if (!bytes) { - return err(request, "ui-file chunk data is not base64url"); - } - if (bytes->size() > kMaxFileChunkBytes) { - return err(request, "ui-file chunk is longer than " + std::to_string(kMaxFileChunkBytes) + " bytes"); - } - auto received = _files->append(principal, step.upload, step.offset, *bytes); - if (!received) { - return refused(received.error()); - } - reply.received = *received; - } else if (step.op == "end") { - auto ref = _files->finish(principal, step.upload); - if (!ref) { - return refused(ref.error()); - } - reply.ref = std::move(*ref); - } else { - auto slice = _files->read(principal, step.ref, step.offset, std::min(step.length, kMaxFileChunkBytes)); - if (!slice) { - return refused(slice.error()); - } - reply.data = ::morph::session::detail::base64UrlEncode(slice->bytes); - reply.total = slice->info.size; - reply.name = std::move(slice->info.name); - reply.type = std::move(slice->info.type); - } - return ok(request, detail::writeMessage(reply)); - } + ::morph::session::IAuthorizer const& authorizer) const; /// @brief Answers a `ui-catalog` and logs the outcome at debug. /// @param request The envelope. /// @param authorizer The server's authoriser. /// @return The encoded reply. [[nodiscard]] std::string catalog(::morph::wire::Envelope const& request, - ::morph::session::IAuthorizer const& authorizer) const { - Answer answer = catalogAnswer(request, authorizer); - ::morph::log::logDebug("[ui-catalog] `{}`: {}", answer.subject, answer.outcome); - return std::move(answer.encoded); - } + ::morph::session::IAuthorizer const& authorizer) const; /// @brief Answers a `ui-catalog` without logging it. /// @param request The envelope. /// @param authorizer The server's authoriser. /// @return The reply and its log fields. [[nodiscard]] Answer catalogAnswer(::morph::wire::Envelope const& request, - ::morph::session::IAuthorizer const& authorizer) const { - std::string const application = _bundle->application.id; - if (!gate(authorizer, request, kCatalogAction)) { - return Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), - .subject = application, - .outcome = "refused: unauthorized"}; - } - CatalogReply reply; - Fetchable const fetchable = listEntries(reply, request.session, authorizer); - for (ActionRef const& ref : _bundle->allActions) { - if (authorizer.authorize(request.session, ref.modelType, ref.action)) { - reply.permitted.push_back(ref.action); - } - } - if (_bundle->models) { - auto& known = reply.models.emplace(); - for (auto const& [type, info] : *_bundle->models) { - if (fetchable.modelTypes.contains(type)) { - known.emplace(type, info); - } - } - } - if (_bundle->actions) { - auto& known = reply.actions.emplace(); - for (auto const& [action, info] : *_bundle->actions) { - if (fetchable.actions.contains(action)) { - known.emplace(action, info); - } - } - } - // A collection's or wizard's document goes with the action that names it, to whoever may fetch that action. - auto const documents = [&fetchable](auto const& served, auto& out) { - if (!served) { - return; - } - auto& known = out.emplace(); - for (auto const& [action, document] : *served) { - if (fetchable.actions.contains(action)) { - known.emplace(action, document); - } - } - }; - documents(_bundle->views, reply.views); - documents(_bundle->wizards, reply.wizards); - return Answer{.encoded = ok(request, detail::writeMessage(reply)), - .subject = application, - .outcome = std::format("ok, {} entries", reply.entries.size())}; - } + ::morph::session::IAuthorizer const& authorizer) const; /// @brief Lists the entries the principal sees into @p reply. /// @param reply The reply being built. @@ -1264,90 +495,26 @@ class UiService final : public ::morph::backend::IEnvelopeService { /// @param authorizer The server's authoriser. /// @return What the documents the principal may fetch name. [[nodiscard]] Fetchable listEntries(CatalogReply& reply, ::morph::session::Context const& session, - ::morph::session::IAuthorizer const& authorizer) const { - Fetchable fetchable{.modelTypes = {_bundle->appModelTypes.begin(), _bundle->appModelTypes.end()}, - .actions = {}}; - for (ActionRef const& ref : _bundle->appActions) { - fetchable.actions.insert(ref.action); - } - for (ServedScreen const& screen : _bundle->screens) { - CatalogEntry entry = screen.entry; - if (entry.available && !detail::permitsAll(authorizer, session, screen.topQueries)) { - if (entry.whenDenied == "hide") { - continue; - } - entry.available = false; - entry.reason = "denied"; - } - if (entry.available || entry.isPublic) { - fetchable.modelTypes.insert(screen.modelTypes.begin(), screen.modelTypes.end()); - for (ActionRef const& ref : screen.actions) { - fetchable.actions.insert(ref.action); - } - } - reply.entries.push_back(std::move(entry)); - } - return fetchable; - } + ::morph::session::IAuthorizer const& authorizer) const; /// @brief Answers a `ui-fetch` and logs the outcome at debug. /// @param request The envelope; its body is a `FetchRequest`. /// @param authorizer The server's authoriser. /// @return The encoded reply. [[nodiscard]] std::string fetch(::morph::wire::Envelope const& request, - ::morph::session::IAuthorizer const& authorizer) const { - Answer answer = fetchAnswer(request, authorizer); - ::morph::log::logDebug("[ui-fetch] {}: {}", answer.subject, answer.outcome); - return std::move(answer.encoded); - } + ::morph::session::IAuthorizer const& authorizer) const; /// @brief Answers a `ui-fetch` without logging it. /// @param request The envelope; its body is a `FetchRequest`. /// @param authorizer The server's authoriser. /// @return The reply and its log fields. [[nodiscard]] Answer fetchAnswer(::morph::wire::Envelope const& request, - ::morph::session::IAuthorizer const& authorizer) const { - auto wanted = parseFetchRequest(request.body); - if (!wanted) { - std::string const reason = std::move(wanted.error()); - return Answer{.encoded = err(request, reason), .subject = "", .outcome = "refused: " + reason}; - } - std::string const& hash = wanted->hash; - auto const found = _bundle->files.find(hash); - bool const isPublic = found != _bundle->files.end() && - std::ranges::any_of(found->second.holders, - [](ServedFile::Holder const& holder) { return holder.isPublic; }); - if (isPublic) { - return gate(authorizer, request, kHelloAction) - ? Answer{.encoded = ok(request, found->second.bytes), .subject = hash, .outcome = "ok"} - : Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), - .subject = hash, - .outcome = "refused: unauthorized"}; - } - // The fetch gate comes before the lookup's answer, so a caller it refuses cannot learn which hashes exist. - if (!gate(authorizer, request, kFetchAction)) { - return Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), - .subject = hash, - .outcome = "refused: unauthorized"}; - } - if (found == _bundle->files.end()) { - return Answer{.encoded = err(request, "not found"), .subject = hash, .outcome = "refused: not found"}; - } - bool const admitted = std::ranges::any_of(found->second.holders, [&](ServedFile::Holder const& holder) { - return !holder.screen || screenAdmits(_bundle->screens.at(*holder.screen), request.session, authorizer); - }); - return admitted ? Answer{.encoded = ok(request, found->second.bytes), .subject = hash, .outcome = "ok"} - : Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), - .subject = hash, - .outcome = "refused: unauthorized"}; - } + ::morph::session::IAuthorizer const& authorizer) const; /// @brief Whether the principal may fetch @p screen's document: it is available, and the catalog lists it as /// such (every top-level query permitted). [[nodiscard]] static bool screenAdmits(ServedScreen const& screen, ::morph::session::Context const& session, - ::morph::session::IAuthorizer const& authorizer) { - return screen.entry.available && detail::permitsAll(authorizer, session, screen.topQueries); - } + ::morph::session::IAuthorizer const& authorizer); std::shared_ptr _bundle; ::morph::model::detail::ActionDispatcher* _dispatcher; diff --git a/src/ui/service.cpp b/src/ui/service.cpp new file mode 100644 index 000000000..f0fb66901 --- /dev/null +++ b/src/ui/service.cpp @@ -0,0 +1,960 @@ +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace morph::ui { +namespace { + +/// @brief Whether @p bytes can be served: within `kMaxFileBytes`, and within the envelope bound once escaped into +/// an `ok` reply. +/// @param bytes The file. +/// @return Why it cannot, or nothing. +[[nodiscard]] std::optional checkServable(std::string const& bytes) { + if (bytes.size() > kMaxFileBytes) { + return "the file is larger than " + std::to_string(kMaxFileBytes) + " bytes"; + } + if (::morph::wire::encode(::morph::wire::makeOk(0, bytes)).size() > ::morph::wire::kMaxEnvelopeBytes) { + return std::string{"the file does not fit one envelope once escaped"}; + } + return std::nullopt; +} + +/// @brief Checks a catalog entry's own fields. +/// @param entry The entry. +/// @return Why it is refused, or nothing. +[[nodiscard]] std::optional checkEntry(CatalogEntry const& entry) { + if (entry.id.empty()) { + return std::string{"a catalog entry has an id"}; + } + if (auto reason = detail::checkName(entry.id, "a catalog entry id")) { + return reason; + } + if (entry.whenDenied != "hide" && entry.whenDenied != "disable") { + return "`whenDenied` is `hide` or `disable`, not `" + entry.whenDenied + "`"; + } + return std::nullopt; +} + +// NOLINTBEGIN(misc-no-recursion): view nodes nest, and the walk follows them; parseJson bounds the depth at 64. + +/// @brief Collects the actions and model types a loaded document names, resolving each query's, mutation's and +/// model-bound node's alias through the enclosing scopes. +/// +/// Load-time validation has already resolved every alias and requires every alias to name a type, so each lookup +/// here finds one. +class DocumentActions { +public: + /// @brief Walks @p document. + /// @param document The loaded document. + explicit DocumentActions(Document const& document) { + enter(document.scope, true); + if (document.view) { + node(*document.view); + } + } + + /// @brief The top-level queries. + /// @return Them, in declaration order. + [[nodiscard]] std::vector const& topQueries() const noexcept { return _top; } + + /// @brief Every action named. + /// @return Them, sorted and unique. + [[nodiscard]] std::vector actions() const { return {_all.begin(), _all.end()}; } + + /// @brief Every model type named. + /// @return Them, sorted and unique. + [[nodiscard]] std::vector modelTypes() const { return {_models.begin(), _models.end()}; } + +private: + void enter(ScopeDecl const& scope, bool top) { + for (ModelDecl const& model : scope.models) { + _types.try_emplace(model.name).first->second.push_back(model.type); + _models.insert(model.type); + } + for (QueryDecl const& query : scope.queries) { + ActionRef ref{.modelType = resolve(query.model), .action = query.action}; + if (top) { + _top.push_back(ref); + } + _all.insert(std::move(ref)); + } + for (MutationDecl const& mutation : scope.mutations) { + _all.insert(ActionRef{.modelType = resolve(mutation.model), .action = mutation.action}); + } + } + + void leave(ScopeDecl const& scope) { + for (ModelDecl const& model : scope.models) { + _types.at(model.name).pop_back(); + } + } + + void node(DocNode const& view) { + if (view.scope) { + enter(*view.scope, false); + } + if (std::string_view const model = view.name("model"); !model.empty()) { + _all.insert(ActionRef{.modelType = resolve(model), .action = std::string{view.name("action")}}); + } + for (auto const& [key, children] : view.children) { + static_cast(key); + for (DocNodePtr const& child : children) { + node(*child); + } + } + for (auto const& [key, parts] : view.parts) { + static_cast(key); + for (DocNodePtr const& part : parts) { + node(*part); + } + } + if (view.scope) { + leave(*view.scope); + } + } + + /// @brief The type of the innermost alias named @p alias. Load-time validation has resolved it already, so the + /// lookup cannot miss; `at` throws rather than read past the end if that ever changes. + [[nodiscard]] std::string const& resolve(std::string_view alias) const { + std::vector const& types = _types.at(std::string{alias}); + return types.at(types.size() - 1); + } + + /// @brief The types an alias names in the open scopes, innermost last. + std::map, std::less<>> _types; + std::vector _top; + std::set _all; + std::set _models; +}; + +// NOLINTEND(misc-no-recursion) + +/// @brief Whether the principal of @p session may run every action of @p refs. +/// @param authorizer The authoriser. +/// @param session The session, its principal verified. +/// @param refs The actions. +/// @return Whether it may run all of them; `true` for none. +[[nodiscard]] bool permitsAll(::morph::session::IAuthorizer const& authorizer, + ::morph::session::Context const& session, std::vector const& refs) { + return std::ranges::all_of( + refs, [&](ActionRef const& ref) { return authorizer.authorize(session, ref.modelType, ref.action); }); +} + +} // namespace +} // namespace morph::ui + +namespace morph::ui { + +std::expected UiRegistry::addScreen(CatalogEntry entry, std::string text) { + std::string const screenId = entry.id; + std::size_t const size = text.size(); + auto added = addScreenImpl(std::move(entry), std::move(text)); + if (added) { + ::morph::log::logDebug("[ui-serve] added the screen `{}` ({} bytes)", screenId, size); + } else { + ::morph::log::logWarn("[ui-serve] refused a screen: {}", added.error().message()); + } + return added; +} + +std::expected UiRegistry::addEntry(CatalogEntry entry) { + std::string const entryId = entry.id; + auto added = addEntryImpl(std::move(entry)); + if (added) { + ::morph::log::logDebug("[ui-serve] added the entry `{}`", entryId); + } else { + ::morph::log::logWarn("[ui-serve] refused an entry: {}", added.error().message()); + } + return added; +} + +std::expected UiRegistry::addFile(BundleFile file) { + std::string const kind = file.kind; + std::string const fileId = file.id; + std::size_t const size = file.bytes.size(); + auto added = addFileImpl(std::move(file)); + if (added) { + ::morph::log::logDebug("[ui-serve] added the {} `{}` ({} bytes)", kind, fileId, size); + } else { + ::morph::log::logWarn("[ui-serve] refused a file: {}", added.error().message()); + } + return added; +} + +std::expected UiRegistry::setShellParts(ShellParts parts, Catalog reads) { + // A refused call leaves the parts and the catalog as they were, so the next app document is not judged by + // them. + Catalog previousCatalog = _catalog; + std::optional previous = std::exchange(_shellParts, std::move(parts)); + _catalog = withReads(_baseCatalog, std::move(reads)); + std::expected outcome = [&]() -> std::expected { + if (auto named = checkShellNames()) { + return std::unexpected(std::move(*named)); + } + return applyShellParts(previous.has_value()); + }(); + if (!outcome) { + _shellParts = std::move(previous); + _catalog = std::move(previousCatalog); + } + return outcome; +} + +std::expected, Refusal> UiRegistry::build() const { + auto built = buildImpl(); + if (built) { + logThemeProblems(); + ::morph::log::logDebug("[ui-serve] built the bundle of `{}`: {} files, digest {}", _application.id, + (*built)->files.size(), (*built)->digest); + } else { + ::morph::log::logWarn("[ui-serve] refused to build: {}", built.error().message()); + } + return built; +} + +void UiRegistry::logThemeProblems() const { + TokenFileLookup const lookup = [this](std::string_view fileId) -> TokenSet const* { + auto const found = _tokenFiles.find(fileId); + return found == _tokenFiles.end() ? nullptr : &found->second; + }; + for (auto const& [indexId, index] : _themeIndexes) { + for (std::string const& problem : themeProblems(index, lookup)) { + ::morph::log::logWarn("[ui-serve] theme {}: {}", indexId, problem); + } + } +} + +std::expected UiRegistry::addScreenImpl(CatalogEntry entry, std::string text) { + if (auto refusal = checkNewEntry(entry)) { + return std::unexpected(std::move(*refusal)); + } + if (entry.host) { + return refuse(entry.id, "a host screen has no document; it is added with addEntry"); + } + if (auto reason = checkServable(text)) { + return refuse(entry.id, std::move(*reason)); + } + auto loaded = loadDocumentText(text, LoadOptions{.catalog = _catalog}); + if (!loaded) { + return std::unexpected(std::move(loaded.error())); + } + if (loaded->id != entry.id) { + return refuse(entry.id, "the entry's id is not the document's id `" + loaded->id + "`"); + } + if (!loaded->view) { + return refuse(entry.id, "the app document is added with addFile"); + } + logWarnings(*loaded); + DocumentActions const named{*loaded}; + Screen screen{.served = ServedScreen{.entry = std::move(entry), + .hash = contentHash(text), + .topQueries = named.topQueries(), + .actions = named.actions(), + .modelTypes = named.modelTypes()}, + .text = std::move(text), + .components = {}}; + for (auto const& [name, component] : loaded->components) { + static_cast(name); + if (!component.qml.empty()) { + screen.components.emplace_back(pointerAppend(component.path, "qml"), component.qml); + } + } + _screens.push_back(std::move(screen)); + return {}; +} + +std::expected UiRegistry::addEntryImpl(CatalogEntry entry) { + if (auto refusal = checkNewEntry(entry)) { + return std::unexpected(std::move(*refusal)); + } + if (!entry.host && entry.available) { + return refuse(entry.id, "an entry without a document is a host screen or unavailable"); + } + _screens.push_back(Screen{ + .served = + ServedScreen{.entry = std::move(entry), .hash = {}, .topQueries = {}, .actions = {}, .modelTypes = {}}, + .text = {}, + .components = {}}); + return {}; +} + +std::expected UiRegistry::addFileImpl(BundleFile file) { + if (file.kind != kAppFile && file.kind != kThemeFile && file.kind != kMessagesFile && + file.kind != kComponentFile && file.kind != kIconFile) { + return refuse(file.id, + "a file is an app document, a theme, a message catalogue, a component or an icon, " + "not `" + + file.kind + "`"); + } + if (file.id.empty()) { + return refuse(file.id, "a file has an id"); + } + if (auto reason = detail::checkName(file.id, "a file id")) { + return refuse(file.id, std::move(*reason)); + } + if (file.kind == kAppFile && _appSynthesised) { + // The app document `setShellParts` made stands in until the application adds its own. + std::erase_if(_files, [](BundleFile const& held) { return held.kind == kAppFile; }); + _appSynthesised = false; + } + if (std::ranges::any_of( + _files, [&file](BundleFile const& added) { return added.kind == file.kind && added.id == file.id; })) { + return refuse(file.id, "the " + file.kind + " `" + file.id + "` is already added"); + } + if (auto reason = checkServable(file.bytes)) { + return refuse(file.id, std::move(*reason)); + } + if (file.kind == kAppFile && _shellParts) { + auto patched = withShellParts(std::move(file), false); + if (!patched) { + return std::unexpected(std::move(patched.error())); + } + file = std::move(*patched); + } + if (auto added = addKind(file); !added) { + return added; + } + _files.push_back(std::move(file)); + return {}; +} + +std::expected, Refusal> UiRegistry::buildImpl() const { + if (auto refusal = checkBuildable()) { + return std::unexpected(std::move(*refusal)); + } + auto bundle = std::make_shared(); + bundle->application = _application; + bundle->vocabularies.assign(_vocabularies.begin(), _vocabularies.end()); + bundle->appActions = _appActions; + bundle->appModelTypes = _appModelTypes; + serveFiles(*bundle); + addFacts(*bundle); + return bundle; +} + +std::optional UiRegistry::checkThemes() const { + TokenFileLookup const lookup = [this](std::string_view fileId) -> TokenSet const* { + auto const found = _tokenFiles.find(fileId); + return found == _tokenFiles.end() ? nullptr : &found->second; + }; + for (auto const& [indexId, index] : _themeIndexes) { + if (auto reason = checkTheme(index, lookup)) { + return Refusal{.document = indexId, .path = {}, .reason = "the theme: " + std::move(*reason)}; + } + for (auto const& [name, fileId] : index.icons) { + bool const held = std::ranges::any_of( + _files, [&fileId](BundleFile const& file) { return file.kind == kIconFile && file.id == fileId; }); + if (!held) { + return Refusal{.document = indexId, + .path = {}, + .reason = std::format("the theme index names the icon `{}` as `{}`, which is not " + "an icon file of the bundle", + name, fileId)}; + } + } + } + return std::nullopt; +} + +std::expected UiRegistry::addKind(BundleFile const& file) { + if (file.kind == kMessagesFile) { + return checkCatalogue(file); + } + if (file.kind == kThemeFile) { + return addTheme(file); + } + if (file.kind == kAppFile) { + return addApp(file); + } + if (file.kind == kIconFile) { + return checkIcon(file); + } + return {}; +} + +std::expected UiRegistry::checkIcon(BundleFile const& file) { + if (file.bytes.size() > kMaxIconBytes) { + return refuse(file.id, std::format("an icon is at most {} bytes of SVG; this one is {}", kMaxIconBytes, + file.bytes.size())); + } + if (!file.bytes.contains(" element"); + } + return {}; +} + +std::expected UiRegistry::checkCatalogue(BundleFile const& file) { + if (!catalogueLocale(file.id)) { + return refuse(file.id, "a message catalogue's id is i18n/.json"); + } + auto catalogue = parseCatalogue(file.bytes); + if (!catalogue) { + return refuse(file.id, std::move(catalogue.error())); + } + if (!catalogue->dropped.empty()) { + return refuse(file.id, "a message is outside the ui/1 subset: " + catalogue->dropped.front()); + } + return {}; +} + +std::expected UiRegistry::addTheme(BundleFile const& file) { + if (isThemeIndex(file.bytes)) { + auto index = parseThemeIndex(file.bytes); + if (!index) { + return refuse(file.id, "the theme index: " + index.error()); + } + _themeIndexes.emplace_back(file.id, std::move(*index)); + return {}; + } + auto tokens = parseTokens(file.bytes); + if (!tokens) { + return refuse(file.id, "the token file: " + tokens.error()); + } + _tokenFiles.emplace(file.id, std::move(*tokens)); + return {}; +} + +std::expected UiRegistry::applyShellParts(bool replace) { + auto found = std::ranges::find_if(_files, [](BundleFile const& file) { return file.kind == kAppFile; }); + if (found == _files.end()) { + BundleFile file{.kind = std::string{kAppFile}, + .id = std::string{kAppFile}, + .bytes = R"({"vocab":"ui/1","id":"app"})", + .isPublic = true}; + auto patched = withShellParts(std::move(file), false); + if (!patched) { + return std::unexpected(std::move(patched.error())); + } + if (auto added = addApp(*patched); !added) { + return added; + } + _files.push_back(std::move(*patched)); + _appSynthesised = true; + return {}; + } + auto patched = withShellParts(*found, replace); + if (!patched) { + return std::unexpected(std::move(patched.error())); + } + if (auto added = addApp(*patched); !added) { + return added; + } + *found = std::move(*patched); + return {}; +} + +std::expected UiRegistry::withShellParts(BundleFile file, bool replace) const { + auto document = parseJson(file.bytes); + auto* const object = document ? std::get_if(&document->data) : nullptr; + auto shell = parseJson(glz::write_json(*_shellParts).value_or("{}")); + if (object == nullptr || !shell) { + return refuse(file.id, "the app document is a JSON object"); + } + if (!replace && object->contains("shell")) { + return refuse(file.id, "the app document declares its own `shell`, and the registry was given parts too"); + } + object->insert_or_assign("shell", std::move(*shell)); + file.bytes = glz::write_json(*document).value_or(file.bytes); + return file; +} + +std::expected UiRegistry::addApp(BundleFile const& file) { + auto loaded = loadDocumentText(file.bytes, LoadOptions{.catalog = _catalog}); + if (!loaded) { + return std::unexpected(std::move(loaded.error())); + } + if (loaded->id != kAppFile) { + return refuse(file.id, "the app document's id is `app`"); + } + logWarnings(*loaded); + DocumentActions const named{*loaded}; + _appActions = named.actions(); + _appModelTypes = named.modelTypes(); + return {}; +} + +void UiRegistry::logWarnings(Document const& document) { + for (LoadWarning const& warning : document.warnings) { + morph::log::logWarn(warning.message(document.id)); + } +} + +std::optional UiRegistry::checkNewEntry(CatalogEntry const& entry) const { + if (auto reason = checkEntry(entry)) { + return Refusal{.document = entry.id, .path = {}, .reason = std::move(*reason)}; + } + if (std::ranges::any_of(_screens, [&](Screen const& screen) { return screen.served.entry.id == entry.id; })) { + return Refusal{.document = entry.id, .path = {}, .reason = "a catalog entry with this id is registered"}; + } + return std::nullopt; +} + +Catalog UiRegistry::withReads(Catalog base, Catalog reads) { + if (reads.model) { + base.model = [first = std::move(base.model), + second = std::move(reads.model)](std::string_view typeId) -> std::optional { + auto found = first ? first(typeId) : std::nullopt; + return found ? found : second(typeId); + }; + } + if (reads.action) { + base.action = [first = std::move(base.action), + second = std::move(reads.action)](std::string_view actionId) -> std::optional { + auto found = first ? first(actionId) : std::nullopt; + return found ? found : second(actionId); + }; + } + return base; +} + +std::optional UiRegistry::checkShellNames() const { + if (!_shellParts) { + return std::nullopt; + } + auto const hasModule = [this](std::string const& module) { + return module.empty() || std::ranges::any_of(_screens, [&module](Screen const& screen) { + return screen.served.entry.module == module; + }); + }; + auto const hasScreen = [this](std::string const& id) { + return std::ranges::any_of(_screens, [&id](Screen const& screen) { return screen.served.entry.id == id; }); + }; + auto const unknown = [](std::string path, std::string const& kind, std::string const& name) { + return Refusal{.document = std::string{kAppFile}, + .path = std::move(path), + .reason = "the shell names the " + kind + " `" + name + "`, which no screen registered has"}; + }; + for (std::size_t index = 0; index < _shellParts->modules.size(); ++index) { + if (auto const& module = _shellParts->modules.at(index).module; !hasModule(module)) { + return unknown("/shell/modules/" + std::to_string(index) + "/module", "module", module); + } + } + for (std::size_t index = 0; index < _shellParts->search.size(); ++index) { + if (auto const& module = _shellParts->search.at(index).module; !hasModule(module)) { + return unknown("/shell/search/" + std::to_string(index) + "/module", "module", module); + } + } + if (_shellParts->inbox && !hasScreen(_shellParts->inbox->screen)) { + return unknown("/shell/inbox/screen", "screen", _shellParts->inbox->screen); + } + if (_shellParts->help && !_shellParts->help->screen.empty() && !hasScreen(_shellParts->help->screen)) { + return unknown("/shell/help/screen", "screen", _shellParts->help->screen); + } + return std::nullopt; +} + +std::optional UiRegistry::checkBuildable() const { + if (auto refusal = checkThemes()) { + return refusal; + } + std::set> componentHashes; + for (BundleFile const& file : _files) { + if (file.kind == kComponentFile) { + componentHashes.insert(contentHash(file.bytes)); + } + } + for (Screen const& screen : _screens) { + for (auto const& [path, hash] : screen.components) { + if (!componentHashes.contains(hash)) { + return Refusal{.document = screen.served.entry.id, + .path = path, + .reason = "the delivered component is not in the bundle"}; + } + } + } + if (_screens.size() > kMaxBundleFiles || _screens.size() + _files.size() > kMaxBundleFiles) { + return Refusal{ + .document = {}, + .path = {}, + .reason = "the bundle holds more than " + std::to_string(kMaxBundleFiles) + " files or entries"}; + } + std::vector const vocabularies{_vocabularies.begin(), _vocabularies.end()}; + if (auto reason = detail::checkNames(vocabularies, kMaxListItems, "the vocabularies", "a vocabulary")) { + return Refusal{.document = {}, .path = {}, .reason = std::move(*reason)}; + } + return std::nullopt; +} + +void UiRegistry::serveFiles(ServedBundle& bundle) const { + Manifest manifest{.application = _application.id, .version = _application.version, .files = {}}; + auto serve = [&bundle, &manifest](BundleFile const& file, std::optional screen) { + std::string const hash = contentHash(file.bytes); + manifest.files.push_back(ManifestFile{ + .id = file.id, .kind = file.kind, .hash = hash, .size = file.bytes.size(), .isPublic = file.isPublic}); + ServedFile& served = bundle.files.try_emplace(hash).first->second; + served.bytes = file.bytes; + served.holders.push_back( + ServedFile::Holder{.kind = file.kind, .id = file.id, .isPublic = file.isPublic, .screen = screen}); + }; + for (Screen const& screen : _screens) { + if (!screen.served.hash.empty()) { + serve(BundleFile{.kind = std::string{kScreenFile}, + .id = screen.served.entry.id, + .bytes = screen.text, + .isPublic = screen.served.entry.isPublic}, + bundle.screens.size()); + } + bundle.screens.push_back(screen.served); + } + for (BundleFile const& file : _files) { + serve(file, std::nullopt); + } + std::ranges::sort(manifest.files, [](ManifestFile const& lhs, ManifestFile const& rhs) { + return std::tie(lhs.kind, lhs.id) < std::tie(rhs.kind, rhs.id); + }); + bundle.manifest = manifestText(manifest); + bundle.digest = contentHash(bundle.manifest); + bundle.files.insert_or_assign( + bundle.digest, + ServedFile{.bytes = bundle.manifest, + .holders = {ServedFile::Holder{ + .kind = "manifest", .id = _application.id, .isPublic = true, .screen = std::nullopt}}}); +} + +void UiRegistry::addFacts(ServedBundle& bundle) const { + std::set all{_appActions.begin(), _appActions.end()}; + std::set> modelTypes{_appModelTypes.begin(), _appModelTypes.end()}; + for (ServedScreen const& screen : bundle.screens) { + all.insert(screen.actions.begin(), screen.actions.end()); + modelTypes.insert(screen.modelTypes.begin(), screen.modelTypes.end()); + } + bundle.allActions.assign(all.begin(), all.end()); + if (_catalog.model) { + auto& known = bundle.models.emplace(); + for (std::string const& type : modelTypes) { + // Load-time validation refused every document naming a type the lookup does not know. + known.emplace(type, _catalog.model(type).value_or(ModelInfo{})); + } + } + if (_catalog.action) { + auto& known = bundle.actions.emplace(); + for (ActionRef const& ref : all) { + // Load-time validation refused every document naming an action the lookup does not know. + known.emplace(ref.action, _catalog.action(ref.action).value_or(ActionInfo{})); + } + } + auto const documents = [&all](auto const& lookup, auto& out) { + if (!lookup) { + return; + } + auto& known = out.emplace(); + for (ActionRef const& ref : all) { + if (std::optional document = lookup(ref.action)) { + known.emplace(ref.action, std::move(*document)); + } + } + }; + documents(_catalog.view, bundle.views); + documents(_catalog.wizard, bundle.wizards); +} + +UiService::UiService(std::shared_ptr bundle, + ::morph::model::detail::ActionDispatcher& dispatcher MORPH_LIFETIMEBOUND, + std::shared_ptr files) + : _bundle{std::move(bundle)}, _dispatcher{&dispatcher}, _files{std::move(files)} { + if (!_bundle) { + throw std::invalid_argument("UiService: the bundle is null"); + } +} + +bool UiService::serves(std::string_view kind) const { + return kind == kHelloKind || kind == kCatalogKind || kind == kFetchKind || kind == kEvaluateKind || + (kind == kFileKind && _files != nullptr); +} + +std::string UiService::handle(::morph::wire::Envelope const& request, + ::morph::session::IAuthorizer const& authorizer) { + ::morph::backend::ConnectionFacts facts; + return handle(request, authorizer, facts); +} + +std::string UiService::handle(::morph::wire::Envelope const& request, ::morph::session::IAuthorizer const& authorizer, + ::morph::backend::ConnectionFacts& facts) { + if (request.kind == kHelloKind) { + return hello(request, authorizer, facts); + } + if (request.kind == kCatalogKind) { + return catalog(request, authorizer); + } + if (request.kind == kEvaluateKind) { + return evaluate(request, authorizer); + } + if (request.kind == kFileKind) { + return file(request, authorizer); + } + return fetch(request, authorizer); +} + +std::string UiService::hello(::morph::wire::Envelope const& request, ::morph::session::IAuthorizer const& authorizer, + ::morph::backend::ConnectionFacts& facts) const { + Answer answer = helloAnswer(request, authorizer, facts); + ::morph::log::logDebug("[ui-hello] `{}`: {}", answer.subject, answer.outcome); + return std::move(answer.encoded); +} + +UiService::Answer UiService::helloAnswer(::morph::wire::Envelope const& request, + ::morph::session::IAuthorizer const& authorizer, + ::morph::backend::ConnectionFacts& facts) const { + std::string const application = _bundle->application.id; + if (!gate(authorizer, request, kHelloAction)) { + return Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), + .subject = application, + .outcome = "refused: unauthorized"}; + } + auto client = parseHelloRequest(request.body); + if (!client) { + std::string const reason = std::move(client.error()); + return Answer{.encoded = err(request, reason), .subject = application, .outcome = "refused: " + reason}; + } + std::string missing; + for (std::string const& vocabulary : _bundle->vocabularies) { + if (std::ranges::find(client->vocabularies, vocabulary) == client->vocabularies.end()) { + missing += (missing.empty() ? "" : ", ") + vocabulary; + } + } + if (!missing.empty()) { + std::string const reason = "missing vocabulary: " + missing; + return Answer{.encoded = err(request, reason), .subject = application, .outcome = "refused: " + reason}; + } + if (client->events) { + facts.events = true; + } + return Answer{.encoded = ok(request, detail::writeMessage(HelloReply{.application = _bundle->application.id, + .version = _bundle->application.version, + .vocabularies = _bundle->vocabularies, + .digest = _bundle->digest, + .events = client->events})), + .subject = application, + .outcome = "ok, digest " + _bundle->digest}; +} + +std::string UiService::evaluate(::morph::wire::Envelope const& request, + ::morph::session::IAuthorizer const& authorizer) const { + if (request.modelType.empty() || request.actionType.empty()) { + return err(request, "ui-evaluate names no modelType and actionType"); + } + if (!authorizer.authorize(request.session, request.modelType, request.actionType)) { + return err(request, std::string{::morph::wire::kUnauthorizedMessage}); + } + auto evaluation = _dispatcher->evaluate(request.modelType, request.actionType, request.body); + EvaluateReply reply{.body = {}, .errors = std::move(evaluation.errors), .ready = evaluation.ready}; + if (auto const error = glz::read_json(reply.body, evaluation.body)) { + return err(request, "ui-evaluate: " + glz::format_error(error, evaluation.body)); + } + return ok(request, detail::writeMessage(reply)); +} + +std::string UiService::file(::morph::wire::Envelope const& request, + ::morph::session::IAuthorizer const& authorizer) const { + auto parsed = parseFileRequest(request.body); + if (!parsed) { + return err(request, std::move(parsed.error())); + } + FileRequest& step = *parsed; + std::string const& principal = request.session.principal; + auto const refused = [&request](FileError error) { return err(request, std::string{fileErrorText(error)}); }; + FileReply reply; + if (step.op == "begin") { + if (step.model.empty() || step.action.empty()) { + return err(request, "ui-file begin names no model and action"); + } + if (!authorizer.authorize(request.session, step.model, step.action)) { + return err(request, std::string{::morph::wire::kUnauthorizedMessage}); + } + auto upload = _files->begin( + principal, FileInfo{.name = std::move(step.name), .type = std::move(step.type), .size = step.size}); + if (!upload) { + return refused(upload.error()); + } + reply.upload = std::move(*upload); + } else if (step.op == "chunk") { + auto bytes = ::morph::session::detail::base64UrlDecode(step.data); + if (!bytes) { + return err(request, "ui-file chunk data is not base64url"); + } + if (bytes->size() > kMaxFileChunkBytes) { + return err(request, "ui-file chunk is longer than " + std::to_string(kMaxFileChunkBytes) + " bytes"); + } + auto received = _files->append(principal, step.upload, step.offset, *bytes); + if (!received) { + return refused(received.error()); + } + reply.received = *received; + } else if (step.op == "end") { + auto ref = _files->finish(principal, step.upload); + if (!ref) { + return refused(ref.error()); + } + reply.ref = std::move(*ref); + } else { + auto slice = _files->read(principal, step.ref, step.offset, std::min(step.length, kMaxFileChunkBytes)); + if (!slice) { + return refused(slice.error()); + } + reply.data = ::morph::session::detail::base64UrlEncode(slice->bytes); + reply.total = slice->info.size; + reply.name = std::move(slice->info.name); + reply.type = std::move(slice->info.type); + } + return ok(request, detail::writeMessage(reply)); +} + +std::string UiService::catalog(::morph::wire::Envelope const& request, + ::morph::session::IAuthorizer const& authorizer) const { + Answer answer = catalogAnswer(request, authorizer); + ::morph::log::logDebug("[ui-catalog] `{}`: {}", answer.subject, answer.outcome); + return std::move(answer.encoded); +} + +UiService::Answer UiService::catalogAnswer(::morph::wire::Envelope const& request, + ::morph::session::IAuthorizer const& authorizer) const { + std::string const application = _bundle->application.id; + if (!gate(authorizer, request, kCatalogAction)) { + return Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), + .subject = application, + .outcome = "refused: unauthorized"}; + } + CatalogReply reply; + Fetchable const fetchable = listEntries(reply, request.session, authorizer); + for (ActionRef const& ref : _bundle->allActions) { + if (authorizer.authorize(request.session, ref.modelType, ref.action)) { + reply.permitted.push_back(ref.action); + } + } + if (_bundle->models) { + auto& known = reply.models.emplace(); + for (auto const& [type, info] : *_bundle->models) { + if (fetchable.modelTypes.contains(type)) { + known.emplace(type, info); + } + } + } + if (_bundle->actions) { + auto& known = reply.actions.emplace(); + for (auto const& [action, info] : *_bundle->actions) { + if (fetchable.actions.contains(action)) { + known.emplace(action, info); + } + } + } + // A collection's or wizard's document goes with the action that names it, to whoever may fetch that action. + auto const documents = [&fetchable](auto const& served, auto& out) { + if (!served) { + return; + } + auto& known = out.emplace(); + for (auto const& [action, document] : *served) { + if (fetchable.actions.contains(action)) { + known.emplace(action, document); + } + } + }; + documents(_bundle->views, reply.views); + documents(_bundle->wizards, reply.wizards); + return Answer{.encoded = ok(request, detail::writeMessage(reply)), + .subject = application, + .outcome = std::format("ok, {} entries", reply.entries.size())}; +} + +UiService::Fetchable UiService::listEntries(CatalogReply& reply, ::morph::session::Context const& session, + ::morph::session::IAuthorizer const& authorizer) const { + Fetchable fetchable{.modelTypes = {_bundle->appModelTypes.begin(), _bundle->appModelTypes.end()}, .actions = {}}; + for (ActionRef const& ref : _bundle->appActions) { + fetchable.actions.insert(ref.action); + } + for (ServedScreen const& screen : _bundle->screens) { + CatalogEntry entry = screen.entry; + if (entry.available && !permitsAll(authorizer, session, screen.topQueries)) { + if (entry.whenDenied == "hide") { + continue; + } + entry.available = false; + entry.reason = "denied"; + } + if (entry.available || entry.isPublic) { + fetchable.modelTypes.insert(screen.modelTypes.begin(), screen.modelTypes.end()); + for (ActionRef const& ref : screen.actions) { + fetchable.actions.insert(ref.action); + } + } + reply.entries.push_back(std::move(entry)); + } + return fetchable; +} + +std::string UiService::fetch(::morph::wire::Envelope const& request, + ::morph::session::IAuthorizer const& authorizer) const { + Answer answer = fetchAnswer(request, authorizer); + ::morph::log::logDebug("[ui-fetch] {}: {}", answer.subject, answer.outcome); + return std::move(answer.encoded); +} + +UiService::Answer UiService::fetchAnswer(::morph::wire::Envelope const& request, + ::morph::session::IAuthorizer const& authorizer) const { + auto wanted = parseFetchRequest(request.body); + if (!wanted) { + std::string const reason = std::move(wanted.error()); + return Answer{.encoded = err(request, reason), .subject = "", .outcome = "refused: " + reason}; + } + std::string const& hash = wanted->hash; + auto const found = _bundle->files.find(hash); + bool const isPublic = + found != _bundle->files.end() && + std::ranges::any_of(found->second.holders, [](ServedFile::Holder const& holder) { return holder.isPublic; }); + if (isPublic) { + return gate(authorizer, request, kHelloAction) + ? Answer{.encoded = ok(request, found->second.bytes), .subject = hash, .outcome = "ok"} + : Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), + .subject = hash, + .outcome = "refused: unauthorized"}; + } + // The fetch gate comes before the lookup's answer, so a caller it refuses cannot learn which hashes exist. + if (!gate(authorizer, request, kFetchAction)) { + return Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), + .subject = hash, + .outcome = "refused: unauthorized"}; + } + if (found == _bundle->files.end()) { + return Answer{.encoded = err(request, "not found"), .subject = hash, .outcome = "refused: not found"}; + } + bool const admitted = std::ranges::any_of(found->second.holders, [&](ServedFile::Holder const& holder) { + return !holder.screen || screenAdmits(_bundle->screens.at(*holder.screen), request.session, authorizer); + }); + return admitted ? Answer{.encoded = ok(request, found->second.bytes), .subject = hash, .outcome = "ok"} + : Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), + .subject = hash, + .outcome = "refused: unauthorized"}; +} + +bool UiService::screenAdmits(ServedScreen const& screen, ::morph::session::Context const& session, + ::morph::session::IAuthorizer const& authorizer) { + return screen.entry.available && permitsAll(authorizer, session, screen.topQueries); +} + +} // namespace morph::ui From c2d29c4630382b7ae17b9062c49cb91d8b4dce8a Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 01:26:00 +0100 Subject: [PATCH 09/38] Move the UI service client's non-template code into src/ui/service_client.cpp The member bodies of two or more lines of MemoryBundleStore, VerifiedCache, UiClient and FileTransfer, and the free functions exchangeOver, evaluationValue, evaluatorOver and watcherOver, move to the compiled library. Their declarations keep their Doxygen blocks in the header and carry MORPH_API. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- CMakeLists.txt | 1 + include/morph/ui/service_client.hpp | 606 +++------------------------ src/ui/service_client.cpp | 623 ++++++++++++++++++++++++++++ 3 files changed, 672 insertions(+), 558 deletions(-) create mode 100644 src/ui/service_client.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index fd4d2ebfb..0d6869b0d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -417,6 +417,7 @@ add_library(morph STATIC src/ui/interpreter.cpp src/ui/library.cpp src/ui/service.cpp + src/ui/service_client.cpp ) add_library(morph::morph ALIAS morph) diff --git a/include/morph/ui/service_client.hpp b/include/morph/ui/service_client.hpp index 3d26877d4..f627d19fb 100644 --- a/include/morph/ui/service_client.hpp +++ b/include/morph/ui/service_client.hpp @@ -8,6 +8,7 @@ #include #include #include +#include #include #include #include @@ -80,65 +81,37 @@ class IBundleStore { }; /// @brief An `IBundleStore` in memory: it lasts as long as the process. Safe to call from any thread. -class MemoryBundleStore final : public IBundleStore { +class MORPH_API MemoryBundleStore final : public IBundleStore { public: /// @brief Reads a file. /// @param hash The file's content hash. /// @return Its bytes, or nothing. - [[nodiscard]] std::optional get(std::string_view hash) const override { - std::scoped_lock const lock{_mutex}; - auto const found = _files.find(hash); - if (found == _files.end()) { - return std::nullopt; - } - return found->second; - } + [[nodiscard]] std::optional get(std::string_view hash) const override; /// @brief Keeps a file. /// @param hash The file's content hash. /// @param bytes The file. // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the key, then the value. - void put(std::string const& hash, std::string bytes) override { - std::scoped_lock const lock{_mutex}; - _files.insert_or_assign(hash, std::move(bytes)); - } + void put(std::string const& hash, std::string bytes) override; /// @brief Drops a file. /// @param hash The file's content hash. - void remove(std::string_view hash) override { - std::scoped_lock const lock{_mutex}; - if (auto const found = _files.find(hash); found != _files.end()) { - _files.erase(found); - } - } + void remove(std::string_view hash) override; /// @brief The digest of an application's last verified bundle. /// @param application The application's id. /// @return The digest, or nothing. - [[nodiscard]] std::optional lastDigest(std::string_view application) const override { - std::scoped_lock const lock{_mutex}; - auto const found = _digests.find(application); - if (found == _digests.end()) { - return std::nullopt; - } - return found->second; - } + [[nodiscard]] std::optional lastDigest(std::string_view application) const override; /// @brief Records an application's last verified bundle. /// @param application The application's id. /// @param digest The manifest's content hash. // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the key, then the value. - void setLastDigest(std::string const& application, std::string digest) override { - std::scoped_lock const lock{_mutex}; - _digests.insert_or_assign(application, std::move(digest)); - } + void setLastDigest(std::string const& application, std::string digest) override; /// @brief How many files the store holds. /// @return The count. - [[nodiscard]] std::size_t size() const { - std::scoped_lock const lock{_mutex}; - return _files.size(); - } + [[nodiscard]] std::size_t size() const; private: mutable std::mutex _mutex; @@ -147,38 +120,22 @@ class MemoryBundleStore final : public IBundleStore { }; /// @brief A content-addressed cache that hands out only bytes that hash to the hash they are asked for. -class VerifiedCache { +class MORPH_API VerifiedCache { public: /// @brief A cache over @p store. /// @param store The store; shared with the caller. /// @throws std::invalid_argument if @p store is null. - explicit VerifiedCache(std::shared_ptr store) : _store{std::move(store)} { - if (!_store) { - throw std::invalid_argument("VerifiedCache: the store is null"); - } - } + explicit VerifiedCache(std::shared_ptr store); /// @brief Reads a file, verified. A stored file that does not hash to @p hash is dropped and reads as a miss. /// @param hash The content hash. /// @return The bytes, or nothing. - [[nodiscard]] std::optional get(std::string const& hash) { - auto bytes = _store->get(hash); - if (bytes && contentHash(*bytes) != hash) { - ::morph::log::logWarn("[ui-cache] dropped {}: the stored bytes do not hash to it", hash); - _store->remove(hash); - return std::nullopt; - } - return bytes; - } + [[nodiscard]] std::optional get(std::string const& hash); /// @brief Keeps a file under its content hash. /// @param bytes The bytes. /// @return The hash they are kept under. - std::string put(std::string bytes) { - std::string hash = contentHash(bytes); - _store->put(hash, std::move(bytes)); - return hash; - } + std::string put(std::string bytes); /// @brief The store. /// @return It. @@ -220,25 +177,8 @@ using Exchange = std::function done) { - auto const answer = std::make_shared>(std::move(done)); - transport->request(std::move(request), *owner) - .thenDetached([answer](::morph::wire::Envelope const& reply) { (*answer)(reply); }) - .onErrorDetached([answer](std::exception_ptr const& failure) { - std::string message = "the request was not delivered"; - try { - std::rethrow_exception(failure); - } catch (std::exception const& error) { - message = error.what(); - } catch (...) { // NOLINT(bugprone-empty-catch): the default message stands for a non-std failure - } - (*answer)(std::unexpected(std::move(message))); - }); - }; -} +[[nodiscard]] MORPH_API Exchange exchangeOver(::morph::backend::IEnvelopeTransport& backend MORPH_LIFETIMEBOUND, + ::morph::exec::IExecutor& cbExec MORPH_LIFETIMEBOUND); /// @brief Opens an application's bundle through the UI service, verifying everything it fetches. /// @@ -247,19 +187,14 @@ using Exchange = std::function store) - : _shared{std::make_shared(std::move(exchange), std::move(client), VerifiedCache{std::move(store)})} { - if (!_shared->exchange) { - throw std::invalid_argument("UiClient: the exchange is empty"); - } - } + UiClient(Exchange exchange, HelloRequest client, std::shared_ptr store); /// @brief What `open` delivers. using Done = std::function)>; @@ -268,10 +203,7 @@ class UiClient { /// synchronous exchange calls it before `open` returns. /// @param session The session every request carries: the principal's token, or none before sign-in. /// @param done Called with the bundle, or why there is none. - void open(::morph::session::Context session, Done done) const { - auto const run = std::make_shared(_shared, std::move(session), std::move(done)); - sendHello(run); - } + void open(::morph::session::Context session, Done done) const; /// @brief What `poll` delivers: the changed bundle, nothing when the digest is the one already held, or why /// there is none. @@ -284,55 +216,13 @@ class UiClient { /// @param knownDigest The digest of the bundle the client has, as `HelloReply::digest` spells it. /// @param done Called with the changed bundle, with nothing when the digest is unchanged, or with why the /// poll failed. - void poll(::morph::session::Context session, std::string knownDigest, PollDone done) const { - auto const answer = std::make_shared(std::move(done)); - auto const run = std::make_shared(_shared, std::move(session), - [answer](std::expected opened) { - if (!opened) { - (*answer)(std::unexpected(std::move(opened.error()))); - return; - } - (*answer)(std::optional{std::move(*opened)}); - }); - run->knownDigest = std::move(knownDigest); - run->unchanged = [answer] { (*answer)(std::optional{}); }; - sendHello(run); - } + void poll(::morph::session::Context session, std::string knownDigest, PollDone done) const; /// @brief Rebuilds the last bundle this store verified for @p application, without a connection. Files the /// store no longer holds, or that no longer verify, are left out; the catalog is empty. /// @param application The application's id. /// @return The bundle, or `Unreachable` when no verified manifest is cached. - [[nodiscard]] std::expected openOffline(std::string_view application) const { - auto const digest = _shared->cache.store().lastDigest(application); - if (!digest) { - return std::unexpected( - ConnectError{.kind = ConnectError::Kind::Unreachable, - .message = "no verified bundle of `" + std::string{application} + "` is cached"}); - } - auto const text = _shared->cache.get(*digest); - if (!text) { - return std::unexpected(ConnectError{ - .kind = ConnectError::Kind::Unreachable, - .message = "the cached manifest of `" + std::string{application} + "` is gone or does not verify"}); - } - auto manifest = parseManifest(*text); - if (!manifest) { - return std::unexpected(ConnectError{.kind = ConnectError::Kind::Unsupported, .message = manifest.error()}); - } - LoadedBundle loaded; - loaded.manifest = std::move(*manifest); - for (ManifestFile const& file : loaded.manifest.files) { - if (!usable(_shared->client, file.kind)) { - continue; - } - if (auto bytes = _shared->cache.get(file.hash)) { - loaded.files.emplace(file.hash, std::move(*bytes)); - } - } - assemble(loaded, *digest); - return loaded; - } + [[nodiscard]] std::expected openOffline(std::string_view application) const; private: /// @brief What the client and every run share; a run holds it, so a run outlives the client that started it. @@ -372,85 +262,25 @@ class UiClient { }; /// @brief Whether a client fetches files of @p kind: every kind it knows, components only when it loads them. - [[nodiscard]] static bool usable(HelloRequest const& client, std::string_view kind) { - if (kind == kComponentFile) { - return client.components; - } - return kind == kScreenFile || kind == kAppFile || kind == kThemeFile || kind == kMessagesFile || - kind == kIconFile; - } + [[nodiscard]] static bool usable(HelloRequest const& client, std::string_view kind); /// @brief Fills the bundle the shell reads from the verified files. - static void assemble(LoadedBundle& loaded, std::string const& digest) { - loaded.bundle.applicationId = loaded.manifest.application; - loaded.bundle.manifestDigest = digest.substr(kHashPrefix.size()); - for (ManifestFile const& file : loaded.manifest.files) { - if (file.kind != kScreenFile && file.kind != kAppFile && file.kind != kThemeFile) { - continue; - } - if (auto const found = loaded.files.find(file.hash); found != loaded.files.end()) { - auto& into = file.kind == kThemeFile ? loaded.bundle.themes : loaded.bundle.documents; - into.insert_or_assign(file.id, found->second); - } - } - // The icon set the theme index names, each icon's SVG by its name; a build refuses an index naming a file - // the bundle lacks. - for (auto const& [fileId, text] : loaded.bundle.themes) { - static_cast(fileId); - if (!isThemeIndex(text)) { - continue; - } - auto const index = parseThemeIndex(text); - if (!index) { - continue; - } - for (auto const& [name, iconId] : index->icons) { - auto const file = std::ranges::find_if(loaded.manifest.files, [&iconId](ManifestFile const& listed) { - return listed.kind == kIconFile && listed.id == iconId; - }); - if (file == loaded.manifest.files.end()) { - continue; - } - if (auto const found = loaded.files.find(file->hash); found != loaded.files.end()) { - loaded.bundle.icons.insert_or_assign(name, found->second); - } - } - } - } + static void assemble(LoadedBundle& loaded, std::string const& digest); /// @brief A request of @p kind carrying the run's session. - [[nodiscard]] static ::morph::wire::Envelope requestOf(std::shared_ptr const& run, std::string_view kind) { - ::morph::wire::Envelope request; - request.kind = std::string{kind}; - request.session = run->session; - return request; - } + [[nodiscard]] static ::morph::wire::Envelope requestOf(std::shared_ptr const& run, std::string_view kind); /// @brief Sends the `ui-hello`. - static void sendHello(std::shared_ptr const& run) { - ::morph::wire::Envelope request = requestOf(run, kHelloKind); - request.body = detail::writeMessage(run->shared->client); - run->shared->exchange(std::move(request), [run](ExchangeReply reply) { onHello(run, std::move(reply)); }); - } + static void sendHello(std::shared_ptr const& run); /// @brief Sends the `ui-catalog`. - static void sendCatalog(std::shared_ptr const& run) { - run->shared->exchange(requestOf(run, kCatalogKind), - [run](ExchangeReply reply) { onCatalog(run, std::move(reply)); }); - } + static void sendCatalog(std::shared_ptr const& run); /// @brief Sends a `ui-fetch` for @p hash. static void fetch(std::shared_ptr const& run, std::string const& hash, - std::function then) { - ::morph::wire::Envelope request = requestOf(run, kFetchKind); - request.body = detail::writeMessage(FetchRequest{.hash = hash}); - run->shared->exchange(std::move(request), std::move(then)); - } + std::function then); - static void fail(std::shared_ptr const& run, ConnectError error) { - ::morph::log::logWarn("[ui-fetch] {}", error.message); - run->done(std::unexpected(std::move(error))); - } + static void fail(std::shared_ptr const& run, ConnectError error); static void fail(std::shared_ptr const& run, ConnectError::Kind kind, std::string message) { fail(run, ConnectError{.kind = kind, .message = std::move(message)}); @@ -458,183 +288,25 @@ class UiClient { /// @brief The reply to a request, or the error it carries: a transport failure is `Unreachable`, an `err` is /// `Refused` with the server's message. - [[nodiscard]] static std::expected bodyOf(ExchangeReply reply) { - if (!reply) { - return std::unexpected(ConnectError{.kind = ConnectError::Kind::Unreachable, .message = reply.error()}); - } - if (reply->kind != "ok") { - return std::unexpected( - ConnectError{.kind = ConnectError::Kind::Refused, .message = std::move(reply->message)}); - } - return std::move(reply->body); - } + [[nodiscard]] static std::expected bodyOf(ExchangeReply reply); /// @brief A fetched file, verified against its hash, or why it is refused. [[nodiscard]] static std::expected verified(ExchangeReply reply, - Expected const& expected) { - auto body = bodyOf(std::move(reply)); - if (!body) { - body.error().message = expected.what + ": " + body.error().message; - return body; - } - if (body->size() > kMaxFileBytes) { - return std::unexpected(ConnectError{ - .kind = ConnectError::Kind::Unverified, - .message = expected.what + " is larger than " + std::to_string(kMaxFileBytes) + " bytes"}); - } - if (std::string const actual = contentHash(*body); actual != expected.hash) { - return std::unexpected(ConnectError{.kind = ConnectError::Kind::Unverified, - .message = expected.what + " does not match its hash (expected " + - expected.hash + ", got " + actual + ")"}); - } - return body; - } + Expected const& expected); - static void onHello(std::shared_ptr const& run, ExchangeReply reply) { - auto body = bodyOf(std::move(reply)); - if (!body) { - ConnectError error = std::move(body.error()); - if (error.message == "unknown envelope kind: " + std::string{kHelloKind}) { - error.kind = ConnectError::Kind::NoUiService; - error.message = "the server serves no UI"; - } else if (error.message.starts_with("missing vocabulary: ")) { - error.kind = ConnectError::Kind::Unsupported; - } - fail(run, std::move(error)); - return; - } - auto hello = parseHelloReply(*body); - if (!hello) { - fail(run, ConnectError::Kind::Unsupported, std::move(hello.error())); - return; - } - HelloRequest const& client = run->shared->client; - for (std::string const& vocabulary : hello->vocabularies) { - if (std::ranges::find(client.vocabularies, vocabulary) == client.vocabularies.end()) { - fail(run, ConnectError::Kind::Unsupported, - "the application needs the vocabulary " + vocabulary + ", which this client does not speak"); - return; - } - } - if (run->unchanged && hello->digest == run->knownDigest) { - ::morph::log::logDebug("[ui-fetch] polling `{}`: digest {}, known {}, manifest unchanged", - hello->application, hello->digest, run->knownDigest); - run->unchanged(); - return; - } - ::morph::log::logDebug("[ui-fetch] {} `{}`: digest {}, known {}, manifest {}", - run->unchanged ? "polling" : "opening", hello->application, hello->digest, - run->knownDigest.empty() ? std::string{""} : run->knownDigest, - hello->digest == run->knownDigest ? "unchanged" : "changed"); - run->loaded.hello = std::move(*hello); - std::string const& digest = run->loaded.hello.digest; - if (auto cached = run->shared->cache.get(digest)) { - onManifest(run, std::move(*cached)); - return; - } - fetch(run, digest, [run](ExchangeReply fetched) { - auto text = - verified(std::move(fetched), Expected{.hash = run->loaded.hello.digest, .what = "the manifest"}); - if (!text) { - fail(run, std::move(text.error())); - return; - } - onManifest(run, std::move(*text)); - }); - } + static void onHello(std::shared_ptr const& run, ExchangeReply reply); - static void onManifest(std::shared_ptr const& run, std::string text) { - auto manifest = parseManifest(text); - if (!manifest) { - fail(run, ConnectError::Kind::Unsupported, std::move(manifest.error())); - return; - } - static_cast(run->shared->cache.put(std::move(text))); - run->loaded.manifest = std::move(*manifest); - sendCatalog(run); - } + static void onManifest(std::shared_ptr const& run, std::string text); - static void onCatalog(std::shared_ptr const& run, ExchangeReply reply) { - auto body = bodyOf(std::move(reply)); - if (!body) { - fail(run, std::move(body.error())); - return; - } - auto catalog = parseCatalogReply(*body); - if (!catalog) { - fail(run, ConnectError::Kind::Unsupported, std::move(catalog.error())); - return; - } - run->loaded.catalog = std::move(*catalog); - std::vector missing; - for (ManifestFile const& file : run->loaded.manifest.files) { - if (!wanted(run->shared->client, run->loaded.catalog, file)) { - continue; - } - if (auto cached = run->shared->cache.get(file.hash)) { - run->loaded.files.insert_or_assign(file.hash, std::move(*cached)); - } else { - Expected expected{.hash = file.hash, .what = "the " + file.kind + " `" + file.id + "`"}; - ::morph::log::logDebug("[ui-fetch] fetching {} ({})", expected.hash, expected.what); - missing.push_back(std::move(expected)); - } - } - // One count for each fetch and one for this loop, so a synchronous exchange that answers every fetch - // before the next is sent cannot settle the run early. - run->pending = missing.size() + 1; - for (Expected& expected : missing) { - std::string const hash = expected.hash; - fetch(run, hash, [run, expected = std::move(expected)](ExchangeReply fetched) { - auto bytes = verified(std::move(fetched), expected); - { - std::scoped_lock const lock{run->mutex}; - if (!bytes) { - if (!run->failure) { - run->failure = std::move(bytes.error()); - } - } else { - static_cast(run->shared->cache.put(*bytes)); - run->loaded.files.insert_or_assign(expected.hash, std::move(*bytes)); - } - } - settle(run); - }); - } - settle(run); - } + static void onCatalog(std::shared_ptr const& run, ExchangeReply reply); /// @brief Whether the run fetches @p file: a kind the client uses, and for a screen, one the catalog lists as /// available or public, which is what the server serves this principal. [[nodiscard]] static bool wanted(HelloRequest const& client, CatalogReply const& catalog, - ManifestFile const& file) { - if (!usable(client, file.kind)) { - return false; - } - if (file.kind != kScreenFile) { - return true; - } - return std::ranges::any_of(catalog.entries, [&file](CatalogEntry const& entry) { - return entry.id == file.id && (entry.available || entry.isPublic); - }); - } + ManifestFile const& file); /// @brief Counts one fetch, or the loop that sent them, as settled; the last delivers the run. - static void settle(std::shared_ptr const& run) { - { - std::scoped_lock const lock{run->mutex}; - if (--run->pending != 0) { - return; - } - } - // Past the last count nothing else touches the run, so it is read without the lock. - if (run->failure) { - fail(run, std::move(*run->failure)); - return; - } - assemble(run->loaded, run->loaded.hello.digest); - run->shared->cache.store().setLastDigest(run->loaded.hello.application, run->loaded.hello.digest); - run->done(std::move(run->loaded)); - } + static void settle(std::shared_ptr const& run); std::shared_ptr _shared; }; @@ -646,30 +318,7 @@ class UiClient { /// @param reply The reply, or why the transport could not deliver it. /// @return The value as JSON text, or why there is none: the transport's reason, the server's `err` message, or why /// the reply body was refused. -[[nodiscard]] inline std::expected evaluationValue(ExchangeReply reply) { - if (!reply) { - return std::unexpected(std::move(reply.error())); - } - if (reply->kind != "ok") { - return std::unexpected(std::move(reply->message)); - } - auto evaluated = parseEvaluateReply(reply->body); - if (!evaluated) { - return std::unexpected(std::move(evaluated.error())); - } - Json::object_t errors; - for (auto const& [field, message] : evaluated->errors) { - errors.insert_or_assign(field, Json(message)); - } - auto& members = evaluated->body.get(); - members.insert_or_assign("errors", Json(std::move(errors))); - members.insert_or_assign("ready", Json(evaluated->ready)); - auto text = glz::write_json(evaluated->body); - if (!text) { - return std::unexpected("the ui-evaluate reply's body cannot be written"); - } - return std::move(*text); -} +[[nodiscard]] MORPH_API std::expected evaluationValue(ExchangeReply reply); /// @brief An evaluator over the UI service: each evaluation is one `ui-evaluate` request through @p exchange, and /// resolves with `evaluationValue` of its reply. What `BridgeDispatcher` takes as its `Evaluator`. @@ -677,30 +326,9 @@ class UiClient { /// @param session The session every request carries. /// @param cbExec The executor the completion is delivered on: the interpreter runtime's owner. Borrowed. /// @return The evaluator: the model's type id, the action id and its JSON body in, the query's value out. -[[nodiscard]] inline std::function<::morph::async::Completion(std::string const&, std::string const&, - std::string const&)> -evaluatorOver(Exchange exchange, ::morph::session::Context session, ::morph::exec::IExecutor* cbExec) { - return [exchange = std::move(exchange), session = std::move(session), cbExec]( - std::string const& typeId, std::string const& actionId, std::string const& bodyJson) { - auto [completion, promise] = ::morph::async::Completion::makeSettleable(cbExec); - auto settle = std::make_shared(std::move(promise)); - ::morph::wire::Envelope request; - request.kind = std::string{kEvaluateKind}; - request.session = session; - request.modelType = typeId; - request.actionType = actionId; - request.body = bodyJson; - exchange(std::move(request), [settle](ExchangeReply reply) { - auto value = evaluationValue(std::move(reply)); - if (value) { - settle->resolve(std::move(*value)); - } else { - settle->reject(std::make_exception_ptr(std::runtime_error{value.error()})); - } - }); - return std::move(completion); - }; -} +[[nodiscard]] MORPH_API + std::function<::morph::async::Completion(std::string const&, std::string const&, std::string const&)> + evaluatorOver(Exchange exchange, ::morph::session::Context session, ::morph::exec::IExecutor* cbExec); /// @brief A watcher over the server (spec 8 §7): each `watch` or `unwatch` is one request of that kind through /// @p exchange, carrying the session @p currentSession returns when it is sent. What `SessionOptions::watcher` @@ -713,29 +341,9 @@ evaluatorOver(Exchange exchange, ::morph::session::Context session, ::morph::exe /// @param cbExec The executor the completion is delivered on: the interpreter runtime's owner. Borrowed. /// @return The watcher: the kind and the `WatchBody` JSON in; the reply body out, or the transport's or the /// server's reason as the failure. -[[nodiscard]] inline std::function<::morph::async::Completion(std::string const&, std::string const&)> +[[nodiscard]] MORPH_API std::function<::morph::async::Completion(std::string const&, std::string const&)> watcherOver(Exchange exchange, std::function<::morph::session::Context()> currentSession, - ::morph::exec::IExecutor* cbExec) { - return [exchange = std::move(exchange), currentSession = std::move(currentSession), cbExec]( - std::string const& kind, std::string const& bodyJson) { - auto [completion, promise] = ::morph::async::Completion::makeSettleable(cbExec); - auto settle = std::make_shared(std::move(promise)); - ::morph::wire::Envelope request; - request.kind = kind; - request.session = currentSession ? currentSession() : ::morph::session::Context{}; - request.body = bodyJson; - exchange(std::move(request), [settle](ExchangeReply reply) { - if (!reply) { - settle->reject(std::make_exception_ptr(std::runtime_error{reply.error()})); - } else if (reply->kind != "ok") { - settle->reject(std::make_exception_ptr(std::runtime_error{reply->message})); - } else { - settle->resolve(std::move(reply->body)); - } - }); - return std::move(completion); - }; -} + ::morph::exec::IExecutor* cbExec); /// @brief A file a download brought back. struct DownloadedFile { @@ -752,18 +360,13 @@ struct DownloadedFile { /// /// What it moves is bytes: reading the file the user picked is the platform's, and an application's /// `InterpreterHost::upload` reads it and hands the bytes here. -class FileTransfer { +class MORPH_API FileTransfer { public: /// @brief A transfer over @p exchange, its requests carrying @p session. /// @param exchange The transport. /// @param session The session every request carries. /// @throws std::invalid_argument for an empty @p exchange. - FileTransfer(Exchange exchange, ::morph::session::Context session) - : _shared{std::make_shared(Shared{.exchange = std::move(exchange), .session = std::move(session)})} { - if (!_shared->exchange) { - throw std::invalid_argument("FileTransfer: the exchange is empty"); - } - } + FileTransfer(Exchange exchange, ::morph::session::Context session); /// @brief Uploads a file, authorised as the mutation that will reference it. /// @param info Its name, type and size; `size` is taken from @p bytes. @@ -774,42 +377,14 @@ class FileTransfer { /// @param done Called once with the file's reference, or why the upload failed. void upload(FileInfo info, std::string bytes, std::string model, std::string action, std::function progress, - std::function)> done) const { - auto const run = std::make_shared(Upload{.shared = _shared, - .bytes = std::move(bytes), - .upload = {}, - .progress = std::move(progress), - .done = std::move(done)}); - FileRequest begin; - begin.op = "begin"; - begin.name = std::move(info.name); - begin.type = std::move(info.type); - begin.size = run->bytes.size(); - begin.model = std::move(model); - begin.action = std::move(action); - send(*_shared, begin, [run](std::expected reply) { - if (!reply || !reply->upload) { - run->fail(reply ? std::string{"the ui-file begin reply has no upload id"} : std::move(reply.error())); - return; - } - run->upload = std::move(*reply->upload); - sendChunk(run, 0); - }); - } + std::function)> done) const; /// @brief Downloads a file by its reference. /// @param ref The reference a reply carried. /// @param progress Called with 0 to 1 after each chunk; may be empty. /// @param done Called once with the file, or why the download failed. void download(std::string ref, std::function progress, - std::function)> done) const { - auto const run = std::make_shared(Download{.shared = _shared, - .ref = std::move(ref), - .file = {}, - .progress = std::move(progress), - .done = std::move(done)}); - readChunk(run); - } + std::function)> done) const; private: struct Shared { @@ -817,18 +392,14 @@ class FileTransfer { ::morph::session::Context session; }; - struct Upload { + struct MORPH_API Upload { std::shared_ptr shared; std::string bytes; std::string upload; std::function progress; std::function)> done; - void fail(std::string reason) const { - if (done) { - done(std::unexpected(std::move(reason))); - } - } + void fail(std::string reason) const; }; struct Download { @@ -841,94 +412,13 @@ class FileTransfer { /// Sends one `ui-file` request and hands its reply body, or why there is none, to @p then. static void send(Shared const& shared, FileRequest const& request, - std::function)> then) { - ::morph::wire::Envelope envelope; - envelope.kind = std::string{kFileKind}; - envelope.session = shared.session; - envelope.body = detail::writeMessage(request); - shared.exchange(std::move(envelope), [then = std::move(then)](ExchangeReply reply) { - if (!reply) { - then(std::unexpected(std::move(reply.error()))); - return; - } - if (reply->kind != "ok") { - then(std::unexpected(std::move(reply->message))); - return; - } - then(parseFileReply(reply->body)); - }); - } + std::function)> then); /// Sends the chunk at @p offset, then the next, then `end`. - static void sendChunk(std::shared_ptr const& run, std::size_t offset) { - if (offset >= run->bytes.size()) { - FileRequest end; - end.op = "end"; - end.upload = run->upload; - send(*run->shared, end, [run](std::expected reply) { - if (!reply || !reply->ref) { - run->fail(reply ? std::string{"the ui-file end reply has no reference"} - : std::move(reply.error())); - return; - } - if (run->done) { - run->done(std::move(*reply->ref)); - } - }); - return; - } - FileRequest chunk; - chunk.op = "chunk"; - chunk.upload = run->upload; - chunk.offset = offset; - std::string_view const all{run->bytes}; - chunk.data = ::morph::session::detail::base64UrlEncode(all.substr(offset, kMaxFileChunkBytes)); - send(*run->shared, chunk, [run](std::expected reply) { - if (!reply || !reply->received) { - run->fail(reply ? std::string{"the ui-file chunk reply has no count"} : std::move(reply.error())); - return; - } - if (run->progress) { - run->progress(static_cast(*reply->received) / static_cast(run->bytes.size())); - } - sendChunk(run, *reply->received); - }); - } + static void sendChunk(std::shared_ptr const& run, std::size_t offset); /// Reads the next chunk, until the whole file has arrived. - static void readChunk(std::shared_ptr const& run) { - FileRequest read; - read.op = "read"; - read.ref = run->ref; - read.offset = run->file.bytes.size(); - send(*run->shared, read, [run](std::expected reply) { - std::optional bytes; - if (reply && reply->data && reply->total) { - bytes = ::morph::session::detail::base64UrlDecode(*reply->data); - } - if (!bytes) { - if (run->done) { - run->done(std::unexpected(reply ? std::string{"the ui-file read reply is malformed"} - : std::move(reply.error()))); - } - return; - } - run->file.bytes += *bytes; - run->file.name = reply->name.value_or(""); - run->file.type = reply->type.value_or(""); - std::size_t const total = *reply->total; - if (run->progress && total > 0) { - run->progress(static_cast(run->file.bytes.size()) / static_cast(total)); - } - if (run->file.bytes.size() >= total || bytes->empty()) { - if (run->done) { - run->done(std::move(run->file)); - } - return; - } - readChunk(run); - }); - } + static void readChunk(std::shared_ptr const& run); std::shared_ptr _shared; }; diff --git a/src/ui/service_client.cpp b/src/ui/service_client.cpp new file mode 100644 index 000000000..1e4079d34 --- /dev/null +++ b/src/ui/service_client.cpp @@ -0,0 +1,623 @@ +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace morph::ui { + +std::optional MemoryBundleStore::get(std::string_view hash) const { + std::scoped_lock const lock{_mutex}; + auto const found = _files.find(hash); + if (found == _files.end()) { + return std::nullopt; + } + return found->second; +} + +void MemoryBundleStore::put(std::string const& hash, std::string bytes) { + std::scoped_lock const lock{_mutex}; + _files.insert_or_assign(hash, std::move(bytes)); +} + +void MemoryBundleStore::remove(std::string_view hash) { + std::scoped_lock const lock{_mutex}; + if (auto const found = _files.find(hash); found != _files.end()) { + _files.erase(found); + } +} + +std::optional MemoryBundleStore::lastDigest(std::string_view application) const { + std::scoped_lock const lock{_mutex}; + auto const found = _digests.find(application); + if (found == _digests.end()) { + return std::nullopt; + } + return found->second; +} + +void MemoryBundleStore::setLastDigest(std::string const& application, std::string digest) { + std::scoped_lock const lock{_mutex}; + _digests.insert_or_assign(application, std::move(digest)); +} + +std::size_t MemoryBundleStore::size() const { + std::scoped_lock const lock{_mutex}; + return _files.size(); +} + +VerifiedCache::VerifiedCache(std::shared_ptr store) : _store{std::move(store)} { + if (!_store) { + throw std::invalid_argument("VerifiedCache: the store is null"); + } +} + +std::optional VerifiedCache::get(std::string const& hash) { + auto bytes = _store->get(hash); + if (bytes && contentHash(*bytes) != hash) { + ::morph::log::logWarn("[ui-cache] dropped {}: the stored bytes do not hash to it", hash); + _store->remove(hash); + return std::nullopt; + } + return bytes; +} + +std::string VerifiedCache::put(std::string bytes) { + std::string hash = contentHash(bytes); + _store->put(hash, std::move(bytes)); + return hash; +} + +Exchange exchangeOver(::morph::backend::IEnvelopeTransport& backend MORPH_LIFETIMEBOUND, + ::morph::exec::IExecutor& cbExec MORPH_LIFETIMEBOUND) { + return [transport = &backend, owner = &cbExec](::morph::wire::Envelope request, + std::function done) { + auto const answer = std::make_shared>(std::move(done)); + transport->request(std::move(request), *owner) + .thenDetached([answer](::morph::wire::Envelope const& reply) { (*answer)(reply); }) + .onErrorDetached([answer](std::exception_ptr const& failure) { + std::string message = "the request was not delivered"; + try { + std::rethrow_exception(failure); + } catch (std::exception const& error) { + message = error.what(); + } catch (...) { // NOLINT(bugprone-empty-catch): the default message stands for a non-std failure + } + (*answer)(std::unexpected(std::move(message))); + }); + }; +} + +UiClient::UiClient(Exchange exchange, HelloRequest client, std::shared_ptr store) + : _shared{std::make_shared(std::move(exchange), std::move(client), VerifiedCache{std::move(store)})} { + if (!_shared->exchange) { + throw std::invalid_argument("UiClient: the exchange is empty"); + } +} + +void UiClient::open(::morph::session::Context session, Done done) const { + auto const run = std::make_shared(_shared, std::move(session), std::move(done)); + sendHello(run); +} + +void UiClient::poll(::morph::session::Context session, std::string knownDigest, PollDone done) const { + auto const answer = std::make_shared(std::move(done)); + auto const run = + std::make_shared(_shared, std::move(session), [answer](std::expected opened) { + if (!opened) { + (*answer)(std::unexpected(std::move(opened.error()))); + return; + } + (*answer)(std::optional{std::move(*opened)}); + }); + run->knownDigest = std::move(knownDigest); + run->unchanged = [answer] { (*answer)(std::optional{}); }; + sendHello(run); +} + +std::expected UiClient::openOffline(std::string_view application) const { + auto const digest = _shared->cache.store().lastDigest(application); + if (!digest) { + return std::unexpected( + ConnectError{.kind = ConnectError::Kind::Unreachable, + .message = "no verified bundle of `" + std::string{application} + "` is cached"}); + } + auto const text = _shared->cache.get(*digest); + if (!text) { + return std::unexpected(ConnectError{ + .kind = ConnectError::Kind::Unreachable, + .message = "the cached manifest of `" + std::string{application} + "` is gone or does not verify"}); + } + auto manifest = parseManifest(*text); + if (!manifest) { + return std::unexpected(ConnectError{.kind = ConnectError::Kind::Unsupported, .message = manifest.error()}); + } + LoadedBundle loaded; + loaded.manifest = std::move(*manifest); + for (ManifestFile const& file : loaded.manifest.files) { + if (!usable(_shared->client, file.kind)) { + continue; + } + if (auto bytes = _shared->cache.get(file.hash)) { + loaded.files.emplace(file.hash, std::move(*bytes)); + } + } + assemble(loaded, *digest); + return loaded; +} + +bool UiClient::usable(HelloRequest const& client, std::string_view kind) { + if (kind == kComponentFile) { + return client.components; + } + return kind == kScreenFile || kind == kAppFile || kind == kThemeFile || kind == kMessagesFile || kind == kIconFile; +} + +void UiClient::assemble(LoadedBundle& loaded, std::string const& digest) { + loaded.bundle.applicationId = loaded.manifest.application; + loaded.bundle.manifestDigest = digest.substr(kHashPrefix.size()); + for (ManifestFile const& file : loaded.manifest.files) { + if (file.kind != kScreenFile && file.kind != kAppFile && file.kind != kThemeFile) { + continue; + } + if (auto const found = loaded.files.find(file.hash); found != loaded.files.end()) { + auto& into = file.kind == kThemeFile ? loaded.bundle.themes : loaded.bundle.documents; + into.insert_or_assign(file.id, found->second); + } + } + // The icon set the theme index names, each icon's SVG by its name; a build refuses an index naming a file + // the bundle lacks. + for (auto const& [fileId, text] : loaded.bundle.themes) { + static_cast(fileId); + if (!isThemeIndex(text)) { + continue; + } + auto const index = parseThemeIndex(text); + if (!index) { + continue; + } + for (auto const& [name, iconId] : index->icons) { + auto const file = std::ranges::find_if(loaded.manifest.files, [&iconId](ManifestFile const& listed) { + return listed.kind == kIconFile && listed.id == iconId; + }); + if (file == loaded.manifest.files.end()) { + continue; + } + if (auto const found = loaded.files.find(file->hash); found != loaded.files.end()) { + loaded.bundle.icons.insert_or_assign(name, found->second); + } + } + } +} + +::morph::wire::Envelope UiClient::requestOf(std::shared_ptr const& run, std::string_view kind) { + ::morph::wire::Envelope request; + request.kind = std::string{kind}; + request.session = run->session; + return request; +} + +void UiClient::sendHello(std::shared_ptr const& run) { + ::morph::wire::Envelope request = requestOf(run, kHelloKind); + request.body = detail::writeMessage(run->shared->client); + run->shared->exchange(std::move(request), [run](ExchangeReply reply) { onHello(run, std::move(reply)); }); +} + +void UiClient::sendCatalog(std::shared_ptr const& run) { + run->shared->exchange(requestOf(run, kCatalogKind), + [run](ExchangeReply reply) { onCatalog(run, std::move(reply)); }); +} + +void UiClient::fetch(std::shared_ptr const& run, std::string const& hash, + std::function then) { + ::morph::wire::Envelope request = requestOf(run, kFetchKind); + request.body = detail::writeMessage(FetchRequest{.hash = hash}); + run->shared->exchange(std::move(request), std::move(then)); +} + +void UiClient::fail(std::shared_ptr const& run, ConnectError error) { + ::morph::log::logWarn("[ui-fetch] {}", error.message); + run->done(std::unexpected(std::move(error))); +} + +std::expected UiClient::bodyOf(ExchangeReply reply) { + if (!reply) { + return std::unexpected(ConnectError{.kind = ConnectError::Kind::Unreachable, .message = reply.error()}); + } + if (reply->kind != "ok") { + return std::unexpected( + ConnectError{.kind = ConnectError::Kind::Refused, .message = std::move(reply->message)}); + } + return std::move(reply->body); +} + +std::expected UiClient::verified(ExchangeReply reply, Expected const& expected) { + auto body = bodyOf(std::move(reply)); + if (!body) { + body.error().message = expected.what + ": " + body.error().message; + return body; + } + if (body->size() > kMaxFileBytes) { + return std::unexpected( + ConnectError{.kind = ConnectError::Kind::Unverified, + .message = expected.what + " is larger than " + std::to_string(kMaxFileBytes) + " bytes"}); + } + if (std::string const actual = contentHash(*body); actual != expected.hash) { + return std::unexpected(ConnectError{.kind = ConnectError::Kind::Unverified, + .message = expected.what + " does not match its hash (expected " + + expected.hash + ", got " + actual + ")"}); + } + return body; +} + +void UiClient::onHello(std::shared_ptr const& run, ExchangeReply reply) { + auto body = bodyOf(std::move(reply)); + if (!body) { + ConnectError error = std::move(body.error()); + if (error.message == "unknown envelope kind: " + std::string{kHelloKind}) { + error.kind = ConnectError::Kind::NoUiService; + error.message = "the server serves no UI"; + } else if (error.message.starts_with("missing vocabulary: ")) { + error.kind = ConnectError::Kind::Unsupported; + } + fail(run, std::move(error)); + return; + } + auto hello = parseHelloReply(*body); + if (!hello) { + fail(run, ConnectError::Kind::Unsupported, std::move(hello.error())); + return; + } + HelloRequest const& client = run->shared->client; + for (std::string const& vocabulary : hello->vocabularies) { + if (std::ranges::find(client.vocabularies, vocabulary) == client.vocabularies.end()) { + fail(run, ConnectError::Kind::Unsupported, + "the application needs the vocabulary " + vocabulary + ", which this client does not speak"); + return; + } + } + if (run->unchanged && hello->digest == run->knownDigest) { + ::morph::log::logDebug("[ui-fetch] polling `{}`: digest {}, known {}, manifest unchanged", hello->application, + hello->digest, run->knownDigest); + run->unchanged(); + return; + } + ::morph::log::logDebug("[ui-fetch] {} `{}`: digest {}, known {}, manifest {}", + run->unchanged ? "polling" : "opening", hello->application, hello->digest, + run->knownDigest.empty() ? std::string{""} : run->knownDigest, + hello->digest == run->knownDigest ? "unchanged" : "changed"); + run->loaded.hello = std::move(*hello); + std::string const& digest = run->loaded.hello.digest; + if (auto cached = run->shared->cache.get(digest)) { + onManifest(run, std::move(*cached)); + return; + } + fetch(run, digest, [run](ExchangeReply fetched) { + auto text = verified(std::move(fetched), Expected{.hash = run->loaded.hello.digest, .what = "the manifest"}); + if (!text) { + fail(run, std::move(text.error())); + return; + } + onManifest(run, std::move(*text)); + }); +} + +void UiClient::onManifest(std::shared_ptr const& run, std::string text) { + auto manifest = parseManifest(text); + if (!manifest) { + fail(run, ConnectError::Kind::Unsupported, std::move(manifest.error())); + return; + } + static_cast(run->shared->cache.put(std::move(text))); + run->loaded.manifest = std::move(*manifest); + sendCatalog(run); +} + +void UiClient::onCatalog(std::shared_ptr const& run, ExchangeReply reply) { + auto body = bodyOf(std::move(reply)); + if (!body) { + fail(run, std::move(body.error())); + return; + } + auto catalog = parseCatalogReply(*body); + if (!catalog) { + fail(run, ConnectError::Kind::Unsupported, std::move(catalog.error())); + return; + } + run->loaded.catalog = std::move(*catalog); + std::vector missing; + for (ManifestFile const& file : run->loaded.manifest.files) { + if (!wanted(run->shared->client, run->loaded.catalog, file)) { + continue; + } + if (auto cached = run->shared->cache.get(file.hash)) { + run->loaded.files.insert_or_assign(file.hash, std::move(*cached)); + } else { + Expected expected{.hash = file.hash, .what = "the " + file.kind + " `" + file.id + "`"}; + ::morph::log::logDebug("[ui-fetch] fetching {} ({})", expected.hash, expected.what); + missing.push_back(std::move(expected)); + } + } + // One count for each fetch and one for this loop, so a synchronous exchange that answers every fetch + // before the next is sent cannot settle the run early. + run->pending = missing.size() + 1; + for (Expected& expected : missing) { + std::string const hash = expected.hash; + fetch(run, hash, [run, expected = std::move(expected)](ExchangeReply fetched) { + auto bytes = verified(std::move(fetched), expected); + { + std::scoped_lock const lock{run->mutex}; + if (!bytes) { + if (!run->failure) { + run->failure = std::move(bytes.error()); + } + } else { + static_cast(run->shared->cache.put(*bytes)); + run->loaded.files.insert_or_assign(expected.hash, std::move(*bytes)); + } + } + settle(run); + }); + } + settle(run); +} + +bool UiClient::wanted(HelloRequest const& client, CatalogReply const& catalog, ManifestFile const& file) { + if (!usable(client, file.kind)) { + return false; + } + if (file.kind != kScreenFile) { + return true; + } + return std::ranges::any_of(catalog.entries, [&file](CatalogEntry const& entry) { + return entry.id == file.id && (entry.available || entry.isPublic); + }); +} + +void UiClient::settle(std::shared_ptr const& run) { + { + std::scoped_lock const lock{run->mutex}; + if (--run->pending != 0) { + return; + } + } + // Past the last count nothing else touches the run, so it is read without the lock. + if (run->failure) { + fail(run, std::move(*run->failure)); + return; + } + assemble(run->loaded, run->loaded.hello.digest); + run->shared->cache.store().setLastDigest(run->loaded.hello.application, run->loaded.hello.digest); + run->done(std::move(run->loaded)); +} + +std::expected evaluationValue(ExchangeReply reply) { + if (!reply) { + return std::unexpected(std::move(reply.error())); + } + if (reply->kind != "ok") { + return std::unexpected(std::move(reply->message)); + } + auto evaluated = parseEvaluateReply(reply->body); + if (!evaluated) { + return std::unexpected(std::move(evaluated.error())); + } + Json::object_t errors; + for (auto const& [field, message] : evaluated->errors) { + errors.insert_or_assign(field, Json(message)); + } + auto& members = evaluated->body.get(); + members.insert_or_assign("errors", Json(std::move(errors))); + members.insert_or_assign("ready", Json(evaluated->ready)); + auto text = glz::write_json(evaluated->body); + if (!text) { + return std::unexpected("the ui-evaluate reply's body cannot be written"); + } + return std::move(*text); +} + +std::function<::morph::async::Completion(std::string const&, std::string const&, std::string const&)> +evaluatorOver(Exchange exchange, ::morph::session::Context session, ::morph::exec::IExecutor* cbExec) { + return [exchange = std::move(exchange), session = std::move(session), cbExec]( + std::string const& typeId, std::string const& actionId, std::string const& bodyJson) { + auto [completion, promise] = ::morph::async::Completion::makeSettleable(cbExec); + auto settle = std::make_shared(std::move(promise)); + ::morph::wire::Envelope request; + request.kind = std::string{kEvaluateKind}; + request.session = session; + request.modelType = typeId; + request.actionType = actionId; + request.body = bodyJson; + exchange(std::move(request), [settle](ExchangeReply reply) { + auto value = evaluationValue(std::move(reply)); + if (value) { + settle->resolve(std::move(*value)); + } else { + settle->reject(std::make_exception_ptr(std::runtime_error{value.error()})); + } + }); + return std::move(completion); + }; +} + +std::function<::morph::async::Completion(std::string const&, std::string const&)> watcherOver( + Exchange exchange, std::function<::morph::session::Context()> currentSession, ::morph::exec::IExecutor* cbExec) { + return [exchange = std::move(exchange), currentSession = std::move(currentSession), cbExec]( + std::string const& kind, std::string const& bodyJson) { + auto [completion, promise] = ::morph::async::Completion::makeSettleable(cbExec); + auto settle = std::make_shared(std::move(promise)); + ::morph::wire::Envelope request; + request.kind = kind; + request.session = currentSession ? currentSession() : ::morph::session::Context{}; + request.body = bodyJson; + exchange(std::move(request), [settle](ExchangeReply reply) { + if (!reply) { + settle->reject(std::make_exception_ptr(std::runtime_error{reply.error()})); + } else if (reply->kind != "ok") { + settle->reject(std::make_exception_ptr(std::runtime_error{reply->message})); + } else { + settle->resolve(std::move(reply->body)); + } + }); + return std::move(completion); + }; +} + +FileTransfer::FileTransfer(Exchange exchange, ::morph::session::Context session) + : _shared{std::make_shared(Shared{.exchange = std::move(exchange), .session = std::move(session)})} { + if (!_shared->exchange) { + throw std::invalid_argument("FileTransfer: the exchange is empty"); + } +} + +void FileTransfer::upload(FileInfo info, std::string bytes, std::string model, std::string action, + std::function progress, + std::function)> done) const { + auto const run = std::make_shared(Upload{.shared = _shared, + .bytes = std::move(bytes), + .upload = {}, + .progress = std::move(progress), + .done = std::move(done)}); + FileRequest begin; + begin.op = "begin"; + begin.name = std::move(info.name); + begin.type = std::move(info.type); + begin.size = run->bytes.size(); + begin.model = std::move(model); + begin.action = std::move(action); + send(*_shared, begin, [run](std::expected reply) { + if (!reply || !reply->upload) { + run->fail(reply ? std::string{"the ui-file begin reply has no upload id"} : std::move(reply.error())); + return; + } + run->upload = std::move(*reply->upload); + sendChunk(run, 0); + }); +} + +void FileTransfer::download(std::string ref, std::function progress, + std::function)> done) const { + auto const run = std::make_shared(Download{.shared = _shared, + .ref = std::move(ref), + .file = {}, + .progress = std::move(progress), + .done = std::move(done)}); + readChunk(run); +} + +void FileTransfer::Upload::fail(std::string reason) const { + if (done) { + done(std::unexpected(std::move(reason))); + } +} + +void FileTransfer::send(Shared const& shared, FileRequest const& request, + std::function)> then) { + ::morph::wire::Envelope envelope; + envelope.kind = std::string{kFileKind}; + envelope.session = shared.session; + envelope.body = detail::writeMessage(request); + shared.exchange(std::move(envelope), [then = std::move(then)](ExchangeReply reply) { + if (!reply) { + then(std::unexpected(std::move(reply.error()))); + return; + } + if (reply->kind != "ok") { + then(std::unexpected(std::move(reply->message))); + return; + } + then(parseFileReply(reply->body)); + }); +} + +void FileTransfer::sendChunk(std::shared_ptr const& run, std::size_t offset) { + if (offset >= run->bytes.size()) { + FileRequest end; + end.op = "end"; + end.upload = run->upload; + send(*run->shared, end, [run](std::expected reply) { + if (!reply || !reply->ref) { + run->fail(reply ? std::string{"the ui-file end reply has no reference"} : std::move(reply.error())); + return; + } + if (run->done) { + run->done(std::move(*reply->ref)); + } + }); + return; + } + FileRequest chunk; + chunk.op = "chunk"; + chunk.upload = run->upload; + chunk.offset = offset; + std::string_view const all{run->bytes}; + chunk.data = ::morph::session::detail::base64UrlEncode(all.substr(offset, kMaxFileChunkBytes)); + send(*run->shared, chunk, [run](std::expected reply) { + if (!reply || !reply->received) { + run->fail(reply ? std::string{"the ui-file chunk reply has no count"} : std::move(reply.error())); + return; + } + if (run->progress) { + run->progress(static_cast(*reply->received) / static_cast(run->bytes.size())); + } + sendChunk(run, *reply->received); + }); +} + +void FileTransfer::readChunk(std::shared_ptr const& run) { + FileRequest read; + read.op = "read"; + read.ref = run->ref; + read.offset = run->file.bytes.size(); + send(*run->shared, read, [run](std::expected reply) { + std::optional bytes; + if (reply && reply->data && reply->total) { + bytes = ::morph::session::detail::base64UrlDecode(*reply->data); + } + if (!bytes) { + if (run->done) { + run->done(std::unexpected(reply ? std::string{"the ui-file read reply is malformed"} + : std::move(reply.error()))); + } + return; + } + run->file.bytes += *bytes; + run->file.name = reply->name.value_or(""); + run->file.type = reply->type.value_or(""); + std::size_t const total = *reply->total; + if (run->progress && total > 0) { + run->progress(static_cast(run->file.bytes.size()) / static_cast(total)); + } + if (run->file.bytes.size() >= total || bytes->empty()) { + if (run->done) { + run->done(std::move(run->file)); + } + return; + } + readChunk(run); + }); +} +} // namespace morph::ui From 8077da674623ad7b40b5dc5020c899ede18bebc8 Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 01:27:55 +0100 Subject: [PATCH 10/38] Move the screen host's non-template code into src/ui/host.cpp DocumentScreenHost's and the nested screen classes' member bodies of two or more lines move to the compiled library, along with identityKey, sameIdentity and titleText, which keep documented declarations in the header because workspace_model.hpp, the tests and the header's own lambdas call them. ParamsEnv has no user outside the moved bodies and lives in the .cpp's unnamed namespace. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- CMakeLists.txt | 1 + include/morph/ui/host.hpp | 625 +++--------------------------------- src/ui/host.cpp | 656 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 709 insertions(+), 573 deletions(-) create mode 100644 src/ui/host.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 0d6869b0d..2bc606baf 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -417,6 +417,7 @@ add_library(morph STATIC src/ui/interpreter.cpp src/ui/library.cpp src/ui/service.cpp + src/ui/host.cpp src/ui/service_client.cpp ) add_library(morph::morph ALIAS morph) diff --git a/include/morph/ui/host.hpp b/include/morph/ui/host.hpp index 75abc6b06..c8be33779 100644 --- a/include/morph/ui/host.hpp +++ b/include/morph/ui/host.hpp @@ -7,6 +7,7 @@ #include #include #include +#include #include #include #include @@ -55,7 +56,7 @@ struct MountError { /// /// The head is data: the screen evaluates it and the shell draws it, so a host screen's handle can implement it too. /// The menu and tool members have defaults, for a head that has neither. -class ScreenHead { +class MORPH_API ScreenHead { public: ScreenHead() = default; ScreenHead(ScreenHead const&) = delete; @@ -146,10 +147,7 @@ class ScreenHead { /// @param entryId The entry's id. /// @return Whether it ran: `false`, with a diagnostic, for an id the menu does not hold enabled and visible, and /// `false` for a closed screen or a head without a menu. - virtual bool choose(std::string_view entryId) { - static_cast(entryId); - return false; - } + virtual bool choose(std::string_view entryId); /// @brief The head's tools that are visible, in order: search fields and selects, each with its value. /// @return They, valid as long as the head; null for a head that has no tools, as a host screen's by default. @@ -162,28 +160,21 @@ class ScreenHead { /// @param value A search's text, or a select's key. /// @return Whether it ran: `false`, with a diagnostic, for an id the head does not hold enabled and visible, and /// `false` for a closed screen or a head without tools. - virtual bool edit(std::string_view toolId, Value const& value) { - static_cast(toolId); - static_cast(value); - return false; - } + virtual bool edit(std::string_view toolId, Value const& value); /// @brief Reports a user's submit of a search tool: runs its `onSubmit` with `event` its text, as a user event in /// the screen scope, in one batch. /// @param toolId The tool's id. /// @return Whether it ran: `false`, with a diagnostic, for an id the head does not hold enabled and visible, or /// holds as a select, and `false` for a closed screen or a head without tools. - virtual bool submit(std::string_view toolId) { - static_cast(toolId); - return false; - } + virtual bool submit(std::string_view toolId); }; /// @brief One mounted screen, as its host sees it. /// /// The host reads `title`, `dirty` and `identity` to show the tab and the unsaved indicator, and closes the screen /// through `requestClose`. It never destroys a handle whose close is pending, except after `forceClose`. -class ScreenHandle { +class MORPH_API ScreenHandle { public: ScreenHandle() = default; ScreenHandle(ScreenHandle const&) = delete; @@ -234,11 +225,7 @@ class ScreenHandle { /// called when the screen closes before the save has finished. /// @param done Called with whether the screen is clean. // NOLINTNEXTLINE(performance-unnecessary-value-param): the base only calls it; overrides keep it. - virtual void save(std::function done) { - if (done) { - done(false); - } - } + virtual void save(std::function done); }; /// @brief What mounts screens for a host that owns its own shell; the workspace shell is one. @@ -281,7 +268,7 @@ using HostScreenFactory = std::functionsecond; - } + [[nodiscard]] HostScreenFactory const* find(std::string_view name) const; private: std::map> _factories; @@ -336,85 +320,10 @@ struct DocumentScreenHostOptions { namespace detail::host { -/// The environment `identityOf` evaluates in: the params, and nothing else. Reading anything else marks it unknown. -class ParamsEnv final : public Environment { -public: - /// @brief An environment over @p params. - /// @param params The params; borrowed for the environment's lifetime. - explicit ParamsEnv(ParamMap const& params) : _params{¶ms} {} - - [[nodiscard]] Value ref(std::string_view head, std::span path) const override { - auto const found = _params->find(head); - if (found == _params->end()) { - _unknown = true; - return Value{}; - } - Value value = found->second; - for (std::string const& step : path) { - ValueRecord const* const record = value.asRecord(); - if (record == nullptr || !record->contains(step)) { - return Value{}; - } - value = record->at(step); - } - return value; - } - - [[nodiscard]] Value row(std::span path) const override { return unknown(path); } - - [[nodiscard]] Value control(ExprKind form, std::string_view name) const override { - static_cast(form); - static_cast(name); - _unknown = true; - return Value{}; - } - - [[nodiscard]] Value pref(std::string_view point, std::span path) const override { - static_cast(point); - return unknown(path); - } - - [[nodiscard]] Value client(ExprKind form, std::string_view name) const override { - static_cast(form); - static_cast(name); - _unknown = true; - return Value{}; - } - - [[nodiscard]] FormatContext const& formatting() const override { return _formatting; } - - // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): Environment's signature. - void report(std::string_view path, std::string_view reason) const override { - static_cast(path); - static_cast(reason); - _unknown = true; - } - - /// @brief Whether the evaluation read anything but the params, or failed. - /// @return It. - [[nodiscard]] bool unknown() const noexcept { return _unknown; } - -private: - [[nodiscard]] Value unknown(std::span path) const { - static_cast(path); - _unknown = true; - return Value{}; - } - - ParamMap const* _params; - FormatContext _formatting; - mutable bool _unknown = false; -}; - /// @brief The text a title value shows. /// @param value The title's value. /// @return A string as is, `null` as empty, anything else as its canonical JSON. -[[nodiscard]] inline std::string titleText(Value const& value) { - if (std::string const* const text = value.asString()) { - return *text; - } - return value.isNull() ? std::string{} : ::morph::ui::detail::canonicalJson(value); -} +[[nodiscard]] MORPH_API std::string titleText(Value const& value); } // namespace detail::host @@ -423,21 +332,13 @@ class ParamsEnv final : public Environment { /// those params would open. /// @param identity The identity value. /// @return Its JSON with record fields in name order, or `std::nullopt` for `null` (a screen without an identity). -[[nodiscard]] inline std::optional identityKey(Value const& identity) { - if (identity.isNull()) { - return std::nullopt; - } - return detail::canonicalJson(identity); -} +[[nodiscard]] MORPH_API std::optional identityKey(Value const& identity); /// @brief Whether two identities name the same screen instance: their keys are equal, and neither is `null`. /// @param lhs One identity. /// @param rhs The other. /// @return True when both have a key and the keys are equal; `null` equals nothing, itself included. -[[nodiscard]] inline bool sameIdentity(Value const& lhs, Value const& rhs) { - std::optional const left = identityKey(lhs); - return left.has_value() && left == identityKey(rhs); -} +[[nodiscard]] MORPH_API bool sameIdentity(Value const& lhs, Value const& rhs); /// @brief The framework's `ScreenHost` over UI documents: it mounts them through an `Interpreter`, closes them by the /// protocol of spec 6 §3, and hands a document's `navigate` to `onNavigate`, which the deriving host @@ -445,7 +346,7 @@ class ParamsEnv final : public Environment { /// /// It is the interpreter's `InterpreterHost` for `navigate`; every other command goes to the application's host, if /// one was given. Everything runs on the runtime's owner. -class DocumentScreenHost : public ScreenHost, private InterpreterHost { +class MORPH_API DocumentScreenHost : public ScreenHost, private InterpreterHost { public: /// @brief A host over @p session and @p dispatcher. /// @param session The session the screens share. Borrowed: it outlives the host. @@ -453,17 +354,7 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { /// @param options The documents, the backend, the close guard and the application's host. /// @throws std::invalid_argument without a document lookup or a backend. DocumentScreenHost(Session& session MORPH_LIFETIMEBOUND, Dispatcher& dispatcher MORPH_LIFETIMEBOUND, - DocumentScreenHostOptions options) - : _options{std::move(options)}, - _session{&session}, - _dispatcher{&dispatcher}, - _interpreter{ - session, dispatcher, - InterpreterOptions{.host = static_cast(this), .diagnostics = _options.diagnostics}} { - if (!_options.documents || _options.backend == nullptr) { - throw std::invalid_argument("DocumentScreenHost: a document lookup and a backend are required"); - } - } + DocumentScreenHostOptions options); /// @brief Mounts a document screen. /// @param screenId The screen id. @@ -495,35 +386,14 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { /// @return The root, or why it was refused: no document, a document whose id is not `app`, or a second root on /// the session. [[nodiscard]] std::expected, MountError> mountApp( - std::shared_ptr document) { - if (!document) { - return std::unexpected(MountError{.screenId = "app", .reason = "no app document"}); - } - std::string const documentId = document->id; - auto root = _interpreter.mountApp(std::move(document)); - if (!root) { - return std::unexpected(mountErrorOf(documentId, root.error())); - } - return std::move(*root); - } + std::shared_ptr document); /// @brief The identity a document screen would have with @p params: its `identity` evaluated over the params. /// @param screenId The screen id. /// @param params The params. /// @return Its canonical text, or `std::nullopt` for an unknown screen, one without `identity`, or one whose /// identity reads more than its params or is `null`. - [[nodiscard]] std::optional identityOf(std::string_view screenId, ParamMap const& params) override { - std::shared_ptr const document = _options.documents(screenId); - if (!document || !document->identity) { - return std::nullopt; - } - detail::host::ParamsEnv const env{params}; - Value const identity = evaluate(*document->identity, env); - if (env.unknown()) { - return std::nullopt; - } - return identityKey(identity); - } + [[nodiscard]] std::optional identityOf(std::string_view screenId, ParamMap const& params) override; /// @brief Starts the requests of a screen's `prefetch` queries before it mounts (spec 5 §5), so the screen mounts /// on a warm cache: what a shell does when the pointer rests on an entry for a screen that is not open. @@ -535,47 +405,14 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { /// params, and an entry that is already fresh or in flight. /// @param screenId The screen id; an unknown one does nothing. /// @param params The params it would mount with. - void prefetch(std::string_view screenId, ParamMap const& params) { - std::shared_ptr const document = _options.documents(screenId); - if (!document) { - return; - } - for (std::string const& name : document->prefetch) { - auto const query = std::ranges::find(document->scope.queries, name, &QueryDecl::name); - if (query == document->scope.queries.end() || query->evaluate) { - continue; - } - auto const model = std::ranges::find(document->scope.models, query->model, &ModelDecl::name); - if (model == document->scope.models.end()) { - continue; - } - std::optional const binding = bindingOf(*model, params); - if (!binding) { - continue; - } - detail::host::ParamsEnv const env{params}; - Value const body = query->body ? evaluate(*query->body, env) : Value{ValueRecord{}}; - if (env.unknown()) { - continue; - } - std::shared_ptr const channel = - _dispatcher->bind(model->type, binding->sharing, binding->instanceKey); - _session->prefetch(channel, binding->token, model->type, query->action, body); - } - } + void prefetch(std::string_view screenId, ParamMap const& params); /// @brief The route of a screen instance (spec 6 §20): `routeOf` over the screen's declared params. /// @param screenId The screen id. /// @param params Its params. /// @return The route, or why it has none: an unknown screen, or a param with no route form. [[nodiscard]] std::expected routeOf(std::string_view screenId, - ParamMap const& params) const { - std::shared_ptr const document = _options.documents(screenId); - if (!document) { - return std::unexpected("unknown screen `" + std::string{screenId} + "`"); - } - return ::morph::ui::routeOf(*document, params); - } + ParamMap const& params) const; /// @brief Reads a route back against the screen it names (`parseRoute` over this host's documents). /// @param route The route. @@ -587,10 +424,7 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { /// @brief A document asked to open another screen, with how (`as`). The default hands the screen and its params /// to `onNavigate(screenId, params)`; a host that shows dialogs, drawers or windows overrides this one. /// @param request The request: screen, params, `as`. - virtual void onNavigate(NavigateRequest const& request) { - ValueRecord const* const params = request.params.asRecord(); - onNavigate(request.screen, params == nullptr ? ParamMap{} : *params); - } + virtual void onNavigate(NavigateRequest const& request); using ScreenHost::onNavigate; @@ -610,39 +444,13 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { /// @return Nothing, or why the old screen was kept: a foreign or closed handle, a close or save in progress, or /// the interpreter's refusal of the new document. [[nodiscard]] std::expected remount(ScreenHandle& handle, - std::shared_ptr document) { - auto* const own = dynamic_cast(&handle); - if (own == nullptr || !document) { - return std::unexpected(MountError{.screenId = document ? document->id : std::string{}, - .reason = "not a document screen of this host"}); - } - return own->remount(_interpreter, std::move(document), *_options.backend); - } + std::shared_ptr document); /// @brief What a chat turn says about a screen this host mounted: its id and title, its params and identity, and /// the aliases of its own scope that hold an instance. `TurnRequest::text` is left for the caller. /// @param handle A handle this host mounted. /// @return The context; nothing for a closed or foreign handle. - [[nodiscard]] static std::optional chatContext(ScreenHandle& handle) { - auto const* const own = dynamic_cast(&handle); - Screen const* const screen = own == nullptr ? nullptr : own->screen(); - if (screen == nullptr) { - return std::nullopt; - } - chat::TurnRequest context; - context.screenId = screen->id(); - context.title = handle.title().peek(); - context.identity = identityKey(handle.identity().peek()).value_or(std::string{}); - context.paramsJson = glz::write_json(valueToJson(Value{own->params()})).value_or(std::string{"{}"}); - for (Screen::BoundAlias const& alias : screen->boundAliases()) { - context.models.push_back(chat::ModelRef{.path = alias.decl->path, - .alias = alias.decl->name, - .modelType = alias.decl->type, - .instanceId = alias.facts.instanceId, - .primary = alias.facts.primary}); - } - return context; - } + [[nodiscard]] static std::optional chatContext(ScreenHandle& handle); /// @brief The development inspector over a screen this host mounted (spec 6 §21): what a shell's inspector window /// reads. It hands out no access to the screen beyond the inspector's own read-only view and its @@ -650,31 +458,17 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { /// @param handle A handle this host mounted. /// @return The inspector, valid until the screen closes or is remounted; nothing for a closed or foreign handle, /// and nothing for a screen whose session has `DevelopmentTools::Off`. - [[nodiscard]] static std::optional inspector(ScreenHandle& handle) { - auto const* const own = dynamic_cast(&handle); - Screen* const screen = own == nullptr ? nullptr : own->screen(); - if (screen == nullptr) { - return std::nullopt; - } - return Inspector::over(*screen); - } + [[nodiscard]] static std::optional inspector(ScreenHandle& handle); /// @brief Cancels every call no mount has adopted: each one's `onCancel` runs, oldest first. What a shell does /// when it closes every screen, so no call outlives the screens it was filed among and a later mount never /// answers an opener that is gone. - void cancelUnclaimedCalls() { - for (std::shared_ptr const& call : std::exchange(_unclaimed, {})) { - call->answer(std::nullopt); - } - } + void cancelUnclaimedCalls(); /// @brief The root widget of a handle this host mounted, which a host places in its own layout. /// @param handle A handle this host mounted. /// @return Its root widget, or `nullptr` for a closed or foreign handle. - [[nodiscard]] static Widget* rootOf(ScreenHandle const& handle) { - auto const* const own = dynamic_cast(&handle); - return own == nullptr ? nullptr : own->root(); - } + [[nodiscard]] static Widget* rootOf(ScreenHandle const& handle); protected: /// @brief Answers with a cancel the call of a navigation this host handled without mounting a document screen: @@ -687,23 +481,7 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { /// those params, opened for any reason, would answer an opener that never opened it. /// @param screenId The screen the navigation named. /// @param params Its params. - void settleCall(std::string_view screenId, ParamMap const& params) { - auto const found = std::ranges::find_if(_unclaimed, [&](std::shared_ptr const& call) { - return call->screen == screenId && call->params == params; - }); - if (found == _unclaimed.end()) { - return; - } - std::shared_ptr const call = std::move(*found); - _unclaimed.erase(found); - if (_options.diagnostics) { - _options.diagnostics(Refusal{ - .document = std::string{screenId}, - .path = {}, - .reason = "navigate to " + std::string{screenId} + " mounted no screen; its call was cancelled"}); - } - call->answer(std::nullopt); - } + void settleCall(std::string_view screenId, ParamMap const& params); private: // How a prefetch reaches the instance the mounted screen's alias will bind. @@ -714,94 +492,37 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { }; // The binding of @p model over @p params, or nothing for an instance the mounted screen will not share. - [[nodiscard]] std::optional bindingOf(ModelDecl const& model, ParamMap const& params) const { - InstanceMode mode = model.instance; - if (mode == InstanceMode::Default) { - Catalog const& catalog = _session->options().catalog; - std::optional const info = catalog.model ? catalog.model(model.type) : std::nullopt; - mode = info && info->stateless ? InstanceMode::Shared : InstanceMode::Private; - } - if (mode == InstanceMode::Shared) { - return Binding{.token = "shared", .sharing = bridge::BindSharing::Private, .instanceKey = {}}; - } - if (mode != InstanceMode::Keyed || !model.key) { - return std::nullopt; - } - detail::host::ParamsEnv const env{params}; - std::string const key = detail::instanceKeyText(evaluate(*model.key, env)); - if (env.unknown() || key.empty()) { - return std::nullopt; - } - return Binding{.token = "shared:" + key, .sharing = bridge::BindSharing::Shared, .instanceKey = key}; - } + [[nodiscard]] std::optional bindingOf(ModelDecl const& model, ParamMap const& params) const; // The mount itself, under @p parent or as a backend root. std::expected, MountError> mountAt(std::string_view screenId, ParamMap const& params, - ContainerWidget* parent) { - std::shared_ptr document = _options.documents(screenId); - if (!document) { - return std::unexpected(MountError{.screenId = std::string{screenId}, .reason = "unknown screen"}); - } - auto screen = - _interpreter.mount(std::move(document), params, *_options.backend, MountOptions{.parent = parent}); - if (!screen) { - return std::unexpected(mountErrorOf(screenId, screen.error())); - } - auto handle = std::make_unique(std::move(*screen), _options.guard, _options.saveFailed); - handle->placed(params, parent); - adoptCall(*handle, screenId, params); - return handle; - } + ContainerWidget* parent); // The interpreter's refusal of a mount, as the host reports it. - [[nodiscard]] static MountError mountErrorOf(std::string_view screenId, Refusal const& refusal) { - std::string reason = refusal.reason; - if (!refusal.path.empty()) { - reason = refusal.path + ": " + reason; - } - return MountError{.screenId = std::string{screenId}, .reason = std::move(reason)}; - } + [[nodiscard]] static MountError mountErrorOf(std::string_view screenId, Refusal const& refusal); /// A screen opened to answer its opener (spec 6 §16): answered exactly once, by `return`, by `close: self`, or by /// the screen closing any other way, which is a cancel. - struct Call { + struct MORPH_API Call { std::string screen; ParamMap params; std::function onResult; std::function onCancel; bool answered = false; - void answer(std::optional result) { - if (answered) { - return; - } - answered = true; - if (result) { - if (onResult) { - onResult(std::move(*result)); - } - } else if (onCancel) { - onCancel(); - } - } + void answer(std::optional result); }; /// The handle of a document screen. Its state is shared with the posts it makes, so a post that runs after the /// handle is gone finds the screen already closed. - class Handle final : public ScreenHandle, public ScreenHead { + class MORPH_API Handle final : public ScreenHandle, public ScreenHead { public: Handle(std::unique_ptr screen, CloseGuard guard, std::function saveFailed) : _state{std::make_shared(std::move(screen), std::move(guard), std::move(saveFailed))} { _state->self = this; } - ~Handle() override { - _state->self = nullptr; - try { - _state->finish(true); - } catch (...) { // NOLINT(bugprone-empty-catch): a destructor has no one to report to; the screen is gone. - } - } + ~Handle() override; Handle(Handle const&) = delete; Handle& operator=(Handle const&) = delete; @@ -879,53 +600,19 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { [[nodiscard]] ParamMap const& params() const { return _state->params; } /// Records what the screen was mounted with, so a remount mounts the same instance in the same place. - void placed(ParamMap params, ContainerWidget* parent) { - _state->params = std::move(params); - _state->parent = parent; - } + void placed(ParamMap params, ContainerWidget* parent); /// Mounts @p document with the screen's params, keeping its state by name and type, and replaces the /// screen with it; on a refusal the screen stays as it was. std::expected remount(Interpreter& interpreter, std::shared_ptr document, - IViewBackend& backend) { - State& state = *_state; - std::string const screenId = document->id; - if (!state.screen) { - return std::unexpected(MountError{.screenId = screenId, .reason = "the screen is closed"}); - } - if (state.closing || state.saved.effect) { - return std::unexpected(MountError{.screenId = screenId, .reason = "the screen is closing or saving"}); - } - auto next = interpreter.mount(std::move(document), state.params, backend, - MountOptions{.parent = state.parent, .keepStateOf = state.screen.get()}); - if (!next) { - return std::unexpected(mountErrorOf(screenId, next.error())); - } - // The old screen goes after the new one has mounted, so its root widget is never missing in between; - // destroying it runs its `onUnmount`. - std::unique_ptr const replaced = std::exchange(state.screen, std::move(*next)); - state.runtime->batch([&state] { state.generation.set(state.generation.peek() + 1); }); - return {}; - } + IViewBackend& backend); /// The call this screen answers, if it was opened as one. void answers(std::shared_ptr call) { _state->call = std::move(call); } /// Closes the screen after its own `return` or `close: self` has answered: posted, since the command that /// asked for it is still running in the screen. - void closeItself(std::function closed) { - std::weak_ptr const weak = _state; - _state->runtime->owner().post([weak, closed = std::move(closed)] { - auto const held = weak.lock(); - if (!held || !held->screen) { - return; - } - held->finish(true); - if (held->self != nullptr && closed) { - closed(*held->self); - } - }); - } + void closeItself(std::function closed); /// Whether this screen answers @p call and is still open. [[nodiscard]] bool answering(std::shared_ptr const& call) const { @@ -933,7 +620,7 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { } private: - struct State { + struct MORPH_API State { /// Whether the screen is mounted and its reads are current. [[nodiscard]] bool live() const { return !closed.get() && generation.get() >= 0; } @@ -1000,37 +687,7 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { ~State() = default; /// Starts a close, or joins the one in progress. - static void request(std::shared_ptr const& state, std::function done) { - if (!state->screen) { - state->post({std::move(done)}, true); - return; - } - state->waiting.push_back(std::move(done)); - if (state->closing) { - return; - } - state->closing = true; - std::shared_ptr const cancelled = state->screen->beginClose(); - if (cancelled == nullptr) { - bool const isDirty = state->screen->dirty(); - if (!isDirty) { - state->finish(true); - } else if (state->guard && state->self != nullptr) { - std::weak_ptr const weak = state; - state->guard(*state->self, [weak](CloseChoice choice) { - if (auto const held = weak.lock()) { - choose(held, choice); - } - }); - } else { - state->decide(false); - } - return; - } - // Closes once onClose and everything it started has ended, unless it ran cancelClose. - whenSettled(state, &State::settled, - [cancelled](State& settledState) { settledState.decide(!*cancelled); }); - } + static void request(std::shared_ptr const& state, std::function done); /// A wait for the screen to have nothing pending; the id tells a posted task whether it is still current. struct Watch { @@ -1044,138 +701,25 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { /// settled the work (a mutation's `onSuccess`) have run. @p slot holds the watch; resetting it, or closing /// the screen, cancels it. static void whenSettled(std::shared_ptr const& state, Watch State::* slot, - std::function then) { - std::weak_ptr const weak = state; - std::uint64_t const watchId = ++state->watches; - Watch& watch = state.get()->*slot; - watch.id = watchId; - watch.effect = - std::make_unique(*state->runtime, [weak, slot, watchId, then = std::move(then)] { - auto const held = weak.lock(); - if (!held || !held->screen || held->screen->pending()) { - return; - } - held->runtime->owner().post([weak, slot, watchId, then] { - auto const again = weak.lock(); - if (!again || !again->screen || (again.get()->*slot).id != watchId) { - return; - } - again.get()->*slot = Watch{}; - then(*again); - }); - }); - } + std::function then); /// Whether the screen is open and declares `onSave`. [[nodiscard]] bool canSave() const { return screen && screen->declares("onSave"); } /// Runs `onSave`, or joins the save in progress, and answers once nothing is pending. - static void save(std::shared_ptr const& state, std::function done) { - if (!state->canSave()) { - if (done) { - done(false); - } - return; - } - if (state->saved.effect) { - state->saving.push_back(std::move(done)); - return; - } - state->screen->runLifecycle("onSave"); - state->saving.push_back(std::move(done)); - // Answered in the settled task itself rather than posted again, so an answer never reaches a handle - // that closed in between; an answer that closes the screen ends the answering. - whenSettled(state, &State::saved, [](State& savedState) { - bool const clean = !savedState.screen->dirty(); - for (auto const& answer : std::exchange(savedState.saving, {})) { - if (!savedState.screen) { - return; - } - if (answer) { - answer(clean); - } - } - }); - } + static void save(std::shared_ptr const& state, std::function done); /// Carries out the guard's choice for the close in progress. - static void choose(std::shared_ptr const& state, CloseChoice choice) { - if (!state->closing) { - return; - } - if (choice != CloseChoice::Save || !state->canSave()) { - state->decide(choice == CloseChoice::Discard); - return; - } - std::weak_ptr const weak = state; - save(state, [weak](bool clean) { - auto const held = weak.lock(); - if (!held) { - return; - } - if (!clean && held->saveFailed && held->self != nullptr) { - held->saveFailed(*held->self); - } - held->decide(clean); - }); - } + static void choose(std::shared_ptr const& state, CloseChoice choice); /// Ends the close in progress: closes the screen or keeps it open, and answers every request. - void decide(bool close) { - if (!closing) { - return; - } - if (close) { - finish(true); - return; - } - closing = false; - post(std::exchange(waiting, {}), false); - } + void decide(bool close); /// Closes the screen now, answering every pending request with `true`. - void finish(bool answer) { - settled = {}; - saved = {}; - saving.clear(); // a save outlived by its screen is never answered - closing = false; - if (call) { - call->answer(std::nullopt); // a no-op once `return` or `close: self` has answered - } - if (screen) { - // The last values a host reads once the screen is gone, whether or not it read them before. - lastTitle = detail::host::titleText(screen->title()); - lastIdentity = screen->identity(); - lastTitleSpans = screen->titleSpans(); - lastPageEdge = screen->pageEdge(); - lastHeadJoined = screen->headJoined(); - lastLeadPlacement = screen->leadPlacement(); - lastTitleRole = screen->titleRole(); - lastHeadSurface = screen->headSurface(); - lastPageSurface = screen->pageSurface(); - lastEyebrow = detail::host::titleText(screen->eyebrow()); - lastEyebrowSpans = screen->eyebrowSpans(); - lastSubtitle = detail::host::titleText(screen->subtitle()); - lastSubtitleSpans = screen->subtitleSpans(); - runtime->batch([this] { closed.set(true); }); - screen.reset(); - } - post(std::exchange(waiting, {}), answer); - } + void finish(bool answer); /// Posts each answer to the owner, so none runs inside the document's own handler. - void post(std::vector> answers, bool answer) const { - if (answers.empty()) { - return; - } - runtime->owner().post([answers = std::move(answers), answer] { - for (auto const& done : answers) { - if (done) { - done(answer); - } - } - }); - } + void post(std::vector> answers, bool answer) const; std::unique_ptr screen; reactive::Runtime* runtime; @@ -1236,89 +780,32 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { // InterpreterHost: navigation is the host's; everything else is the application's. bool navigate(NavigateRequest const& request, std::function onResult, - std::function onCancel) override { - if (request.screen.empty()) { - return _options.application != nullptr && - _options.application->navigate(request, std::move(onResult), std::move(onCancel)); - } - NavigateRequest forwarded = request; - forwarded.call = onResult || onCancel; - if (forwarded.call) { - ValueRecord const* const params = request.params.asRecord(); - _unclaimed.push_back(std::make_shared(Call{.screen = request.screen, - .params = params == nullptr ? ParamMap{} : *params, - .onResult = std::move(onResult), - .onCancel = std::move(onCancel), - .answered = false})); - } - onNavigate(forwarded); - return true; - } + std::function onCancel) override; - bool closeSelf(std::string const& screen, std::optional result) override { - // The innermost open call of that screen answers; a screen opened without one is the application's. - for (OpenCall const& open : std::views::reverse(_open)) { - std::shared_ptr const call = open.call.lock(); - if (call == nullptr || call->screen != screen || call->answered || open.handle == nullptr || - !open.handle->answering(call)) { - continue; - } - call->answer(std::move(result)); - open.handle->closeItself([this](ScreenHandle& closed) { onScreenClosed(closed); }); - return true; - } - return _options.application != nullptr && _options.application->closeSelf(screen, std::move(result)); - } + bool closeSelf(std::string const& screen, std::optional result) override; /// Ties a mounted screen to the call that opened it: the oldest unclaimed call of that screen and params. - void adoptCall(Handle& handle, std::string_view screenId, ParamMap const& params) { - std::erase_if(_open, [](OpenCall const& open) { return open.call.expired(); }); - auto const found = std::ranges::find_if(_unclaimed, [&](std::shared_ptr const& call) { - return call->screen == screenId && call->params == params; - }); - if (found == _unclaimed.end()) { - return; - } - std::shared_ptr const call = std::move(*found); - _unclaimed.erase(found); - handle.answers(call); - _open.push_back(OpenCall{.call = call, .handle = &handle}); - } + void adoptCall(Handle& handle, std::string_view screenId, ParamMap const& params); bool hostCommand(std::string const& name, Value const& args) override { return _options.application != nullptr && _options.application->hostCommand(name, args); } bool switchBackend(std::string const& name, std::function)> done) override { return _options.application != nullptr && _options.application->switchBackend(name, std::move(done)); } - void resetPrefs(std::string const& screen, std::string const& point) override { - if (_options.application != nullptr) { - _options.application->resetPrefs(screen, point); - } - } - void setLocale(std::string const& locale) override { - if (_options.application != nullptr) { - _options.application->setLocale(locale); - } - } + void resetPrefs(std::string const& screen, std::string const& point) override; + void setLocale(std::string const& locale) override; bool notify(std::string const& text, std::string const& role) override { return _options.application != nullptr && _options.application->notify(text, role); } bool signIn(Value const& reply) override { return _options.application != nullptr && _options.application->signIn(reply); } - void signOut() override { - if (_options.application != nullptr) { - _options.application->signOut(); - } - } + void signOut() override; bool setAppValue(std::string const& name, Value const& value) override { return _options.application != nullptr && _options.application->setAppValue(name, value); } bool uploadFor(UploadRequest const& request, std::function progress, - std::function)> done) override { - return _options.application != nullptr && - _options.application->uploadFor(request, std::move(progress), std::move(done)); - } + std::function)> done) override; bool download(Value const& file, std::string const& option, Value const& name, std::function)> done) override { return _options.application != nullptr && _options.application->download(file, option, name, std::move(done)); @@ -1331,16 +818,8 @@ class DocumentScreenHost : public ScreenHost, private InterpreterHost { std::function)> done) override { return _options.application != nullptr && _options.application->saveFile(file, option, std::move(done)); } - void preferenceChanged(std::string const& screen, std::string const& point, Value const& value) override { - if (_options.application != nullptr) { - _options.application->preferenceChanged(screen, point, value); - } - } - void permissionsStale() override { - if (_options.application != nullptr) { - _options.application->permissionsStale(); - } - } + void preferenceChanged(std::string const& screen, std::string const& point, Value const& value) override; + void permissionsStale() override; /// A call a mounted screen answers, newest last. struct OpenCall { diff --git a/src/ui/host.cpp b/src/ui/host.cpp new file mode 100644 index 000000000..d15875cb5 --- /dev/null +++ b/src/ui/host.cpp @@ -0,0 +1,656 @@ +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace morph::ui { +namespace { + +/// The environment `identityOf` evaluates in: the params, and nothing else. Reading anything else marks it unknown. +class ParamsEnv final : public Environment { +public: + /// @brief An environment over @p params. + /// @param params The params; borrowed for the environment's lifetime. + explicit ParamsEnv(ParamMap const& params) : _params{¶ms} {} + + [[nodiscard]] Value ref(std::string_view head, std::span path) const override { + auto const found = _params->find(head); + if (found == _params->end()) { + _unknown = true; + return Value{}; + } + Value value = found->second; + for (std::string const& step : path) { + ValueRecord const* const record = value.asRecord(); + if (record == nullptr || !record->contains(step)) { + return Value{}; + } + value = record->at(step); + } + return value; + } + + [[nodiscard]] Value row(std::span path) const override { return unknown(path); } + + [[nodiscard]] Value control(ExprKind form, std::string_view name) const override { + static_cast(form); + static_cast(name); + _unknown = true; + return Value{}; + } + + [[nodiscard]] Value pref(std::string_view point, std::span path) const override { + static_cast(point); + return unknown(path); + } + + [[nodiscard]] Value client(ExprKind form, std::string_view name) const override { + static_cast(form); + static_cast(name); + _unknown = true; + return Value{}; + } + + [[nodiscard]] FormatContext const& formatting() const override { return _formatting; } + + // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): Environment's signature. + void report(std::string_view path, std::string_view reason) const override { + static_cast(path); + static_cast(reason); + _unknown = true; + } + + /// @brief Whether the evaluation read anything but the params, or failed. + /// @return It. + [[nodiscard]] bool unknown() const noexcept { return _unknown; } + +private: + [[nodiscard]] Value unknown(std::span path) const { + static_cast(path); + _unknown = true; + return Value{}; + } + + ParamMap const* _params; + FormatContext _formatting; + mutable bool _unknown = false; +}; + +} // namespace + +bool ScreenHead::choose(std::string_view entryId) { + static_cast(entryId); + return false; +} + +bool ScreenHead::edit(std::string_view toolId, Value const& value) { + static_cast(toolId); + static_cast(value); + return false; +} + +bool ScreenHead::submit(std::string_view toolId) { + static_cast(toolId); + return false; +} + +void ScreenHandle::save(std::function done) { + if (done) { + done(false); + } +} + +HostScreenFactory const* ScreenHostRegistry::find(std::string_view name) const { + auto const found = _factories.find(name); + return found == _factories.end() ? nullptr : &found->second; +} +namespace detail::host { + +std::string titleText(Value const& value) { + if (std::string const* const text = value.asString()) { + return *text; + } + return value.isNull() ? std::string{} : ::morph::ui::detail::canonicalJson(value); +} +} // namespace detail::host + +std::optional identityKey(Value const& identity) { + if (identity.isNull()) { + return std::nullopt; + } + return detail::canonicalJson(identity); +} + +bool sameIdentity(Value const& lhs, Value const& rhs) { + std::optional const left = identityKey(lhs); + return left.has_value() && left == identityKey(rhs); +} + +DocumentScreenHost::DocumentScreenHost(Session& session MORPH_LIFETIMEBOUND, + Dispatcher& dispatcher MORPH_LIFETIMEBOUND, DocumentScreenHostOptions options) + : _options{std::move(options)}, + _session{&session}, + _dispatcher{&dispatcher}, + _interpreter{ + session, dispatcher, + InterpreterOptions{.host = static_cast(this), .diagnostics = _options.diagnostics}} { + if (!_options.documents || _options.backend == nullptr) { + throw std::invalid_argument("DocumentScreenHost: a document lookup and a backend are required"); + } +} + +std::expected, MountError> DocumentScreenHost::mountApp( + std::shared_ptr document) { + if (!document) { + return std::unexpected(MountError{.screenId = "app", .reason = "no app document"}); + } + std::string const documentId = document->id; + auto root = _interpreter.mountApp(std::move(document)); + if (!root) { + return std::unexpected(mountErrorOf(documentId, root.error())); + } + return std::move(*root); +} + +std::optional DocumentScreenHost::identityOf(std::string_view screenId, ParamMap const& params) { + std::shared_ptr const document = _options.documents(screenId); + if (!document || !document->identity) { + return std::nullopt; + } + ParamsEnv const env{params}; + Value const identity = evaluate(*document->identity, env); + if (env.unknown()) { + return std::nullopt; + } + return identityKey(identity); +} + +void DocumentScreenHost::prefetch(std::string_view screenId, ParamMap const& params) { + std::shared_ptr const document = _options.documents(screenId); + if (!document) { + return; + } + for (std::string const& name : document->prefetch) { + auto const query = std::ranges::find(document->scope.queries, name, &QueryDecl::name); + if (query == document->scope.queries.end() || query->evaluate) { + continue; + } + auto const model = std::ranges::find(document->scope.models, query->model, &ModelDecl::name); + if (model == document->scope.models.end()) { + continue; + } + std::optional const binding = bindingOf(*model, params); + if (!binding) { + continue; + } + ParamsEnv const env{params}; + Value const body = query->body ? evaluate(*query->body, env) : Value{ValueRecord{}}; + if (env.unknown()) { + continue; + } + std::shared_ptr const channel = + _dispatcher->bind(model->type, binding->sharing, binding->instanceKey); + _session->prefetch(channel, binding->token, model->type, query->action, body); + } +} + +std::expected DocumentScreenHost::routeOf(std::string_view screenId, + ParamMap const& params) const { + std::shared_ptr const document = _options.documents(screenId); + if (!document) { + return std::unexpected("unknown screen `" + std::string{screenId} + "`"); + } + return ::morph::ui::routeOf(*document, params); +} + +void DocumentScreenHost::onNavigate(NavigateRequest const& request) { + ValueRecord const* const params = request.params.asRecord(); + onNavigate(request.screen, params == nullptr ? ParamMap{} : *params); +} + +std::expected DocumentScreenHost::remount(ScreenHandle& handle, + std::shared_ptr document) { + auto* const own = dynamic_cast(&handle); + if (own == nullptr || !document) { + return std::unexpected(MountError{.screenId = document ? document->id : std::string{}, + .reason = "not a document screen of this host"}); + } + return own->remount(_interpreter, std::move(document), *_options.backend); +} + +std::optional DocumentScreenHost::chatContext(ScreenHandle& handle) { + auto const* const own = dynamic_cast(&handle); + Screen const* const screen = own == nullptr ? nullptr : own->screen(); + if (screen == nullptr) { + return std::nullopt; + } + chat::TurnRequest context; + context.screenId = screen->id(); + context.title = handle.title().peek(); + context.identity = identityKey(handle.identity().peek()).value_or(std::string{}); + context.paramsJson = glz::write_json(valueToJson(Value{own->params()})).value_or(std::string{"{}"}); + for (Screen::BoundAlias const& alias : screen->boundAliases()) { + context.models.push_back(chat::ModelRef{.path = alias.decl->path, + .alias = alias.decl->name, + .modelType = alias.decl->type, + .instanceId = alias.facts.instanceId, + .primary = alias.facts.primary}); + } + return context; +} + +std::optional DocumentScreenHost::inspector(ScreenHandle& handle) { + auto const* const own = dynamic_cast(&handle); + Screen* const screen = own == nullptr ? nullptr : own->screen(); + if (screen == nullptr) { + return std::nullopt; + } + return Inspector::over(*screen); +} + +void DocumentScreenHost::cancelUnclaimedCalls() { + for (std::shared_ptr const& call : std::exchange(_unclaimed, {})) { + call->answer(std::nullopt); + } +} + +Widget* DocumentScreenHost::rootOf(ScreenHandle const& handle) { + auto const* const own = dynamic_cast(&handle); + return own == nullptr ? nullptr : own->root(); +} + +void DocumentScreenHost::settleCall(std::string_view screenId, ParamMap const& params) { + auto const found = std::ranges::find_if(_unclaimed, [&](std::shared_ptr const& call) { + return call->screen == screenId && call->params == params; + }); + if (found == _unclaimed.end()) { + return; + } + std::shared_ptr const call = std::move(*found); + _unclaimed.erase(found); + if (_options.diagnostics) { + _options.diagnostics( + Refusal{.document = std::string{screenId}, + .path = {}, + .reason = "navigate to " + std::string{screenId} + " mounted no screen; its call was cancelled"}); + } + call->answer(std::nullopt); +} + +std::optional DocumentScreenHost::bindingOf(ModelDecl const& model, + ParamMap const& params) const { + InstanceMode mode = model.instance; + if (mode == InstanceMode::Default) { + Catalog const& catalog = _session->options().catalog; + std::optional const info = catalog.model ? catalog.model(model.type) : std::nullopt; + mode = info && info->stateless ? InstanceMode::Shared : InstanceMode::Private; + } + if (mode == InstanceMode::Shared) { + return Binding{.token = "shared", .sharing = bridge::BindSharing::Private, .instanceKey = {}}; + } + if (mode != InstanceMode::Keyed || !model.key) { + return std::nullopt; + } + ParamsEnv const env{params}; + std::string const key = detail::instanceKeyText(evaluate(*model.key, env)); + if (env.unknown() || key.empty()) { + return std::nullopt; + } + return Binding{.token = "shared:" + key, .sharing = bridge::BindSharing::Shared, .instanceKey = key}; +} + +std::expected, MountError> DocumentScreenHost::mountAt(std::string_view screenId, + ParamMap const& params, + ContainerWidget* parent) { + std::shared_ptr document = _options.documents(screenId); + if (!document) { + return std::unexpected(MountError{.screenId = std::string{screenId}, .reason = "unknown screen"}); + } + auto screen = _interpreter.mount(std::move(document), params, *_options.backend, MountOptions{.parent = parent}); + if (!screen) { + return std::unexpected(mountErrorOf(screenId, screen.error())); + } + auto handle = std::make_unique(std::move(*screen), _options.guard, _options.saveFailed); + handle->placed(params, parent); + adoptCall(*handle, screenId, params); + return handle; +} + +MountError DocumentScreenHost::mountErrorOf(std::string_view screenId, Refusal const& refusal) { + std::string reason = refusal.reason; + if (!refusal.path.empty()) { + reason = refusal.path + ": " + reason; + } + return MountError{.screenId = std::string{screenId}, .reason = std::move(reason)}; +} + +void DocumentScreenHost::Call::answer(std::optional result) { + if (answered) { + return; + } + answered = true; + if (result) { + if (onResult) { + onResult(std::move(*result)); + } + } else if (onCancel) { + onCancel(); + } +} + +DocumentScreenHost::Handle::~Handle() { + _state->self = nullptr; + try { + _state->finish(true); + } catch (...) { // NOLINT(bugprone-empty-catch): a destructor has no one to report to; the screen is gone. + } +} + +void DocumentScreenHost::Handle::placed(ParamMap params, ContainerWidget* parent) { + _state->params = std::move(params); + _state->parent = parent; +} + +std::expected DocumentScreenHost::Handle::remount(Interpreter& interpreter, + std::shared_ptr document, + IViewBackend& backend) { + State& state = *_state; + std::string const screenId = document->id; + if (!state.screen) { + return std::unexpected(MountError{.screenId = screenId, .reason = "the screen is closed"}); + } + if (state.closing || state.saved.effect) { + return std::unexpected(MountError{.screenId = screenId, .reason = "the screen is closing or saving"}); + } + auto next = interpreter.mount(std::move(document), state.params, backend, + MountOptions{.parent = state.parent, .keepStateOf = state.screen.get()}); + if (!next) { + return std::unexpected(mountErrorOf(screenId, next.error())); + } + // The old screen goes after the new one has mounted, so its root widget is never missing in between; + // destroying it runs its `onUnmount`. + std::unique_ptr const replaced = std::exchange(state.screen, std::move(*next)); + state.runtime->batch([&state] { state.generation.set(state.generation.peek() + 1); }); + return {}; +} + +void DocumentScreenHost::Handle::closeItself(std::function closed) { + std::weak_ptr const weak = _state; + _state->runtime->owner().post([weak, closed = std::move(closed)] { + auto const held = weak.lock(); + if (!held || !held->screen) { + return; + } + held->finish(true); + if (held->self != nullptr && closed) { + closed(*held->self); + } + }); +} + +void DocumentScreenHost::Handle::State::request(std::shared_ptr const& state, std::function done) { + if (!state->screen) { + state->post({std::move(done)}, true); + return; + } + state->waiting.push_back(std::move(done)); + if (state->closing) { + return; + } + state->closing = true; + std::shared_ptr const cancelled = state->screen->beginClose(); + if (cancelled == nullptr) { + bool const isDirty = state->screen->dirty(); + if (!isDirty) { + state->finish(true); + } else if (state->guard && state->self != nullptr) { + std::weak_ptr const weak = state; + state->guard(*state->self, [weak](CloseChoice choice) { + if (auto const held = weak.lock()) { + choose(held, choice); + } + }); + } else { + state->decide(false); + } + return; + } + // Closes once onClose and everything it started has ended, unless it ran cancelClose. + whenSettled(state, &State::settled, [cancelled](State& settledState) { settledState.decide(!*cancelled); }); +} + +void DocumentScreenHost::Handle::State::whenSettled(std::shared_ptr const& state, Watch State::* slot, + std::function then) { + std::weak_ptr const weak = state; + std::uint64_t const watchId = ++state->watches; + Watch& watch = state.get()->*slot; + watch.id = watchId; + watch.effect = std::make_unique(*state->runtime, [weak, slot, watchId, then = std::move(then)] { + auto const held = weak.lock(); + if (!held || !held->screen || held->screen->pending()) { + return; + } + held->runtime->owner().post([weak, slot, watchId, then] { + auto const again = weak.lock(); + if (!again || !again->screen || (again.get()->*slot).id != watchId) { + return; + } + again.get()->*slot = Watch{}; + then(*again); + }); + }); +} + +void DocumentScreenHost::Handle::State::save(std::shared_ptr const& state, std::function done) { + if (!state->canSave()) { + if (done) { + done(false); + } + return; + } + if (state->saved.effect) { + state->saving.push_back(std::move(done)); + return; + } + state->screen->runLifecycle("onSave"); + state->saving.push_back(std::move(done)); + // Answered in the settled task itself rather than posted again, so an answer never reaches a handle + // that closed in between; an answer that closes the screen ends the answering. + whenSettled(state, &State::saved, [](State& savedState) { + bool const clean = !savedState.screen->dirty(); + for (auto const& answer : std::exchange(savedState.saving, {})) { + if (!savedState.screen) { + return; + } + if (answer) { + answer(clean); + } + } + }); +} + +void DocumentScreenHost::Handle::State::choose(std::shared_ptr const& state, CloseChoice choice) { + if (!state->closing) { + return; + } + if (choice != CloseChoice::Save || !state->canSave()) { + state->decide(choice == CloseChoice::Discard); + return; + } + std::weak_ptr const weak = state; + save(state, [weak](bool clean) { + auto const held = weak.lock(); + if (!held) { + return; + } + if (!clean && held->saveFailed && held->self != nullptr) { + held->saveFailed(*held->self); + } + held->decide(clean); + }); +} + +void DocumentScreenHost::Handle::State::decide(bool close) { + if (!closing) { + return; + } + if (close) { + finish(true); + return; + } + closing = false; + post(std::exchange(waiting, {}), false); +} + +void DocumentScreenHost::Handle::State::finish(bool answer) { + settled = {}; + saved = {}; + saving.clear(); // a save outlived by its screen is never answered + closing = false; + if (call) { + call->answer(std::nullopt); // a no-op once `return` or `close: self` has answered + } + if (screen) { + // The last values a host reads once the screen is gone, whether or not it read them before. + lastTitle = detail::host::titleText(screen->title()); + lastIdentity = screen->identity(); + lastTitleSpans = screen->titleSpans(); + lastPageEdge = screen->pageEdge(); + lastHeadJoined = screen->headJoined(); + lastLeadPlacement = screen->leadPlacement(); + lastTitleRole = screen->titleRole(); + lastHeadSurface = screen->headSurface(); + lastPageSurface = screen->pageSurface(); + lastEyebrow = detail::host::titleText(screen->eyebrow()); + lastEyebrowSpans = screen->eyebrowSpans(); + lastSubtitle = detail::host::titleText(screen->subtitle()); + lastSubtitleSpans = screen->subtitleSpans(); + runtime->batch([this] { closed.set(true); }); + screen.reset(); + } + post(std::exchange(waiting, {}), answer); +} + +void DocumentScreenHost::Handle::State::post(std::vector> answers, bool answer) const { + if (answers.empty()) { + return; + } + runtime->owner().post([answers = std::move(answers), answer] { + for (auto const& done : answers) { + if (done) { + done(answer); + } + } + }); +} + +bool DocumentScreenHost::navigate(NavigateRequest const& request, std::function onResult, + std::function onCancel) { + if (request.screen.empty()) { + return _options.application != nullptr && + _options.application->navigate(request, std::move(onResult), std::move(onCancel)); + } + NavigateRequest forwarded = request; + forwarded.call = onResult || onCancel; + if (forwarded.call) { + ValueRecord const* const params = request.params.asRecord(); + _unclaimed.push_back(std::make_shared(Call{.screen = request.screen, + .params = params == nullptr ? ParamMap{} : *params, + .onResult = std::move(onResult), + .onCancel = std::move(onCancel), + .answered = false})); + } + onNavigate(forwarded); + return true; +} + +bool DocumentScreenHost::closeSelf(std::string const& screen, std::optional result) { + // The innermost open call of that screen answers; a screen opened without one is the application's. + for (OpenCall const& open : std::views::reverse(_open)) { + std::shared_ptr const call = open.call.lock(); + if (call == nullptr || call->screen != screen || call->answered || open.handle == nullptr || + !open.handle->answering(call)) { + continue; + } + call->answer(std::move(result)); + open.handle->closeItself([this](ScreenHandle& closed) { onScreenClosed(closed); }); + return true; + } + return _options.application != nullptr && _options.application->closeSelf(screen, std::move(result)); +} + +void DocumentScreenHost::adoptCall(Handle& handle, std::string_view screenId, ParamMap const& params) { + std::erase_if(_open, [](OpenCall const& open) { return open.call.expired(); }); + auto const found = std::ranges::find_if(_unclaimed, [&](std::shared_ptr const& call) { + return call->screen == screenId && call->params == params; + }); + if (found == _unclaimed.end()) { + return; + } + std::shared_ptr const call = std::move(*found); + _unclaimed.erase(found); + handle.answers(call); + _open.push_back(OpenCall{.call = call, .handle = &handle}); +} + +void DocumentScreenHost::resetPrefs(std::string const& screen, std::string const& point) { + if (_options.application != nullptr) { + _options.application->resetPrefs(screen, point); + } +} + +void DocumentScreenHost::setLocale(std::string const& locale) { + if (_options.application != nullptr) { + _options.application->setLocale(locale); + } +} + +void DocumentScreenHost::signOut() { + if (_options.application != nullptr) { + _options.application->signOut(); + } +} + +bool DocumentScreenHost::uploadFor(UploadRequest const& request, std::function progress, + std::function)> done) { + return _options.application != nullptr && + _options.application->uploadFor(request, std::move(progress), std::move(done)); +} + +void DocumentScreenHost::preferenceChanged(std::string const& screen, std::string const& point, Value const& value) { + if (_options.application != nullptr) { + _options.application->preferenceChanged(screen, point, value); + } +} + +void DocumentScreenHost::permissionsStale() { + if (_options.application != nullptr) { + _options.application->permissionsStale(); + } +} +} // namespace morph::ui From de9e6b99813ffba0dfa0c569302192fa862cd407 Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 01:29:28 +0100 Subject: [PATCH 11/38] Move the workspace's non-template code into src/ui/workspace.cpp Workspace's member bodies of two or more lines move to the compiled library, and the class carries MORPH_API. One-line accessors stay in the header. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- CMakeLists.txt | 1 + include/morph/ui/workspace.hpp | 869 +++----------------------------- src/ui/workspace.cpp | 894 +++++++++++++++++++++++++++++++++ 3 files changed, 958 insertions(+), 806 deletions(-) create mode 100644 src/ui/workspace.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 2bc606baf..6a015baca 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -419,6 +419,7 @@ add_library(morph STATIC src/ui/service.cpp src/ui/host.cpp src/ui/service_client.cpp + src/ui/workspace.cpp ) add_library(morph::morph ALIAS morph) diff --git a/include/morph/ui/workspace.hpp b/include/morph/ui/workspace.hpp index 028d4eae3..428b28081 100644 --- a/include/morph/ui/workspace.hpp +++ b/include/morph/ui/workspace.hpp @@ -9,6 +9,7 @@ #include #include #include +#include #include #include #include @@ -82,7 +83,7 @@ struct HeadParts { /// and takes Ctrl+Tab, Ctrl+Shift+Tab and Ctrl+W, which documents may not declare. A screen a document navigates to as /// a dialog or a drawer is shown over the tabs (`openOverlay`). Neither copyable nor movable; owned by the owner /// thread of its runtime. -class Workspace { +class MORPH_API Workspace { public: /// @brief The shell, its tab bar appended to @p parent. /// @param runtime The runtime the screens' reactive nodes belong to. Borrowed. @@ -94,55 +95,11 @@ class Workspace { /// `headPartsForActive()` itself, so a shell with its own top bar shows the head once. Workspace(reactive::Runtime& runtime MORPH_LIFETIMEBOUND, IViewBackend& backend MORPH_LIFETIMEBOUND, DocumentScreenHost& host MORPH_LIFETIMEBOUND, WorkspaceOptions options = {}, - ContainerWidget* parent = nullptr, HeadPlacement headPlacement = HeadPlacement::InPage) - : _runtime{&runtime}, - _backend{&backend}, - _host{&host}, - _parent{parent}, - _bar{backend.createTabs(parent)}, - _hosts{options.hosts}, - _screens{options.screens}, - _onChanged{std::move(options.onChanged)}, - _diagnostics{options.diagnostics}, - _headPlacement{headPlacement} { - // The bar and each page fill what they are given, so a screen whose root stretches fills the page. - _bar->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); - _bar->setTabs({}); - _bar->setSelected(kNone); - _bar->setOnSelect([this](std::size_t index) { - std::vector const order = _model->order(); - if (index < order.size()) { - _model->activate(order.at(index)); - } - }); - _bar->setKeys({"Ctrl+Tab", "Ctrl+Shift+Tab", "Ctrl+W"}, [this](std::string const& chord) { - if (chord == "Ctrl+Tab") { - next(); - } else if (chord == "Ctrl+Shift+Tab") { - previous(); - } else if (std::optional const shown = active()) { - close(*shown, {}); - } - }); - WorkspaceModelOptions modelOptions{std::move(options), {}, {}}; - modelOptions.onChanged = [this] { showTabs(); }; - modelOptions.mountPage = [this](WorkspaceTabId tab, std::string_view screenId, ParamMap const& params) { - return mountPage(tab, screenId, params); - }; - modelOptions.unmountPage = [this](WorkspaceTabId tab) { - std::erase(_shownOrder, tab); - _pages.erase(tab.value); - }; - _model = std::make_unique(runtime, host, std::move(modelOptions)); - } + ContainerWidget* parent = nullptr, HeadPlacement headPlacement = HeadPlacement::InPage); /// @brief Closes every overlay without asking, newest first, then unmounts every tab's screen the same way, then /// the pages: a callee goes before the opener its call answers. - ~Workspace() { - *_alive = false; - closeOverlays(); - _model.reset(); - } + ~Workspace(); Workspace(Workspace const&) = delete; Workspace& operator=(Workspace const&) = delete; @@ -161,13 +118,7 @@ class Workspace { /// @param screenId The screen id. /// @param params Its params. /// @return The tab's index, or why the screen could not be mounted; a refused mount opens nothing. - std::expected open(std::string_view screenId, ParamMap const& params) { - auto opened = _model->open(screenId, params); - if (!opened) { - return std::unexpected(std::move(opened.error())); - } - return indexOf(*opened); - } + std::expected open(std::string_view screenId, ParamMap const& params); /// @brief Opens a screen as `open` does, and says whether it mounted one (`WorkspaceModel::openTab`): what a host /// needs to settle the call of a navigation that only focused a tab. @@ -189,80 +140,21 @@ class Workspace { /// itself goes through `screenClosed`. An overlay adds no tab, no record entry and no route. /// @param request The navigation: a screen, its params, and `as` either `dialog` or `drawer`. /// @return Nothing, or why nothing was shown: an `as` that is not an overlay, a host screen, or a refused mount. - std::expected openOverlay(NavigateRequest const& request) { - if (request.as != "dialog" && request.as != "drawer") { - return std::unexpected(MountError{.screenId = request.screen, - .reason = "`as: " + request.as + "` is not a dialog or a drawer"}); - } - if (_screens && !_screens(request.screen).host.empty()) { - return std::unexpected( - MountError{.screenId = request.screen, .reason = "a host screen opens as a tab, not an overlay"}); - } - ValueRecord const* const record = request.params.asRecord(); - ParamMap const params = record == nullptr ? ParamMap{} : *record; - auto overlay = std::make_unique(); - overlay->id = ++_lastOverlay; - overlay->screenId = request.screen; - ContainerWidget* content = nullptr; - ContainerWidget* footer = nullptr; - if (request.as == "drawer") { - overlay->drawer = _backend->createDrawer(_parent, Side::End); - content = overlay->drawer.get(); - footer = &overlay->drawer->footer(); - } else { - overlay->dialog = _backend->createDialog(_parent); - content = overlay->dialog.get(); - footer = &overlay->dialog->footer(); - } - auto handle = _host->mountInto(request.screen, params, *content); - if (!handle) { - return std::unexpected(std::move(handle.error())); - } - overlay->handle = std::move(*handle); - showOverlay(*overlay, *footer); - _overlays.push_back(std::move(overlay)); - return {}; - } + std::expected openOverlay(NavigateRequest const& request); /// @brief A screen the workspace shows closed itself, by `return` or `close: self`: its overlay goes, or its tab /// does. What a host's `DocumentScreenHost::onScreenClosed` forwards here. /// @param screen The closed screen's handle; one the workspace does not show does nothing. - void screenClosed(ScreenHandle const& screen) { - auto const overlay = std::ranges::find_if( - _overlays, [&screen](std::unique_ptr const& open) { return open->handle.get() == &screen; }); - if (overlay != _overlays.end()) { - _overlays.erase(overlay); - return; - } - for (WorkspaceTabId const tab : _model->order()) { - if (_model->handleOf(tab) == &screen) { - // The screen is closed, so its close answers at once and the tab goes. - _model->close(tab, {}); - return; - } - } - } + void screenClosed(ScreenHandle const& screen); /// @brief The screens shown over the tabs, oldest first. /// @return Each overlay's screen id. - [[nodiscard]] std::vector overlays() const { - std::vector out; - out.reserve(_overlays.size()); - for (auto const& overlay : _overlays) { - out.push_back(overlay->screenId); - } - return out; - } + [[nodiscard]] std::vector overlays() const; /// @brief Tells the workspace the window's width class changed, as the backend's `setOnWidthClass` listener /// reports it: each open dialog overlay is a sheet while it is `compact`. /// @param widthClass The class. - void setWidthClass(std::string_view widthClass) { - bool const sheet = widthClass == "compact"; - for (auto const& overlay : _overlays) { - showSheet(*overlay, sheet); - } - } + void setWidthClass(std::string_view widthClass); /// @brief Opens the start screens (`WorkspaceModel::start`). /// @param how The start screen, the fallback and the record. @@ -279,11 +171,7 @@ class Workspace { /// @brief Shows a tab and makes it the most recently used. /// @param index The tab; past the last one does nothing. - void activate(std::size_t index) { - if (std::optional const tab = tabAt(index)) { - _model->activate(*tab); - } - } + void activate(std::size_t index); /// @brief Shows the next tab in most-recently-used order (Ctrl+Tab). Repeated calls walk the order as it was at /// the first of them; any other activation starts a new walk. @@ -295,28 +183,12 @@ class Workspace { /// @brief Closes a tab through its screen's close protocol. /// @param index The tab. /// @param done Called once with whether it closed; may be empty. - void close(std::size_t index, std::function done) { - std::optional const tab = tabAt(index); - if (!tab) { - if (done) { - done(false); - } - return; - } - _model->close(*tab, std::move(done)); - } + void close(std::size_t index, std::function done); /// @brief Closes every tab but one, one at a time, stopping at the first veto. /// @param index The tab kept; past the last one closes every tab. /// @param done Called once with whether every other tab closed; may be empty. - void closeOthers(std::size_t index, std::function done) { - std::optional const tab = tabAt(index); - if (!tab) { - _model->closeAll(std::move(done)); - return; - } - _model->closeOthers(*tab, std::move(done)); - } + void closeOthers(std::size_t index, std::function done); /// @brief Closes every tab, one at a time, stopping at the first veto. /// @param done Called once with whether every tab closed; may be empty. @@ -336,83 +208,33 @@ class Workspace { /// @brief The active tab's index. /// @return It, or `std::nullopt` while no tab is open. - [[nodiscard]] std::optional active() const { - std::optional const tab = _model->active().peek(); - if (!tab) { - return std::nullopt; - } - return indexOf(*tab); - } + [[nodiscard]] std::optional active() const; /// @brief The screen handle of a tab: what a client remounts for development reload and inspects. /// @param index The tab's index. /// @return Its handle, valid while the tab is open; null past the end. - [[nodiscard]] ScreenHandle* handleOf(std::size_t index) const noexcept { - std::optional const tab = tabAt(index); - return tab ? _model->handleOf(*tab) : nullptr; - } + [[nodiscard]] ScreenHandle* handleOf(std::size_t index) const noexcept; /// @brief The active tab's screen handle. /// @return It, or null while no tab is open. - [[nodiscard]] ScreenHandle* activeHandle() const { - std::optional const shown = active(); - return shown ? handleOf(*shown) : nullptr; - } + [[nodiscard]] ScreenHandle* activeHandle() const; /// @brief The active tab's head as two parts, the same reactive content `headRow` builds for the in-page /// rendering, for a host that mounts them elsewhere (a shell's own top bar, say). Neither is null: with no /// active tab each is an invisible, empty container rather than a null `Node`, since a caller mounting them /// may not expect to handle one. /// @return The lead and the trail, reactive to the active tab changing and to its head's own content changing. - [[nodiscard]] HeadParts headPartsForActive() const { - std::optional const tab = _model->active().peek(); - if (tab) { - // A host places the lead beside the title and gives it the minimum width it wants, so the lead has none - // of its own: with one, a lead's natural width would never be less than it. - Row lead = buildHeadLead(*tab, LeadPlacement::Below); - lead.common.layout.minWidth.reset(); - return HeadParts{.eyebrow = ui::text(buildHeadEyebrow(*tab)), - .lead = ui::row(std::move(lead)), - .trail = ui::actionBar(buildHeadTrail(*tab)), - .inlineLead = ui::row(buildHeadLead(*tab, LeadPlacement::Inline))}; - } - Text eyebrow{.text = std::string{}, .role = TextRole::Muted, .field = {}, .common = {}}; - eyebrow.common.testId = "head_eyebrow"; - eyebrow.common.visible = false; - Row lead{.children = {}, .gap = 0, .common = {}, .tone = std::nullopt}; - lead.common.testId = "head_lead"; - lead.common.visible = false; - Row trail{.children = {}, .gap = 0, .common = {}, .tone = std::nullopt}; - trail.common.testId = "head_trail"; - trail.common.visible = false; - Row inlineLead{.children = {}, .gap = 0, .common = {}, .tone = std::nullopt}; - inlineLead.common.testId = "head_lead_inline"; - inlineLead.common.visible = false; - return HeadParts{.eyebrow = ui::text(std::move(eyebrow)), - .lead = ui::row(std::move(lead)), - .trail = ui::row(std::move(trail)), - .inlineLead = ui::row(std::move(inlineLead))}; - } + [[nodiscard]] HeadParts headPartsForActive() const; /// @brief Where the active tab's head puts its lead. A tracked read. /// @return The place; `Below` with no active tab. With the head in the page (`HeadPlacement::InPage`) the tab /// bar carries the title, so `Inline` reads as `Below` there. - [[nodiscard]] LeadPlacement activeLeadPlacement() const { - std::optional const tab = _model->active().get(); - return tab ? leadPlacementOf(*tab) : LeadPlacement::Below; - } + [[nodiscard]] LeadPlacement activeLeadPlacement() const; /// @brief Whether the active tab's head is a single line: it has no eyebrow, and its lead is not drawn under the /// title (it has none, or it sits inline or at the end). A tracked read. /// @return Whether the head is one line; `true` with no active tab. - [[nodiscard]] bool activeHeadOneLine() const { - std::optional const tab = _model->active().get(); - if (!tab) { - return true; - } - bool const leadUnderTitle = leadHasContent(*tab) && leadPlacementOf(*tab) == LeadPlacement::Below; - return !(eyebrowHasContent(*tab) || leadUnderTitle); - } + [[nodiscard]] bool activeHeadOneLine() const; /// @brief What ends the active tab's head trail, so a compact top bar can stand the line's end the right distance /// from the window's edge. A tracked read. @@ -420,126 +242,59 @@ class Workspace { /// trigger is an icon button, or a last action that is icon-only or ghost is `Unframed`; any other last /// action is `Framed`; with no action and no menu, a head tool is `Framed`; an empty trail, and no active /// tab, is `None`. - [[nodiscard]] HeadTrailEnd activeHeadTrailEnd() const { - std::optional const tab = _model->active().get(); - if (!tab) { - return HeadTrailEnd::None; - } - if (!headMenuOf(*tab).empty()) { - return HeadTrailEnd::Unframed; - } - ScreenHead const* const head = headOf(*tab); - if (head == nullptr) { - return HeadTrailEnd::None; - } - std::vector const actions = head->actions().get(); - if (!actions.empty()) { - return actions.back().iconOnly || actions.back().emphasis == ButtonEmphasis::Ghost ? HeadTrailEnd::Unframed - : HeadTrailEnd::Framed; - } - return headToolsOf(*tab).empty() ? HeadTrailEnd::None : HeadTrailEnd::Framed; - } + [[nodiscard]] HeadTrailEnd activeHeadTrailEnd() const; /// @brief Whether the active tab's page continues the head's block: the screen's shown root says so /// (`ScreenHead::headJoined`) and the page is not inset, which two tabs or more force. A tracked read. /// @return Whether the head is joined to the page. - [[nodiscard]] bool activeHeadJoined() const { - std::optional const tab = _model->active().get(); - if (!tab || activePageInset()) { - return false; - } - ScreenHead const* const head = headOf(*tab); - reactive::Computed const* const joined = head == nullptr ? nullptr : head->headJoined(); - return joined != nullptr && joined->get(); - } + [[nodiscard]] bool activeHeadJoined() const; /// @brief The text role the active screen asks for its head's title. A tracked read. /// @return `Heading`, or `Headline` where the screen asks for it; `Heading` with no active tab. - [[nodiscard]] TextRole activeTitleRole() const { - std::optional const tab = _model->active().get(); - ScreenHead const* const head = tab ? headOf(*tab) : nullptr; - reactive::Computed const* const role = head == nullptr ? nullptr : head->titleRole(); - return role == nullptr ? TextRole::Heading : role->get(); - } + [[nodiscard]] TextRole activeTitleRole() const; /// @brief The surface the active screen asks the shell to draw its top bar on. A tracked read. /// @return The surface's name; empty with no active tab and while the screen names none. - [[nodiscard]] std::string activeHeadSurface() const { - std::optional const tab = _model->active().get(); - ScreenHead const* const head = tab ? headOf(*tab) : nullptr; - reactive::Computed const* const surface = head == nullptr ? nullptr : head->headSurface(); - return surface == nullptr ? std::string{} : surface->get(); - } + [[nodiscard]] std::string activeHeadSurface() const; /// @brief The surface the active screen asks the shell to draw the page area on. A tracked read. /// @return The surface's name; empty with no active tab and while the screen names none. - [[nodiscard]] std::string activePageSurface() const { - std::optional const tab = _model->active().get(); - ScreenHead const* const head = tab ? headOf(*tab) : nullptr; - reactive::Computed const* const surface = head == nullptr ? nullptr : head->pageSurface(); - return surface == nullptr ? std::string{} : surface->get(); - } + [[nodiscard]] std::string activePageSurface() const; /// @brief The active tab's title as runs, which a shell that knows them draws in place of the tab's caption. A /// tracked read. /// @return The runs; empty with no active tab, or while the active screen gives none. - [[nodiscard]] std::vector activeTitleSpans() const { - std::optional const tab = _model->active().get(); - return tab ? titleSpansOf(headOf(*tab)) : std::vector{}; - } + [[nodiscard]] std::vector activeTitleSpans() const; /// @brief Whether the shell insets the page around the active tab's screen. A tracked read. The page is inset with /// no active tab and while the workspace's tab strip shows (two tabs or more), since the strip is a child /// of the page and would otherwise touch the window's edges; with one tab it is inset unless the screen's /// shown root lays itself at the page's edges (`ScreenHead::pageEdge`). /// @return Whether the page is inset. - [[nodiscard]] bool activePageInset() const { - std::optional const tab = _model->active().get(); - if (!tab || _model->tabs().get().size() > 1) { - return true; - } - ScreenHead const* const head = headOf(*tab); - reactive::Computed const* const edge = head == nullptr ? nullptr : head->pageEdge(); - return edge == nullptr || !edge->get(); - } + [[nodiscard]] bool activePageInset() const; /// @brief Whether the active tab's head shows anything: an eyebrow, a subtitle, a badge, a tool, an action or a /// menu entry. A tracked read, so a /// shell that shows the head on a line of its own follows a tab switch and a head's own changes; the head /// row's own visibility is the same rule. /// @return Whether there is an active tab whose head has content. - [[nodiscard]] bool activeHeadShown() const { - std::optional const tab = _model->active().get(); - return tab.has_value() && headHasContent(*tab); - } + [[nodiscard]] bool activeHeadShown() const; /// @brief Closes every overlay, then every tab, without asking, newest first: what signing out does, since no /// close guard may keep a screen of the principal who is leaving. A callee goes before the opener its call /// answers, so the opener's `onCancel` runs in a live scope; then every call no mount adopted is cancelled. - void forceCloseAll() { - closeOverlays(); - _model->forceCloseAll(); - } + void forceCloseAll(); /// @brief The open tabs, in order. /// @return Each tab's screen, identity and caption. - [[nodiscard]] std::vector tabs() const { - std::vector out; - for (WorkspaceTabId const tab : _model->order()) { - ScreenHandle const& handle = *_model->handleOf(tab); - out.push_back(WorkspaceTab{.screenId = std::string{screenOf(tab)}, - .identity = handle.identity().peek(), - .caption = captionOf(handle)}); - } - return out; - } + [[nodiscard]] std::vector tabs() const; private: static constexpr std::size_t kNone = static_cast(-1); // A tab's page: the slot of the bar it shows in, the head row above its screen, and the screen's id. The model // destroys the screen's handle before it lets the page go. - struct Page { + struct MORPH_API Page { std::string screenId; std::unique_ptr slot; // The head row reads the handle through the model, which answers null once the handle is gone. @@ -550,15 +305,12 @@ class Workspace { Page& operator=(Page const&) = delete; Page(Page&&) = delete; Page& operator=(Page&&) = delete; - ~Page() { - head.reset(); - slot.reset(); - } + ~Page(); }; // A screen shown over the tabs: its dialog or drawer, its handle, the footer of its head's actions and the scope // of the effects that follow it, destroyed in the reverse order, so the handle goes before its container. - struct Overlay { + struct MORPH_API Overlay { std::uint64_t id = 0; std::string screenId; std::unique_ptr dialog; @@ -574,125 +326,29 @@ class Workspace { Overlay& operator=(Overlay const&) = delete; Overlay(Overlay&&) = delete; Overlay& operator=(Overlay&&) = delete; - ~Overlay() { - scope.reset(); - footer.reset(); - handle.reset(); - drawer.reset(); - dialog.reset(); - } - - void setOpen(bool open) const { - if (dialog) { - dialog->setOpen(open); - } else { - drawer->setOpen(open); - } - } + ~Overlay(); + + void setOpen(bool open) const; }; // Draws a dialog overlay as a sheet, or as a centred dialog again; a drawer has no sheet. - static void showSheet(Overlay& overlay, bool sheet) { - if (overlay.dialog && sheet != overlay.sheet) { - overlay.sheet = sheet; - overlay.dialog->setSheet(sheet); - } - } + static void showSheet(Overlay& overlay, bool sheet); // Titles a mounted overlay, puts its head's actions in its footer, opens it and makes a dismissal ask its screen. - void showOverlay(Overlay& overlay, ContainerWidget& footer) { - ScreenHandle const* const handle = overlay.handle.get(); - ScreenHead* const head = overlay.handle->head(); - overlay.scope = std::make_unique(*_runtime); - overlay.scope->effect([&overlay, handle] { - std::string const title = handle->title().get(); - if (overlay.dialog) { - overlay.dialog->setTitle(title); - } else { - overlay.drawer->setTitle(title); - } - }); - if (head != nullptr) { - overlay.footer.emplace(*_runtime, *_backend, overlayActions(*head), &footer); - overlay.scope->effect([this, &overlay, head] { - bool const menu = head->menu() != nullptr && !head->menu()->get().empty(); - bool const tools = head->tools() != nullptr && !head->tools()->get().empty(); - if ((menu || tools) && !overlay.reported) { - overlay.reported = true; - _runtime->untracked([this, &overlay] { - if (_diagnostics) { - _diagnostics(Refusal{.document = overlay.screenId, - .path = {}, - .reason = "a dialog or drawer does not show the head menu or tools " - "of " + - overlay.screenId}); - } - }); - } - }); - } - showSheet(overlay, _backend->widthClass() == "compact"); - std::uint64_t const overlayId = overlay.id; - auto const dismissed = [this, overlayId] { - Overlay const* const shown = overlayOf(overlayId); - if (shown == nullptr) { - return; - } - // The dismissal closed the widget. It is opened again at once, so the screen stays reachable while its - // close protocol runs, and goes only when the screen closed: a dirty screen without a guard stays. - shown->setOpen(true); - shown->handle->requestClose([this, alive = std::weak_ptr{_alive}, overlayId](bool closed) { - if (auto const live = alive.lock(); live != nullptr && *live && closed) { - removeOverlay(overlayId); - } - }); - }; - if (overlay.dialog) { - overlay.dialog->setOnDismiss(dismissed); - } else { - overlay.drawer->setOnDismiss(dismissed); - } - overlay.setOpen(true); - } + void showOverlay(Overlay& overlay, ContainerWidget& footer); // The footer of an overlay: a button per visible head action, each running the action by its id. It is an action // bar, so its buttons are the theme's action gap apart, as the same actions are in a head. - [[nodiscard]] static Node overlayActions(ScreenHead& head) { - ActionBar bar; - bar.common.testId = "overlay_actions"; - bar.common.visible = Prop{[&head] { return !head.actions().get().empty(); }}; - bar.children.push_back(ui::forEach( - [&head] { return head.actions().get(); }, [](HeadAction const& action) { return Key{action.id}; }, - [&head](reactive::Signal const& action) { - Button button{.label = Prop{[&action] { return action.get().label; }}, - .emphasis = action.peek().emphasis, - .onClick = [&head, actionId = action.peek().id] { head.run(actionId); }, - .common = {}}; - button.common.testId = "overlay_action_" + action.peek().id; - button.common.enabled = Prop{[&action] { return action.get().enabled; }}; - return ui::button(std::move(button)); - }, - Axis::Horizontal, 2)); - return ui::actionBar(std::move(bar)); - } + [[nodiscard]] static Node overlayActions(ScreenHead& head); - [[nodiscard]] Overlay const* overlayOf(std::uint64_t overlayId) const { - auto const found = std::ranges::find(_overlays, overlayId, [](auto const& open) { return open->id; }); - return found == _overlays.end() ? nullptr : found->get(); - } + [[nodiscard]] Overlay const* overlayOf(std::uint64_t overlayId) const; void removeOverlay(std::uint64_t overlayId) { std::erase_if(_overlays, [overlayId](std::unique_ptr const& open) { return open->id == overlayId; }); } // Closes every overlay without asking, newest first; each one's close answers its call with a cancel. - void closeOverlays() { - while (!_overlays.empty()) { - std::unique_ptr const last = std::move(_overlays.back()); - _overlays.pop_back(); - last->handle->forceClose(); - } - } + void closeOverlays(); // A badge of the head row, by its place among the visible badges. struct PlacedBadge { @@ -710,163 +366,43 @@ class Workspace { }; // NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. - [[nodiscard]] static std::string shapeOf(std::vector const& entries) { - std::string shape; - for (HeadMenuEntry const& entry : entries) { - if (entry.separator) { - shape += '|'; - } else if (!entry.items.empty()) { - shape += '(' + shapeOf(entry.items) + ')'; - } else { - shape += entry.id + ';'; - } - } - return shape; - } + [[nodiscard]] static std::string shapeOf(std::vector const& entries); // The entry at @p path through @p entries; null past the end, which a binding reads only in the moment before // the menu is drawn again for a new shape. [[nodiscard]] static HeadMenuEntry const* entryAt(std::vector const& entries, - std::vector const& path) { - std::vector const* level = &entries; - HeadMenuEntry const* entry = nullptr; - for (std::size_t const index : path) { - if (index >= level->size()) { - return nullptr; - } - entry = &level->at(index); - level = &entry->items; - } - return entry; - } + std::vector const& path); // The menu items of one level of the head menu: each bound to its entry by its place, which the shape keeps, and // each chosen by its id, so the screen refuses an entry hidden since by name rather than running its neighbour. // NOLINTNEXTLINE(misc-no-recursion): a submenu is a menu one level down. [[nodiscard]] std::vector headMenuItems(WorkspaceTabId tab, reactive::Signal const& menu, std::vector const& level, - std::vector const& outer) const { - std::vector items; - for (std::size_t index = 0; index < level.size(); ++index) { - HeadMenuEntry const& entry = level.at(index); - MenuItem item; - if (entry.separator) { - item.separator = true; - items.push_back(std::move(item)); - continue; - } - std::vector path = outer; - path.push_back(index); - auto const read = [&menu, path](auto field, auto const& fallback) { - return [&menu, path, field, fallback] { - HeadMenuEntry const* const shown = entryAt(menu.get().entries, path); - return shown == nullptr ? fallback : std::invoke(field, *shown); - }; - }; - item.label = Prop{read(&HeadMenuEntry::label, std::string{})}; - item.description = Prop{read(&HeadMenuEntry::description, std::string{})}; - item.enabled = Prop{read(&HeadMenuEntry::enabled, false)}; - item.checked = Prop>{read(&HeadMenuEntry::checked, std::optional{})}; - item.icon = entry.icon; - item.keys = entry.keys; - if (entry.items.empty()) { - item.onSelect = [this, tab, entryId = entry.id] { - ScreenHandle* const handle = _model->handleOf(tab); - if (ScreenHead* const head = handle == nullptr ? nullptr : handle->head()) { - head->choose(entryId); - } - }; - } else { - item.items = headMenuItems(tab, menu, entry.items, path); - } - items.push_back(std::move(item)); - } - return items; - } + std::vector const& outer) const; - [[nodiscard]] std::optional tabAt(std::size_t index) const { - std::vector const order = _model->order(); - return index < order.size() ? std::optional{order.at(index)} : std::nullopt; - } + [[nodiscard]] std::optional tabAt(std::size_t index) const; - [[nodiscard]] std::size_t indexOf(WorkspaceTabId tab) const { - std::vector const order = _model->order(); - auto const found = std::ranges::find(order, tab); - return found == order.end() ? kNone : static_cast(found - order.begin()); - } + [[nodiscard]] std::size_t indexOf(WorkspaceTabId tab) const; - [[nodiscard]] std::string_view screenOf(WorkspaceTabId tab) const { - auto const found = _pages.find(tab.value); - return found == _pages.end() ? std::string_view{} : std::string_view{found->second->screenId}; - } + [[nodiscard]] std::string_view screenOf(WorkspaceTabId tab) const; - [[nodiscard]] static std::string captionOf(ScreenHandle const& handle) { - std::string caption = handle.title().peek(); - if (handle.dirty().peek()) { - caption += " •"; - } - return caption; - } + [[nodiscard]] static std::string captionOf(ScreenHandle const& handle); // The model's mountPage: a page slot at the end of the bar, the screen mounted into it, a host screen from the // registry and a document screen from the document host, then the head row above it. The page goes with a // refused mount. std::expected, MountError> mountPage(WorkspaceTabId tab, std::string_view screenId, - ParamMap const& params) { - auto page = std::make_unique(); - page->screenId = std::string{screenId}; - page->slot = _backend->createSlot(_bar.get()); - page->slot->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); - // A screen whose root keeps its content height scrolls inside the page instead of being cut at the window's - // edge; one whose root stretches fills the page and lays itself out. - page->slot->setScrollable(true); - page->slot->setVisible(false); - std::expected, MountError> handle; - WorkspaceScreen const facts = _screens ? _screens(screenId) : WorkspaceScreen{}; - if (facts.host.empty()) { - handle = _host->mountInto(screenId, params, *page->slot); - } else { - HostScreenFactory const* const factory = _hosts == nullptr ? nullptr : _hosts->find(facts.host); - if (factory == nullptr) { - return std::unexpected(MountError{.screenId = std::string{screenId}, - .reason = "no host screen `" + facts.host + "` is registered"}); - } - handle = (*factory)(params, *page->slot); - } - if (!handle) { - return handle; - } - if (_headPlacement == HeadPlacement::InPage && (*handle)->head() != nullptr) { - // Mounted after the screen, since it reads the handle, and moved above it. - page->head.emplace(*_runtime, *_backend, headRow(tab), page->slot.get()); - page->slot->moveChild(page->head->root(), 0); - } - _pages.insert_or_assign(tab.value, std::move(page)); - _shownOrder.push_back(tab); - return handle; - } + ParamMap const& params); // The head of a tab's screen, while the tab is open. A tracked read of the model's tabs, so a binding made while // the model is still opening the tab reads the head once it holds it. - [[nodiscard]] ScreenHead* headOf(WorkspaceTabId tab) const { - static_cast(_model->tabs().get()); - ScreenHandle* const handle = _model->handleOf(tab); - return handle == nullptr ? nullptr : handle->head(); - } + [[nodiscard]] ScreenHead* headOf(WorkspaceTabId tab) const; // The visible entries of a tab's head menu; a tracked read. - [[nodiscard]] std::vector headMenuOf(WorkspaceTabId tab) const { - ScreenHead const* const head = headOf(tab); - reactive::Computed> const* const menu = head == nullptr ? nullptr : head->menu(); - return menu == nullptr ? std::vector{} : menu->get(); - } + [[nodiscard]] std::vector headMenuOf(WorkspaceTabId tab) const; // The visible tools of a tab's head; a tracked read. - [[nodiscard]] std::vector headToolsOf(WorkspaceTabId tab) const { - ScreenHead const* const head = headOf(tab); - reactive::Computed> const* const tools = head == nullptr ? nullptr : head->tools(); - return tools == nullptr ? std::vector{} : tools->get(); - } + [[nodiscard]] std::vector headToolsOf(WorkspaceTabId tab) const; // Whether a tab's head has a subtitle, a badge, a tool, an action or a menu entry; a tracked read. [[nodiscard]] bool headHasContent(WorkspaceTabId tab) const { @@ -877,131 +413,34 @@ class Workspace { [[nodiscard]] bool eyebrowHasContent(WorkspaceTabId tab) const { return !eyebrowRunsOf(tab).empty(); } // The head's eyebrow runs when the screen gives them, else its plain eyebrow as one run; a tracked read. - [[nodiscard]] std::vector eyebrowRunsOf(WorkspaceTabId tab) const { - ScreenHead const* const head = headOf(tab); - if (head == nullptr) { - return {}; - } - reactive::Computed> const* const spans = head->eyebrowSpans(); - std::vector runs = spans == nullptr ? std::vector{} : spans->get(); - if (runs.empty()) { - reactive::Computed const* const plain = head->eyebrow(); - std::string line = plain == nullptr ? std::string{} : plain->get(); - if (!line.empty()) { - runs.push_back(TextSpan{.text = std::move(line)}); - } - } - return runs; - } + [[nodiscard]] std::vector eyebrowRunsOf(WorkspaceTabId tab) const; // The head's eyebrow as a muted text, hidden while there is none. - [[nodiscard]] Text buildHeadEyebrow(WorkspaceTabId tab) const { - auto const plain = [this, tab] { - ScreenHead const* const head = headOf(tab); - reactive::Computed const* const eyebrow = head == nullptr ? nullptr : head->eyebrow(); - return eyebrow == nullptr ? std::string{} : eyebrow->get(); - }; - Text text{.text = Prop{plain}, .role = TextRole::Muted, .field = {}, .common = {}}; - text.spans = Prop>{[this, tab] { return eyebrowRunsOf(tab); }}; - text.common.testId = "head_eyebrow"; - text.common.visible = Prop{[this, tab] { return eyebrowHasContent(tab); }}; - return text; - } + [[nodiscard]] Text buildHeadEyebrow(WorkspaceTabId tab) const; // Whether the head has a subtitle or a badge. - [[nodiscard]] bool leadHasContent(WorkspaceTabId tab) const { - ScreenHead const* const head = headOf(tab); - return head != nullptr && - (!head->subtitle().get().empty() || !subtitleSpansOf(head).empty() || !head->status().get().empty()); - } + [[nodiscard]] bool leadHasContent(WorkspaceTabId tab) const; // The head's title runs; a tracked read, empty for a head that has none. - [[nodiscard]] static std::vector titleSpansOf(ScreenHead const* head) { - reactive::Computed> const* const spans = head == nullptr ? nullptr : head->titleSpans(); - return spans == nullptr ? std::vector{} : spans->get(); - } + [[nodiscard]] static std::vector titleSpansOf(ScreenHead const* head); // The head's subtitle runs; a tracked read, empty for a head that has none. - [[nodiscard]] static std::vector subtitleSpansOf(ScreenHead const* head) { - reactive::Computed> const* const spans = - head == nullptr ? nullptr : head->subtitleSpans(); - return spans == nullptr ? std::vector{} : spans->get(); - } + [[nodiscard]] static std::vector subtitleSpansOf(ScreenHead const* head); // Whether the head has a tool, an action or a menu entry. // An `end` lead counts: it sits in the trail. - [[nodiscard]] bool trailHasContent(WorkspaceTabId tab) const { - ScreenHead const* const head = headOf(tab); - return head != nullptr && - (!headToolsOf(tab).empty() || !head->actions().get().empty() || !headMenuOf(tab).empty() || - (leadPlacementOf(tab) == LeadPlacement::End && leadHasContent(tab))); - } + [[nodiscard]] bool trailHasContent(WorkspaceTabId tab) const; // Where a tab's head puts its lead; a tracked read. In the page there is no title line to follow, so `Inline` // draws as `Below`. - [[nodiscard]] LeadPlacement leadPlacementOf(WorkspaceTabId tab) const { - ScreenHead const* const head = headOf(tab); - reactive::Computed const* const placement = head == nullptr ? nullptr : head->leadPlacement(); - LeadPlacement const place = placement == nullptr ? LeadPlacement::Below : placement->get(); - return place == LeadPlacement::Inline && _headPlacement == HeadPlacement::InPage ? LeadPlacement::Below - : place; - } + [[nodiscard]] LeadPlacement leadPlacementOf(WorkspaceTabId tab) const; // A tool of the head row: a search field or a select bound to the tool's value, its label the accessible name and // no caption, reporting each edit to the head, which runs the document's commands. - [[nodiscard]] Node headTool(WorkspaceTabId tab, reactive::Signal const& tool) const { - std::string const toolId = tool.peek().id; - auto const report = [this, tab, toolId](Value const& value) { - ScreenHandle* const handle = _model->handleOf(tab); - if (ScreenHead* const head = handle == nullptr ? nullptr : handle->head()) { - head->edit(toolId, value); - } - }; - Common common; - common.testId = "head_tool_" + toolId; - common.enabled = Prop{[&tool] { return tool.get().enabled; }}; - common.a11y.name = Prop{[&tool] { return tool.get().label; }}; - if (int const width = tool.peek().width; width > 0) { - common.layout.width = Sizing::fixed(width); - } - if (tool.peek().kind == HeadToolKind::Select) { - Select select; - select.options = Prop>{[&tool] { return tool.get().options; }}; - select.selected = Prop>{[&tool] { return tool.get().selected; }}; - select.onSelect = [report](Key const& key) { report(detail::valueOfKey(key)); }; - select.label = Prop{[&tool] { return tool.get().label; }}; - select.common = std::move(common); - return ui::select(std::move(select)); - } - TextInput input; - input.value = Prop{[&tool] { return tool.get().value; }}; - input.placeholder = Prop{[&tool] { return tool.get().placeholder; }}; - input.label = Prop{[&tool] { return tool.get().label; }}; - input.onChange = [report](std::string text) { report(Value{std::move(text)}); }; - // A submit of text the tool does not show yet reports it as an edit first, so `onSubmit` reads what was - // submitted. - input.onSubmit = [this, tab, toolId, &tool](std::string const& text) { - ScreenHandle* const handle = _model->handleOf(tab); - ScreenHead* const head = handle == nullptr ? nullptr : handle->head(); - if (head == nullptr) { - return; - } - if (text != tool.peek().value) { - head->edit(toolId, Value{text}); - } - head->submit(toolId); - }; - input.common = std::move(common); - return ui::textInput(std::move(input)); - } + [[nodiscard]] Node headTool(WorkspaceTabId tab, reactive::Signal const& tool) const; // The test-id suffix of the lead built for @p place: none for the copy under the title. - [[nodiscard]] static std::string idSuffix(LeadPlacement place) { - if (place == LeadPlacement::Inline) { - return "_inline"; - } - return place == LeadPlacement::End ? "_end" : ""; - } + [[nodiscard]] static std::string idSuffix(LeadPlacement place); // The head's lead, built but not yet wrapped into an immutable Node: the subtitle (muted) and the badges on one // wrapping line, so they sit side by side while they fit and wrap under one another where they do not; the badges' @@ -1012,202 +451,20 @@ class Workspace { // from its minimum. The `Inline` copy stretches with none, so it fills what the title's line gives it and its // subtitle wraps there, while the frame's slot, still content-sized, holds the spare width. The `End` copy is // content-sized, in the trail. - [[nodiscard]] Row buildHeadLead(WorkspaceTabId tab, LeadPlacement place) const { - std::string const suffix = idSuffix(place); - auto const subtitle = [this, tab] { - ScreenHead const* const head = headOf(tab); - return head == nullptr ? std::string{} : head->subtitle().get(); - }; - auto const status = [this, tab] { - ScreenHead const* const head = headOf(tab); - return head == nullptr ? std::vector{} : head->status().get(); - }; - Row row{.children = {}, .gap = 1, .common = {}, .tone = std::nullopt}; - row.wrap = true; - row.align = Align::Center; - row.common.testId = "head_lead" + suffix; - if (place == LeadPlacement::Below) { - row.common.layout.width = Sizing::stretch(); - row.common.layout.minWidth = kHeadLeadMinimum; - } else if (place == LeadPlacement::Inline) { - row.common.layout.width = Sizing::stretch(); - } - row.common.visible = - Prop{[this, tab, place] { return leadHasContent(tab) && leadPlacementOf(tab) == place; }}; - // The runs when the screen gives them, else its plain subtitle as one run, so the text is bound to one thing. - auto const spans = [this, tab, subtitle] { - std::vector runs = subtitleSpansOf(headOf(tab)); - if (runs.empty()) { - std::string plain = subtitle(); - if (!plain.empty()) { - runs.push_back(TextSpan{.text = std::move(plain)}); - } - } - return runs; - }; - Text text{.text = Prop{subtitle}, .role = TextRole::Muted, .field = {}, .common = {}}; - text.spans = Prop>{spans}; - text.common.testId = "head_subtitle" + suffix; - text.common.visible = Prop{[spans] { return !spans().empty(); }}; - row.children.push_back(ui::text(std::move(text))); - row.children.push_back(ui::forEach( - [status] { - std::vector placed; - for (HeadBadge const& badge : status()) { - placed.push_back(PlacedBadge{.index = placed.size(), .badge = badge}); - } - return placed; - }, - [](PlacedBadge const& placed) { return Key{static_cast(placed.index)}; }, - [suffix](reactive::Signal const& placed) { - Badge badge{.tone = Prop{[&placed] { return placed.get().badge.tone; }}, - .text = Prop{[&placed] { return placed.get().badge.text; }}, - .icon = placed.peek().badge.icon, - .common = {}}; - badge.common.testId = "head_status" + suffix + "_" + std::to_string(placed.peek().index); - return ui::badge(std::move(badge)); - }, - Axis::Horizontal, 1, {}, true)); - return row; - } + [[nodiscard]] Row buildHeadLead(WorkspaceTabId tab, LeadPlacement place) const; // The head's trail: the tools, the actions as buttons and the head's own menu behind one icon button, in one row. // It is a row of actions: its parts are the theme's action gap apart, and it wraps, so a part with nothing in it // takes none. Hidden while the head has none of them. - [[nodiscard]] ActionBar buildHeadTrail(WorkspaceTabId tab) const { - auto const actions = [this, tab] { - ScreenHead const* const head = headOf(tab); - return head == nullptr ? std::vector{} : head->actions().get(); - }; - ActionBar row; - // Wrapping, so a part with nothing in it (no tools, no menu) takes no gap: a non-wrapping row would leave one - // after the last action, short of the edge by a step. - row.wrap = true; - row.common.testId = "head_trail"; - row.common.visible = Prop{[this, tab] { return trailHasContent(tab); }}; - row.align = Align::Center; - row.children.push_back(ui::forEach( - [this, tab] { return headToolsOf(tab); }, [](HeadTool const& tool) { return Key{tool.id}; }, - [this, tab](reactive::Signal const& tool) { return headTool(tab, tool); }, Axis::Horizontal, 1)); - row.children.push_back(ui::row(buildHeadLead(tab, LeadPlacement::End))); - row.children.push_back(ui::forEach( - actions, [](HeadAction const& action) { return Key{action.id}; }, - [this, tab](reactive::Signal const& action) { - Button button{.label = Prop{[&action] { - HeadAction const& current = action.get(); - return current.iconOnly ? std::string{} : current.label; - }}, - .emphasis = action.peek().emphasis, - .onClick = - [this, tab, actionId = action.peek().id] { - ScreenHandle* const handle = _model->handleOf(tab); - if (ScreenHead* const head = handle == nullptr ? nullptr : handle->head()) { - head->run(actionId); - } - }, - .common = {}, - .icon = action.peek().icon}; - button.common.testId = "head_action_" + action.peek().id; - // An icon-only button is named and titled by its label, which it does not draw. - auto const labelWhenIconOnly = [&action] { - HeadAction const& current = action.get(); - return current.iconOnly ? current.label : std::string{}; - }; - button.common.a11y.name = Prop{labelWhenIconOnly}; - button.common.tooltip = Prop{labelWhenIconOnly}; - button.common.enabled = Prop{[&action] { return action.get().enabled; }}; - return ui::button(std::move(button)); - }, - Axis::Horizontal, 1)); - row.children.push_back(ui::forEach( - [this, tab] { - std::vector entries = headMenuOf(tab); - if (entries.empty()) { - return std::vector{}; - } - std::string shape = shapeOf(entries); - return std::vector{ShapedMenu{.shape = std::move(shape), .entries = std::move(entries)}}; - }, - [](ShapedMenu const& menu) { return Key{menu.shape}; }, - [this, tab](reactive::Signal const& menu) { - Menu spec{.items = headMenuItems(tab, menu, menu.peek().entries, {}), - .common = {}, - .style = MenuStyle::Button, - .label = {}, - .icon = "more", - .emphasis = ButtonEmphasis::Normal}; - // The trigger draws the icon alone; its name is the head's `menuLabel`. - Prop const name{[this, tab] { - ScreenHead const* const head = headOf(tab); - reactive::Computed const* const label = head == nullptr ? nullptr : head->menuLabel(); - return label == nullptr ? std::string{"More actions"} : label->get(); - }}; - spec.common.a11y.name = name; - spec.common.tooltip = name; - spec.common.testId = "head_menu"; - return ui::menu(std::move(spec)); - }, - Axis::Horizontal, 1)); - return row; - } + [[nodiscard]] ActionBar buildHeadTrail(WorkspaceTabId tab) const; // The head above a tab's screen: the eyebrow, then the row of the lead and the trail on one wrapping line, the // trail at the trailing edge, dropping to a line of its own where it does not fit beside the lead's minimum. // Hidden while the head has no content, so a screen without a head looks as it would without it. - [[nodiscard]] Node headRow(WorkspaceTabId tab) const { - Row row{.children = {}, .gap = 2, .common = {}, .tone = std::nullopt}; - row.children.push_back(ui::row(buildHeadLead(tab, LeadPlacement::Below))); - row.children.push_back(ui::actionBar(buildHeadTrail(tab))); - row.common.testId = "head"; - row.common.layout.width = Sizing::stretch(); - row.common.visible = Prop{[this, tab] { return leadHasContent(tab) || trailHasContent(tab); }}; - row.align = Align::Start; - row.justify = Justify::End; - row.wrap = true; - Column block{.children = {}, .gap = 1, .common = {}}; - block.children.push_back(ui::text(buildHeadEyebrow(tab))); - block.children.push_back(ui::row(std::move(row))); - block.common.testId = "head_block"; - block.common.layout.width = Sizing::stretch(); - block.common.visible = Prop{[this, tab] { return headHasContent(tab); }}; - return ui::column(std::move(block)); - } + [[nodiscard]] Node headRow(WorkspaceTabId tab) const; // The model changed: the bar shows its tabs in order, with their captions, and the active tab's page. - void showTabs() { - if (_model == nullptr) { - return; - } - std::vector const order = _model->order(); - std::optional const shown = _model->active().peek(); - std::vector captions; - captions.reserve(order.size()); - for (std::size_t index = 0; index < order.size(); ++index) { - auto const found = _pages.find(order.at(index).value); - if (found == _pages.end()) { - continue; - } - Page& page = *found->second; - // A tab the model moved (a reuseEmpty replacement) moves its page in the bar too; `_shownOrder` is the - // bar's own order of the pages. - if (index >= _shownOrder.size() || _shownOrder.at(index) != order.at(index)) { - std::erase(_shownOrder, order.at(index)); - _shownOrder.insert( - _shownOrder.begin() + static_cast(std::min(index, _shownOrder.size())), - order.at(index)); - _bar->moveChild(*page.slot, index); - } - page.slot->setVisible(shown == order.at(index)); - captions.push_back(captionOf(*_model->handleOf(order.at(index)))); - } - _bar->setTabs(captions); - _bar->setSelected(shown ? indexOf(*shown) : kNone); - // One tab needs no strip to choose it by; the chords still work with the strip hidden. - _bar->setBarShown(captions.size() > 1); - if (_onChanged) { - _onChanged(); - } - } + void showTabs(); reactive::Runtime* _runtime; IViewBackend* _backend; diff --git a/src/ui/workspace.cpp b/src/ui/workspace.cpp new file mode 100644 index 000000000..a60b0969c --- /dev/null +++ b/src/ui/workspace.cpp @@ -0,0 +1,894 @@ +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace morph::ui { + +Workspace::Workspace(reactive::Runtime& runtime MORPH_LIFETIMEBOUND, IViewBackend& backend MORPH_LIFETIMEBOUND, + DocumentScreenHost& host MORPH_LIFETIMEBOUND, WorkspaceOptions options, ContainerWidget* parent, + HeadPlacement headPlacement) + : _runtime{&runtime}, + _backend{&backend}, + _host{&host}, + _parent{parent}, + _bar{backend.createTabs(parent)}, + _hosts{options.hosts}, + _screens{options.screens}, + _onChanged{std::move(options.onChanged)}, + _diagnostics{options.diagnostics}, + _headPlacement{headPlacement} { + // The bar and each page fill what they are given, so a screen whose root stretches fills the page. + _bar->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); + _bar->setTabs({}); + _bar->setSelected(kNone); + _bar->setOnSelect([this](std::size_t index) { + std::vector const order = _model->order(); + if (index < order.size()) { + _model->activate(order.at(index)); + } + }); + _bar->setKeys({"Ctrl+Tab", "Ctrl+Shift+Tab", "Ctrl+W"}, [this](std::string const& chord) { + if (chord == "Ctrl+Tab") { + next(); + } else if (chord == "Ctrl+Shift+Tab") { + previous(); + } else if (std::optional const shown = active()) { + close(*shown, {}); + } + }); + WorkspaceModelOptions modelOptions{std::move(options), {}, {}}; + modelOptions.onChanged = [this] { showTabs(); }; + modelOptions.mountPage = [this](WorkspaceTabId tab, std::string_view screenId, ParamMap const& params) { + return mountPage(tab, screenId, params); + }; + modelOptions.unmountPage = [this](WorkspaceTabId tab) { + std::erase(_shownOrder, tab); + _pages.erase(tab.value); + }; + _model = std::make_unique(runtime, host, std::move(modelOptions)); +} + +Workspace::~Workspace() { + *_alive = false; + closeOverlays(); + _model.reset(); +} + +std::expected Workspace::open(std::string_view screenId, ParamMap const& params) { + auto opened = _model->open(screenId, params); + if (!opened) { + return std::unexpected(std::move(opened.error())); + } + return indexOf(*opened); +} + +std::expected Workspace::openOverlay(NavigateRequest const& request) { + if (request.as != "dialog" && request.as != "drawer") { + return std::unexpected( + MountError{.screenId = request.screen, .reason = "`as: " + request.as + "` is not a dialog or a drawer"}); + } + if (_screens && !_screens(request.screen).host.empty()) { + return std::unexpected( + MountError{.screenId = request.screen, .reason = "a host screen opens as a tab, not an overlay"}); + } + ValueRecord const* const record = request.params.asRecord(); + ParamMap const params = record == nullptr ? ParamMap{} : *record; + auto overlay = std::make_unique(); + overlay->id = ++_lastOverlay; + overlay->screenId = request.screen; + ContainerWidget* content = nullptr; + ContainerWidget* footer = nullptr; + if (request.as == "drawer") { + overlay->drawer = _backend->createDrawer(_parent, Side::End); + content = overlay->drawer.get(); + footer = &overlay->drawer->footer(); + } else { + overlay->dialog = _backend->createDialog(_parent); + content = overlay->dialog.get(); + footer = &overlay->dialog->footer(); + } + auto handle = _host->mountInto(request.screen, params, *content); + if (!handle) { + return std::unexpected(std::move(handle.error())); + } + overlay->handle = std::move(*handle); + showOverlay(*overlay, *footer); + _overlays.push_back(std::move(overlay)); + return {}; +} + +void Workspace::screenClosed(ScreenHandle const& screen) { + auto const overlay = std::ranges::find_if( + _overlays, [&screen](std::unique_ptr const& open) { return open->handle.get() == &screen; }); + if (overlay != _overlays.end()) { + _overlays.erase(overlay); + return; + } + for (WorkspaceTabId const tab : _model->order()) { + if (_model->handleOf(tab) == &screen) { + // The screen is closed, so its close answers at once and the tab goes. + _model->close(tab, {}); + return; + } + } +} + +std::vector Workspace::overlays() const { + std::vector out; + out.reserve(_overlays.size()); + for (auto const& overlay : _overlays) { + out.push_back(overlay->screenId); + } + return out; +} + +void Workspace::setWidthClass(std::string_view widthClass) { + bool const sheet = widthClass == "compact"; + for (auto const& overlay : _overlays) { + showSheet(*overlay, sheet); + } +} + +void Workspace::activate(std::size_t index) { + if (std::optional const tab = tabAt(index)) { + _model->activate(*tab); + } +} + +void Workspace::close(std::size_t index, std::function done) { + std::optional const tab = tabAt(index); + if (!tab) { + if (done) { + done(false); + } + return; + } + _model->close(*tab, std::move(done)); +} + +void Workspace::closeOthers(std::size_t index, std::function done) { + std::optional const tab = tabAt(index); + if (!tab) { + _model->closeAll(std::move(done)); + return; + } + _model->closeOthers(*tab, std::move(done)); +} + +std::optional Workspace::active() const { + std::optional const tab = _model->active().peek(); + if (!tab) { + return std::nullopt; + } + return indexOf(*tab); +} + +ScreenHandle* Workspace::handleOf(std::size_t index) const noexcept { + std::optional const tab = tabAt(index); + return tab ? _model->handleOf(*tab) : nullptr; +} + +ScreenHandle* Workspace::activeHandle() const { + std::optional const shown = active(); + return shown ? handleOf(*shown) : nullptr; +} + +HeadParts Workspace::headPartsForActive() const { + std::optional const tab = _model->active().peek(); + if (tab) { + // A host places the lead beside the title and gives it the minimum width it wants, so the lead has none + // of its own: with one, a lead's natural width would never be less than it. + Row lead = buildHeadLead(*tab, LeadPlacement::Below); + lead.common.layout.minWidth.reset(); + return HeadParts{.eyebrow = ui::text(buildHeadEyebrow(*tab)), + .lead = ui::row(std::move(lead)), + .trail = ui::actionBar(buildHeadTrail(*tab)), + .inlineLead = ui::row(buildHeadLead(*tab, LeadPlacement::Inline))}; + } + Text eyebrow{.text = std::string{}, .role = TextRole::Muted, .field = {}, .common = {}}; + eyebrow.common.testId = "head_eyebrow"; + eyebrow.common.visible = false; + Row lead{.children = {}, .gap = 0, .common = {}, .tone = std::nullopt}; + lead.common.testId = "head_lead"; + lead.common.visible = false; + Row trail{.children = {}, .gap = 0, .common = {}, .tone = std::nullopt}; + trail.common.testId = "head_trail"; + trail.common.visible = false; + Row inlineLead{.children = {}, .gap = 0, .common = {}, .tone = std::nullopt}; + inlineLead.common.testId = "head_lead_inline"; + inlineLead.common.visible = false; + return HeadParts{.eyebrow = ui::text(std::move(eyebrow)), + .lead = ui::row(std::move(lead)), + .trail = ui::row(std::move(trail)), + .inlineLead = ui::row(std::move(inlineLead))}; +} + +LeadPlacement Workspace::activeLeadPlacement() const { + std::optional const tab = _model->active().get(); + return tab ? leadPlacementOf(*tab) : LeadPlacement::Below; +} + +bool Workspace::activeHeadOneLine() const { + std::optional const tab = _model->active().get(); + if (!tab) { + return true; + } + bool const leadUnderTitle = leadHasContent(*tab) && leadPlacementOf(*tab) == LeadPlacement::Below; + return !(eyebrowHasContent(*tab) || leadUnderTitle); +} + +HeadTrailEnd Workspace::activeHeadTrailEnd() const { + std::optional const tab = _model->active().get(); + if (!tab) { + return HeadTrailEnd::None; + } + if (!headMenuOf(*tab).empty()) { + return HeadTrailEnd::Unframed; + } + ScreenHead const* const head = headOf(*tab); + if (head == nullptr) { + return HeadTrailEnd::None; + } + std::vector const actions = head->actions().get(); + if (!actions.empty()) { + return actions.back().iconOnly || actions.back().emphasis == ButtonEmphasis::Ghost ? HeadTrailEnd::Unframed + : HeadTrailEnd::Framed; + } + return headToolsOf(*tab).empty() ? HeadTrailEnd::None : HeadTrailEnd::Framed; +} + +bool Workspace::activeHeadJoined() const { + std::optional const tab = _model->active().get(); + if (!tab || activePageInset()) { + return false; + } + ScreenHead const* const head = headOf(*tab); + reactive::Computed const* const joined = head == nullptr ? nullptr : head->headJoined(); + return joined != nullptr && joined->get(); +} + +TextRole Workspace::activeTitleRole() const { + std::optional const tab = _model->active().get(); + ScreenHead const* const head = tab ? headOf(*tab) : nullptr; + reactive::Computed const* const role = head == nullptr ? nullptr : head->titleRole(); + return role == nullptr ? TextRole::Heading : role->get(); +} + +std::string Workspace::activeHeadSurface() const { + std::optional const tab = _model->active().get(); + ScreenHead const* const head = tab ? headOf(*tab) : nullptr; + reactive::Computed const* const surface = head == nullptr ? nullptr : head->headSurface(); + return surface == nullptr ? std::string{} : surface->get(); +} + +std::string Workspace::activePageSurface() const { + std::optional const tab = _model->active().get(); + ScreenHead const* const head = tab ? headOf(*tab) : nullptr; + reactive::Computed const* const surface = head == nullptr ? nullptr : head->pageSurface(); + return surface == nullptr ? std::string{} : surface->get(); +} + +std::vector Workspace::activeTitleSpans() const { + std::optional const tab = _model->active().get(); + return tab ? titleSpansOf(headOf(*tab)) : std::vector{}; +} + +bool Workspace::activePageInset() const { + std::optional const tab = _model->active().get(); + if (!tab || _model->tabs().get().size() > 1) { + return true; + } + ScreenHead const* const head = headOf(*tab); + reactive::Computed const* const edge = head == nullptr ? nullptr : head->pageEdge(); + return edge == nullptr || !edge->get(); +} + +bool Workspace::activeHeadShown() const { + std::optional const tab = _model->active().get(); + return tab.has_value() && headHasContent(*tab); +} + +void Workspace::forceCloseAll() { + closeOverlays(); + _model->forceCloseAll(); +} + +std::vector Workspace::tabs() const { + std::vector out; + for (WorkspaceTabId const tab : _model->order()) { + ScreenHandle const& handle = *_model->handleOf(tab); + out.push_back(WorkspaceTab{.screenId = std::string{screenOf(tab)}, + .identity = handle.identity().peek(), + .caption = captionOf(handle)}); + } + return out; +} + +Workspace::Page::~Page() { + head.reset(); + slot.reset(); +} + +Workspace::Overlay::~Overlay() { + scope.reset(); + footer.reset(); + handle.reset(); + drawer.reset(); + dialog.reset(); +} + +void Workspace::Overlay::setOpen(bool open) const { + if (dialog) { + dialog->setOpen(open); + } else { + drawer->setOpen(open); + } +} + +void Workspace::showSheet(Overlay& overlay, bool sheet) { + if (overlay.dialog && sheet != overlay.sheet) { + overlay.sheet = sheet; + overlay.dialog->setSheet(sheet); + } +} + +void Workspace::showOverlay(Overlay& overlay, ContainerWidget& footer) { + ScreenHandle const* const handle = overlay.handle.get(); + ScreenHead* const head = overlay.handle->head(); + overlay.scope = std::make_unique(*_runtime); + overlay.scope->effect([&overlay, handle] { + std::string const title = handle->title().get(); + if (overlay.dialog) { + overlay.dialog->setTitle(title); + } else { + overlay.drawer->setTitle(title); + } + }); + if (head != nullptr) { + overlay.footer.emplace(*_runtime, *_backend, overlayActions(*head), &footer); + overlay.scope->effect([this, &overlay, head] { + bool const menu = head->menu() != nullptr && !head->menu()->get().empty(); + bool const tools = head->tools() != nullptr && !head->tools()->get().empty(); + if ((menu || tools) && !overlay.reported) { + overlay.reported = true; + _runtime->untracked([this, &overlay] { + if (_diagnostics) { + _diagnostics(Refusal{.document = overlay.screenId, + .path = {}, + .reason = "a dialog or drawer does not show the head menu or tools " + "of " + + overlay.screenId}); + } + }); + } + }); + } + showSheet(overlay, _backend->widthClass() == "compact"); + std::uint64_t const overlayId = overlay.id; + auto const dismissed = [this, overlayId] { + Overlay const* const shown = overlayOf(overlayId); + if (shown == nullptr) { + return; + } + // The dismissal closed the widget. It is opened again at once, so the screen stays reachable while its + // close protocol runs, and goes only when the screen closed: a dirty screen without a guard stays. + shown->setOpen(true); + shown->handle->requestClose([this, alive = std::weak_ptr{_alive}, overlayId](bool closed) { + if (auto const live = alive.lock(); live != nullptr && *live && closed) { + removeOverlay(overlayId); + } + }); + }; + if (overlay.dialog) { + overlay.dialog->setOnDismiss(dismissed); + } else { + overlay.drawer->setOnDismiss(dismissed); + } + overlay.setOpen(true); +} + +Node Workspace::overlayActions(ScreenHead& head) { + ActionBar bar; + bar.common.testId = "overlay_actions"; + bar.common.visible = Prop{[&head] { return !head.actions().get().empty(); }}; + bar.children.push_back(ui::forEach( + [&head] { return head.actions().get(); }, [](HeadAction const& action) { return Key{action.id}; }, + [&head](reactive::Signal const& action) { + Button button{.label = Prop{[&action] { return action.get().label; }}, + .emphasis = action.peek().emphasis, + .onClick = [&head, actionId = action.peek().id] { head.run(actionId); }, + .common = {}}; + button.common.testId = "overlay_action_" + action.peek().id; + button.common.enabled = Prop{[&action] { return action.get().enabled; }}; + return ui::button(std::move(button)); + }, + Axis::Horizontal, 2)); + return ui::actionBar(std::move(bar)); +} + +Workspace::Overlay const* Workspace::overlayOf(std::uint64_t overlayId) const { + auto const found = std::ranges::find(_overlays, overlayId, [](auto const& open) { return open->id; }); + return found == _overlays.end() ? nullptr : found->get(); +} + +void Workspace::closeOverlays() { + while (!_overlays.empty()) { + std::unique_ptr const last = std::move(_overlays.back()); + _overlays.pop_back(); + last->handle->forceClose(); + } +} + +std::string Workspace::shapeOf(std::vector const& entries) { + std::string shape; + for (HeadMenuEntry const& entry : entries) { + if (entry.separator) { + shape += '|'; + } else if (!entry.items.empty()) { + shape += '(' + shapeOf(entry.items) + ')'; + } else { + shape += entry.id + ';'; + } + } + return shape; +} + +HeadMenuEntry const* Workspace::entryAt(std::vector const& entries, + std::vector const& path) { + std::vector const* level = &entries; + HeadMenuEntry const* entry = nullptr; + for (std::size_t const index : path) { + if (index >= level->size()) { + return nullptr; + } + entry = &level->at(index); + level = &entry->items; + } + return entry; +} + +std::vector Workspace::headMenuItems(WorkspaceTabId tab, reactive::Signal const& menu, + std::vector const& level, + std::vector const& outer) const { + std::vector items; + for (std::size_t index = 0; index < level.size(); ++index) { + HeadMenuEntry const& entry = level.at(index); + MenuItem item; + if (entry.separator) { + item.separator = true; + items.push_back(std::move(item)); + continue; + } + std::vector path = outer; + path.push_back(index); + auto const read = [&menu, path](auto field, auto const& fallback) { + return [&menu, path, field, fallback] { + HeadMenuEntry const* const shown = entryAt(menu.get().entries, path); + return shown == nullptr ? fallback : std::invoke(field, *shown); + }; + }; + item.label = Prop{read(&HeadMenuEntry::label, std::string{})}; + item.description = Prop{read(&HeadMenuEntry::description, std::string{})}; + item.enabled = Prop{read(&HeadMenuEntry::enabled, false)}; + item.checked = Prop>{read(&HeadMenuEntry::checked, std::optional{})}; + item.icon = entry.icon; + item.keys = entry.keys; + if (entry.items.empty()) { + item.onSelect = [this, tab, entryId = entry.id] { + ScreenHandle* const handle = _model->handleOf(tab); + if (ScreenHead* const head = handle == nullptr ? nullptr : handle->head()) { + head->choose(entryId); + } + }; + } else { + item.items = headMenuItems(tab, menu, entry.items, path); + } + items.push_back(std::move(item)); + } + return items; +} + +std::optional Workspace::tabAt(std::size_t index) const { + std::vector const order = _model->order(); + return index < order.size() ? std::optional{order.at(index)} : std::nullopt; +} + +std::size_t Workspace::indexOf(WorkspaceTabId tab) const { + std::vector const order = _model->order(); + auto const found = std::ranges::find(order, tab); + return found == order.end() ? kNone : static_cast(found - order.begin()); +} + +std::string_view Workspace::screenOf(WorkspaceTabId tab) const { + auto const found = _pages.find(tab.value); + return found == _pages.end() ? std::string_view{} : std::string_view{found->second->screenId}; +} + +std::string Workspace::captionOf(ScreenHandle const& handle) { + std::string caption = handle.title().peek(); + if (handle.dirty().peek()) { + caption += " •"; + } + return caption; +} + +std::expected, MountError> Workspace::mountPage(WorkspaceTabId tab, + std::string_view screenId, + ParamMap const& params) { + auto page = std::make_unique(); + page->screenId = std::string{screenId}; + page->slot = _backend->createSlot(_bar.get()); + page->slot->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); + // A screen whose root keeps its content height scrolls inside the page instead of being cut at the window's + // edge; one whose root stretches fills the page and lays itself out. + page->slot->setScrollable(true); + page->slot->setVisible(false); + std::expected, MountError> handle; + WorkspaceScreen const facts = _screens ? _screens(screenId) : WorkspaceScreen{}; + if (facts.host.empty()) { + handle = _host->mountInto(screenId, params, *page->slot); + } else { + HostScreenFactory const* const factory = _hosts == nullptr ? nullptr : _hosts->find(facts.host); + if (factory == nullptr) { + return std::unexpected(MountError{.screenId = std::string{screenId}, + .reason = "no host screen `" + facts.host + "` is registered"}); + } + handle = (*factory)(params, *page->slot); + } + if (!handle) { + return handle; + } + if (_headPlacement == HeadPlacement::InPage && (*handle)->head() != nullptr) { + // Mounted after the screen, since it reads the handle, and moved above it. + page->head.emplace(*_runtime, *_backend, headRow(tab), page->slot.get()); + page->slot->moveChild(page->head->root(), 0); + } + _pages.insert_or_assign(tab.value, std::move(page)); + _shownOrder.push_back(tab); + return handle; +} + +ScreenHead* Workspace::headOf(WorkspaceTabId tab) const { + static_cast(_model->tabs().get()); + ScreenHandle* const handle = _model->handleOf(tab); + return handle == nullptr ? nullptr : handle->head(); +} + +std::vector Workspace::headMenuOf(WorkspaceTabId tab) const { + ScreenHead const* const head = headOf(tab); + reactive::Computed> const* const menu = head == nullptr ? nullptr : head->menu(); + return menu == nullptr ? std::vector{} : menu->get(); +} + +std::vector Workspace::headToolsOf(WorkspaceTabId tab) const { + ScreenHead const* const head = headOf(tab); + reactive::Computed> const* const tools = head == nullptr ? nullptr : head->tools(); + return tools == nullptr ? std::vector{} : tools->get(); +} + +std::vector Workspace::eyebrowRunsOf(WorkspaceTabId tab) const { + ScreenHead const* const head = headOf(tab); + if (head == nullptr) { + return {}; + } + reactive::Computed> const* const spans = head->eyebrowSpans(); + std::vector runs = spans == nullptr ? std::vector{} : spans->get(); + if (runs.empty()) { + reactive::Computed const* const plain = head->eyebrow(); + std::string line = plain == nullptr ? std::string{} : plain->get(); + if (!line.empty()) { + runs.push_back(TextSpan{.text = std::move(line)}); + } + } + return runs; +} + +Text Workspace::buildHeadEyebrow(WorkspaceTabId tab) const { + auto const plain = [this, tab] { + ScreenHead const* const head = headOf(tab); + reactive::Computed const* const eyebrow = head == nullptr ? nullptr : head->eyebrow(); + return eyebrow == nullptr ? std::string{} : eyebrow->get(); + }; + Text text{.text = Prop{plain}, .role = TextRole::Muted, .field = {}, .common = {}}; + text.spans = Prop>{[this, tab] { return eyebrowRunsOf(tab); }}; + text.common.testId = "head_eyebrow"; + text.common.visible = Prop{[this, tab] { return eyebrowHasContent(tab); }}; + return text; +} + +bool Workspace::leadHasContent(WorkspaceTabId tab) const { + ScreenHead const* const head = headOf(tab); + return head != nullptr && + (!head->subtitle().get().empty() || !subtitleSpansOf(head).empty() || !head->status().get().empty()); +} + +std::vector Workspace::titleSpansOf(ScreenHead const* head) { + reactive::Computed> const* const spans = head == nullptr ? nullptr : head->titleSpans(); + return spans == nullptr ? std::vector{} : spans->get(); +} + +std::vector Workspace::subtitleSpansOf(ScreenHead const* head) { + reactive::Computed> const* const spans = head == nullptr ? nullptr : head->subtitleSpans(); + return spans == nullptr ? std::vector{} : spans->get(); +} + +bool Workspace::trailHasContent(WorkspaceTabId tab) const { + ScreenHead const* const head = headOf(tab); + return head != nullptr && + (!headToolsOf(tab).empty() || !head->actions().get().empty() || !headMenuOf(tab).empty() || + (leadPlacementOf(tab) == LeadPlacement::End && leadHasContent(tab))); +} + +LeadPlacement Workspace::leadPlacementOf(WorkspaceTabId tab) const { + ScreenHead const* const head = headOf(tab); + reactive::Computed const* const placement = head == nullptr ? nullptr : head->leadPlacement(); + LeadPlacement const place = placement == nullptr ? LeadPlacement::Below : placement->get(); + return place == LeadPlacement::Inline && _headPlacement == HeadPlacement::InPage ? LeadPlacement::Below : place; +} + +Node Workspace::headTool(WorkspaceTabId tab, reactive::Signal const& tool) const { + std::string const toolId = tool.peek().id; + auto const report = [this, tab, toolId](Value const& value) { + ScreenHandle* const handle = _model->handleOf(tab); + if (ScreenHead* const head = handle == nullptr ? nullptr : handle->head()) { + head->edit(toolId, value); + } + }; + Common common; + common.testId = "head_tool_" + toolId; + common.enabled = Prop{[&tool] { return tool.get().enabled; }}; + common.a11y.name = Prop{[&tool] { return tool.get().label; }}; + if (int const width = tool.peek().width; width > 0) { + common.layout.width = Sizing::fixed(width); + } + if (tool.peek().kind == HeadToolKind::Select) { + Select select; + select.options = Prop>{[&tool] { return tool.get().options; }}; + select.selected = Prop>{[&tool] { return tool.get().selected; }}; + select.onSelect = [report](Key const& key) { report(detail::valueOfKey(key)); }; + select.label = Prop{[&tool] { return tool.get().label; }}; + select.common = std::move(common); + return ui::select(std::move(select)); + } + TextInput input; + input.value = Prop{[&tool] { return tool.get().value; }}; + input.placeholder = Prop{[&tool] { return tool.get().placeholder; }}; + input.label = Prop{[&tool] { return tool.get().label; }}; + input.onChange = [report](std::string text) { report(Value{std::move(text)}); }; + // A submit of text the tool does not show yet reports it as an edit first, so `onSubmit` reads what was + // submitted. + input.onSubmit = [this, tab, toolId, &tool](std::string const& text) { + ScreenHandle* const handle = _model->handleOf(tab); + ScreenHead* const head = handle == nullptr ? nullptr : handle->head(); + if (head == nullptr) { + return; + } + if (text != tool.peek().value) { + head->edit(toolId, Value{text}); + } + head->submit(toolId); + }; + input.common = std::move(common); + return ui::textInput(std::move(input)); +} + +std::string Workspace::idSuffix(LeadPlacement place) { + if (place == LeadPlacement::Inline) { + return "_inline"; + } + return place == LeadPlacement::End ? "_end" : ""; +} + +Row Workspace::buildHeadLead(WorkspaceTabId tab, LeadPlacement place) const { + std::string const suffix = idSuffix(place); + auto const subtitle = [this, tab] { + ScreenHead const* const head = headOf(tab); + return head == nullptr ? std::string{} : head->subtitle().get(); + }; + auto const status = [this, tab] { + ScreenHead const* const head = headOf(tab); + return head == nullptr ? std::vector{} : head->status().get(); + }; + Row row{.children = {}, .gap = 1, .common = {}, .tone = std::nullopt}; + row.wrap = true; + row.align = Align::Center; + row.common.testId = "head_lead" + suffix; + if (place == LeadPlacement::Below) { + row.common.layout.width = Sizing::stretch(); + row.common.layout.minWidth = kHeadLeadMinimum; + } else if (place == LeadPlacement::Inline) { + row.common.layout.width = Sizing::stretch(); + } + row.common.visible = + Prop{[this, tab, place] { return leadHasContent(tab) && leadPlacementOf(tab) == place; }}; + // The runs when the screen gives them, else its plain subtitle as one run, so the text is bound to one thing. + auto const spans = [this, tab, subtitle] { + std::vector runs = subtitleSpansOf(headOf(tab)); + if (runs.empty()) { + std::string plain = subtitle(); + if (!plain.empty()) { + runs.push_back(TextSpan{.text = std::move(plain)}); + } + } + return runs; + }; + Text text{.text = Prop{subtitle}, .role = TextRole::Muted, .field = {}, .common = {}}; + text.spans = Prop>{spans}; + text.common.testId = "head_subtitle" + suffix; + text.common.visible = Prop{[spans] { return !spans().empty(); }}; + row.children.push_back(ui::text(std::move(text))); + row.children.push_back(ui::forEach( + [status] { + std::vector placed; + for (HeadBadge const& badge : status()) { + placed.push_back(PlacedBadge{.index = placed.size(), .badge = badge}); + } + return placed; + }, + [](PlacedBadge const& placed) { return Key{static_cast(placed.index)}; }, + [suffix](reactive::Signal const& placed) { + Badge badge{.tone = Prop{[&placed] { return placed.get().badge.tone; }}, + .text = Prop{[&placed] { return placed.get().badge.text; }}, + .icon = placed.peek().badge.icon, + .common = {}}; + badge.common.testId = "head_status" + suffix + "_" + std::to_string(placed.peek().index); + return ui::badge(std::move(badge)); + }, + Axis::Horizontal, 1, {}, true)); + return row; +} + +ActionBar Workspace::buildHeadTrail(WorkspaceTabId tab) const { + auto const actions = [this, tab] { + ScreenHead const* const head = headOf(tab); + return head == nullptr ? std::vector{} : head->actions().get(); + }; + ActionBar row; + // Wrapping, so a part with nothing in it (no tools, no menu) takes no gap: a non-wrapping row would leave one + // after the last action, short of the edge by a step. + row.wrap = true; + row.common.testId = "head_trail"; + row.common.visible = Prop{[this, tab] { return trailHasContent(tab); }}; + row.align = Align::Center; + row.children.push_back(ui::forEach( + [this, tab] { return headToolsOf(tab); }, [](HeadTool const& tool) { return Key{tool.id}; }, + [this, tab](reactive::Signal const& tool) { return headTool(tab, tool); }, Axis::Horizontal, 1)); + row.children.push_back(ui::row(buildHeadLead(tab, LeadPlacement::End))); + row.children.push_back(ui::forEach( + actions, [](HeadAction const& action) { return Key{action.id}; }, + [this, tab](reactive::Signal const& action) { + Button button{.label = Prop{[&action] { + HeadAction const& current = action.get(); + return current.iconOnly ? std::string{} : current.label; + }}, + .emphasis = action.peek().emphasis, + .onClick = + [this, tab, actionId = action.peek().id] { + ScreenHandle* const handle = _model->handleOf(tab); + if (ScreenHead* const head = handle == nullptr ? nullptr : handle->head()) { + head->run(actionId); + } + }, + .common = {}, + .icon = action.peek().icon}; + button.common.testId = "head_action_" + action.peek().id; + // An icon-only button is named and titled by its label, which it does not draw. + auto const labelWhenIconOnly = [&action] { + HeadAction const& current = action.get(); + return current.iconOnly ? current.label : std::string{}; + }; + button.common.a11y.name = Prop{labelWhenIconOnly}; + button.common.tooltip = Prop{labelWhenIconOnly}; + button.common.enabled = Prop{[&action] { return action.get().enabled; }}; + return ui::button(std::move(button)); + }, + Axis::Horizontal, 1)); + row.children.push_back(ui::forEach( + [this, tab] { + std::vector entries = headMenuOf(tab); + if (entries.empty()) { + return std::vector{}; + } + std::string shape = shapeOf(entries); + return std::vector{ShapedMenu{.shape = std::move(shape), .entries = std::move(entries)}}; + }, + [](ShapedMenu const& menu) { return Key{menu.shape}; }, + [this, tab](reactive::Signal const& menu) { + Menu spec{.items = headMenuItems(tab, menu, menu.peek().entries, {}), + .common = {}, + .style = MenuStyle::Button, + .label = {}, + .icon = "more", + .emphasis = ButtonEmphasis::Normal}; + // The trigger draws the icon alone; its name is the head's `menuLabel`. + Prop const name{[this, tab] { + ScreenHead const* const head = headOf(tab); + reactive::Computed const* const label = head == nullptr ? nullptr : head->menuLabel(); + return label == nullptr ? std::string{"More actions"} : label->get(); + }}; + spec.common.a11y.name = name; + spec.common.tooltip = name; + spec.common.testId = "head_menu"; + return ui::menu(std::move(spec)); + }, + Axis::Horizontal, 1)); + return row; +} + +Node Workspace::headRow(WorkspaceTabId tab) const { + Row row{.children = {}, .gap = 2, .common = {}, .tone = std::nullopt}; + row.children.push_back(ui::row(buildHeadLead(tab, LeadPlacement::Below))); + row.children.push_back(ui::actionBar(buildHeadTrail(tab))); + row.common.testId = "head"; + row.common.layout.width = Sizing::stretch(); + row.common.visible = Prop{[this, tab] { return leadHasContent(tab) || trailHasContent(tab); }}; + row.align = Align::Start; + row.justify = Justify::End; + row.wrap = true; + Column block{.children = {}, .gap = 1, .common = {}}; + block.children.push_back(ui::text(buildHeadEyebrow(tab))); + block.children.push_back(ui::row(std::move(row))); + block.common.testId = "head_block"; + block.common.layout.width = Sizing::stretch(); + block.common.visible = Prop{[this, tab] { return headHasContent(tab); }}; + return ui::column(std::move(block)); +} + +void Workspace::showTabs() { + if (_model == nullptr) { + return; + } + std::vector const order = _model->order(); + std::optional const shown = _model->active().peek(); + std::vector captions; + captions.reserve(order.size()); + for (std::size_t index = 0; index < order.size(); ++index) { + auto const found = _pages.find(order.at(index).value); + if (found == _pages.end()) { + continue; + } + Page& page = *found->second; + // A tab the model moved (a reuseEmpty replacement) moves its page in the bar too; `_shownOrder` is the + // bar's own order of the pages. + if (index >= _shownOrder.size() || _shownOrder.at(index) != order.at(index)) { + std::erase(_shownOrder, order.at(index)); + _shownOrder.insert(_shownOrder.begin() + static_cast(std::min(index, _shownOrder.size())), + order.at(index)); + _bar->moveChild(*page.slot, index); + } + page.slot->setVisible(shown == order.at(index)); + captions.push_back(captionOf(*_model->handleOf(order.at(index)))); + } + _bar->setTabs(captions); + _bar->setSelected(shown ? indexOf(*shown) : kNone); + // One tab needs no strip to choose it by; the chords still work with the strip hidden. + _bar->setBarShown(captions.size() > 1); + if (_onChanged) { + _onChanged(); + } +} +} // namespace morph::ui From 0c3d59fc6136f6d67ba5eb3479d027e6682b40f0 Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 01:31:01 +0100 Subject: [PATCH 12/38] Move the shell parts model's non-template code into src/ui/shell_parts_model.cpp ShellPartsModel's member bodies of two or more lines move to the compiled library, along with shellText and shellLabels, which shell_parts_binding.hpp calls and so keep documented declarations. builtinShellText has no other user and lives in the .cpp's unnamed namespace. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- CMakeLists.txt | 1 + include/morph/ui/shell_parts_model.hpp | 629 ++---------------------- src/ui/shell_parts_model.cpp | 655 +++++++++++++++++++++++++ 3 files changed, 692 insertions(+), 593 deletions(-) create mode 100644 src/ui/shell_parts_model.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 6a015baca..a978e628f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -419,6 +419,7 @@ add_library(morph STATIC src/ui/service.cpp src/ui/host.cpp src/ui/service_client.cpp + src/ui/shell_parts_model.cpp src/ui/workspace.cpp ) add_library(morph::morph ALIAS morph) diff --git a/include/morph/ui/shell_parts_model.hpp b/include/morph/ui/shell_parts_model.hpp index 784fc27f9..d5bfc9f0d 100644 --- a/include/morph/ui/shell_parts_model.hpp +++ b/include/morph/ui/shell_parts_model.hpp @@ -7,6 +7,7 @@ #include #include #include +#include #include #include #include @@ -27,90 +28,16 @@ namespace morph::ui { -/// @brief The texts the shell draws that no application declares, in English and German, by catalogue key. -/// @param key A `morph.shell.*` key. -/// @param locale The session's locale; only its language matters. -/// @return The text; the key when it names none. -[[nodiscard]] inline std::string builtinShellText(std::string_view key, std::string_view locale) { - struct Entry { - std::string_view key; - std::string_view en; - std::string_view de; - }; - static constexpr std::array kRows = {{ - {"morph.shell.context", "Scope", "Bereich"}, - {"morph.shell.search", "Search", "Suche"}, - {"morph.shell.searchResults", "Search results", "Suchergebnisse"}, - {"morph.shell.searchEmpty", "No results for", "Keine Ergebnisse für"}, - {"morph.shell.searchFailed", "could not be searched", "konnte nicht durchsucht werden"}, - {"morph.shell.searching", "Searching…", "Suche läuft…"}, - {"morph.shell.inbox", "waiting", "offen"}, - {"morph.shell.principal", "Signed in as", "Angemeldet als"}, - {"morph.shell.roles", "Your roles", "Ihre Rollen"}, - {"morph.shell.language", "Language", "Sprache"}, - {"morph.shell.formats", "Number and date format", "Zahlen- und Datumsformat"}, - {"morph.shell.countFailed", "count unavailable", "Anzahl nicht verfügbar"}, - {"morph.shell.close", "Close", "Schließen"}, - {"morph.shell.moduleClosed", "collapsed", "eingeklappt"}, - {"morph.shell.moduleOpen", "expanded", "ausgeklappt"}, - {"morph.shell.contextDirty", "Switching scope discards unsaved changes in {n} tabs", - "Der Wechsel des Bereichs verwirft ungespeicherte Änderungen in {n} Tabs"}, - {"morph.shell.contextDiscard", "Discard and switch", "Verwerfen und wechseln"}, - {"morph.shell.contextCancel", "Cancel", "Abbrechen"}, - {"morph.shell.locale.en", "English", "Englisch"}, - {"morph.shell.locale.de", "German", "Deutsch"}, - {"morph.shell.navigation", "Navigation", "Navigation"}, - {"morph.shell.signOut", "Sign out", "Abmelden"}, - {"morph.shell.help", "Help", "Hilfe"}, - {"morph.shell.loading", "Loading…", "Lädt…"}, - {"morph.shell.connected", "Connected", "Verbunden"}, - {"morph.shell.reconnecting", "Reconnecting…", "Verbindung wird wiederhergestellt…"}, - {"morph.shell.offline", "Offline", "Offline"}, - }}; - bool const german = locale.starts_with("de"); - auto const found = std::ranges::find_if(kRows, [key](Entry const& row) { return row.key == key; }); - if (found == kRows.end()) { - return std::string{key}; - } - return std::string{german ? found->de : found->en}; -} - /// @brief A `morph.shell.*` text: the bundle's catalogue wins, then the built-in English or German. /// @param key The key. /// @param format The session's formatting facts. /// @return The text. -[[nodiscard]] inline std::string shellText(std::string_view key, FormatContext const& format) { - if (format.translations) { - if (auto const pattern = format.translations(std::string{key}, format.locale)) { - return *pattern; - } - } - return builtinShellText(key, format.locale); -} +[[nodiscard]] MORPH_API std::string shellText(std::string_view key, FormatContext const& format); /// @brief The frame's texts in the session's locale. /// @param format The session's formatting facts. /// @return The labels. -[[nodiscard]] inline ShellLabels shellLabels(FormatContext const& format) { - return ShellLabels{.scope = shellText("morph.shell.context", format), - .search = shellText("morph.shell.search", format), - .searchResults = shellText("morph.shell.searchResults", format), - .searchEmpty = shellText("morph.shell.searchEmpty", format), - .searchFailed = shellText("morph.shell.searchFailed", format), - .searching = shellText("morph.shell.searching", format), - .waiting = shellText("morph.shell.inbox", format), - .signedInAs = shellText("morph.shell.principal", format), - .roles = shellText("morph.shell.roles", format), - .language = shellText("morph.shell.language", format), - .formats = shellText("morph.shell.formats", format), - .countFailed = shellText("morph.shell.countFailed", format), - .close = shellText("morph.shell.close", format), - .signOut = shellText("morph.shell.signOut", format), - .help = shellText("morph.shell.help", format), - .connected = shellText("morph.shell.connected", format), - .reconnecting = shellText("morph.shell.reconnecting", format), - .offline = shellText("morph.shell.offline", format)}; -} +[[nodiscard]] MORPH_API ShellLabels shellLabels(FormatContext const& format); /// @brief What the model asks of its client. struct ShellModelOptions { @@ -143,7 +70,7 @@ struct ShellModelOptions { /// /// Neither copyable nor movable; used on the owner thread of its session. It borrows the session, the app root and the /// parts, and must go before any of them. -class ShellPartsModel { +class MORPH_API ShellPartsModel { public: /// @brief The model; it installs the `setContext` handler and starts following the switcher. /// @param session The session. Borrowed. @@ -151,22 +78,7 @@ class ShellPartsModel { /// @param parts The parts. Borrowed. /// @param options What it asks of its client. ShellPartsModel(Session& session MORPH_LIFETIMEBOUND, AppRoot& root MORPH_LIFETIMEBOUND, - ShellParts const& parts MORPH_LIFETIMEBOUND, ShellModelOptions options) - : _session{&session}, - _root{&root}, - _parts{&parts}, - _options{std::move(options)}, - _chosen{session.runtime(), Value{}}, - _answered{session.runtime(), !parts.context.has_value()}, - _searchText{session.runtime(), std::string{}}, - _optionList{session.runtime(), std::vector()` emits it. /// @return The rows; none for a schema without properties. Or why the schema cannot be read. -[[nodiscard]] inline std::expected, std::string> actionFields(std::string_view schemaJson) { - auto model = forms::FormModel::fromSchema("", schemaJson); - if (!model) { - std::string const& where = model.error().path; - return std::unexpected(where.empty() ? model.error().message : where + ": " + model.error().message); - } - std::vector fields; - for (forms::FieldSpec const& spec : model->fields()) { - ActionField field{.name = spec.name, .type = detail::explorer::typeText(spec), .required = spec.required}; - if (auto const& minimum = spec.exactMinimum ? spec.exactMinimum : spec.minimum) { - field.rules.push_back("min " + *minimum); - } - if (auto const& maximum = spec.exactMaximum ? spec.exactMaximum : spec.maximum) { - field.rules.push_back("max " + *maximum); - } - if (spec.multipleOf) { - field.rules.push_back("multiple of " + *spec.multipleOf); - } - if (spec.readOnly) { - field.rules.emplace_back("read-only"); - } - if (spec.hidden) { - field.rules.emplace_back("hidden"); - } - for (forms::RuleExpr const& rule : model->rules()) { - if (rule.names(spec.name)) { - field.rules.emplace_back(rule.kindName()); - } - } - fields.push_back(std::move(field)); - } - return fields; -} +[[nodiscard]] MORPH_API std::expected, std::string> actionFields(std::string_view schemaJson); /// @brief Which widget "Try it" builds for an action. enum class TryItKind : std::uint8_t { @@ -303,31 +121,8 @@ enum class TryItKind : std::uint8_t { /// @param kind The node. /// @return The document's JSON text, with the id `tryItScreenId(actionId)`. // NOLINTNEXTLINE(bugprone-easily-swappable-parameters): an action id and a model type read alike, and neither reads. -[[nodiscard]] inline std::string tryItDocument(std::string_view actionId, std::string_view modelType, TryItKind kind) { - auto const quoted = [](std::string_view text) { return glz::write_json(std::string{text}).value_or("\"\""); }; - std::string const action = quoted(actionId); - std::string node; - if (kind == TryItKind::Form) { - node = R"({"kind":"form","testId":"tryit","model":"target","action":)" + action + - R"(,"submit":"explicit", - "onSuccess":[{"set":"reply","value":{"ref":"event"}},{"set":"failure","value":null}], - "onError":[{"set":"failure","value":{"ref":"event"}},{"set":"reply","value":null}]}, - {"kind":"text","testId":"tryit_result","role":"success","text":{"ref":"reply"}}, - {"kind":"text","testId":"tryit_error","role":"error","text":{"if":[ - {"fn":"engaged","args":[{"ref":"failure"}]}, - {"fn":"format","args":["Failed: {0}",{"ref":"failure"}]},""]}})"; - } else { - node = std::string{R"({"kind":")"} + (kind == TryItKind::Collection ? "collection" : "wizard") + - R"(","testId":"tryit","model":"target","action":)" + action + "}"; - } - return R"({"vocab":"ui/1","id":)" + quoted(tryItScreenId(actionId)) + R"(,"title":)" + - quoted("Try " + std::string{actionId}) + R"(, - "models":{"target":{"type":)" + - quoted(modelType) + R"(,"instance":"private"}}, - "state":{"reply":{"init":null},"failure":{"init":null}}, - "view":{"kind":"column","gap":3,"children":[)" + - node + "]}}"; -} +[[nodiscard]] MORPH_API std::string tryItDocument(std::string_view actionId, std::string_view modelType, + TryItKind kind); /// @brief A model's `schemas` document: `{actionType: schema}`, or why the server would not describe the model. using ModelSchemas = std::expected; @@ -338,22 +133,8 @@ using SchemasByModel = std::map>; /// @brief The actions a model's `schemas` document lists, with each one's schema. /// @param document The document's JSON text. /// @return The schemas by action id, or why the document cannot be read. -[[nodiscard]] inline std::expected>, std::string> schemasOf( - std::string_view document) { - auto parsed = parseJson(document); - if (!parsed) { - return std::unexpected(std::move(parsed.error())); - } - auto const* const actions = std::get_if(&parsed->data); - if (actions == nullptr) { - return std::unexpected(std::string{"the schemas document is not an object"}); - } - std::map> schemas; - for (auto const& [action, schema] : *actions) { - schemas.emplace(action, glz::write_json(schema).value_or(std::string{})); - } - return schemas; -} +[[nodiscard]] MORPH_API std::expected>, std::string> schemasOf( + std::string_view document); /// @brief The catalog a "Try it" document loads with: @p catalog, whose `action` lookup also answers an action /// only a @@ -363,48 +144,7 @@ using SchemasByModel = std::map>; /// @param catalog The client's catalog. /// @param schemas The models' `schemas` documents. /// @return The catalog. -[[nodiscard]] inline Catalog tryItCatalog(Catalog catalog, SchemasByModel const& schemas) { - auto const known = std::make_shared, std::less<>>>(); - for (auto const& [type, document] : schemas) { - if (!document) { - continue; - } - if (auto read = schemasOf(*document)) { - for (auto& [action, schema] : *read) { - known->emplace(action, std::pair{type, std::move(schema)}); - } - } - } - catalog.action = [inner = std::move(catalog.action), - known](std::string_view actionId) -> std::optional { - if (inner) { - if (std::optional info = inner(actionId)) { - return info; - } - } - auto const found = known->find(actionId); - if (found == known->end()) { - return std::nullopt; - } - ActionInfo info; - info.modelType = found->second.first; - return info; - }; - catalog.schema = [inner = std::move(catalog.schema), - known](std::string_view actionId) -> std::optional { - if (inner) { - if (std::optional schema = inner(actionId)) { - return schema; - } - } - auto const found = known->find(actionId); - if (found == known->end()) { - return std::nullopt; - } - return found->second.second; - }; - return catalog; -} +[[nodiscard]] MORPH_API Catalog tryItCatalog(Catalog catalog, SchemasByModel const& schemas); /// @brief What an `Explorer` shows, and what it reports. struct ExplorerOptions { @@ -438,7 +178,7 @@ struct ExplorerOptions { /// `explorer_action_`, `explorer_title`, `explorer_facts`, `explorer_fields`, `explorer_uses`, /// `explorer_open_`, `explorer_tryit`, `explorer_tryit_status`, `explorer_schema`, and inside "Try it" the /// generated document's own (`tryit`, …). -class Explorer final : public ScreenHandle { +class MORPH_API Explorer final : public ScreenHandle { public: /// @brief The explorer, appended to @p page. /// @param runtime The reactive runtime its title is computed in. Borrowed. @@ -446,41 +186,7 @@ class Explorer final : public ScreenHandle { /// @param page The container it is appended to; it outlives the explorer. /// @param options What it shows and reports. Explorer(reactive::Runtime& runtime MORPH_LIFETIMEBOUND, IViewBackend& backend MORPH_LIFETIMEBOUND, - ContainerWidget& page MORPH_LIFETIMEBOUND, ExplorerOptions options) - : _backend{&backend}, - _options{std::move(options)}, - _scope{runtime}, - _title{_scope.computed([] { return std::string{"Explorer"}; })}, - _dirty{_scope.computed([] { return false; })}, - _identity{_scope.computed([] { return Value{}; })}, - _root{backend.createSplitter(&page, Axis::Horizontal)}, - _listScroll{backend.createScroll(_root.get(), Axis::Vertical)}, - _list{backend.createStack(_listScroll.get(), Axis::Vertical)}, - _detailScroll{backend.createScroll(_root.get(), Axis::Vertical)}, - _detail{backend.createStack(_detailScroll.get(), Axis::Vertical)} { - if (!_options.facts.action && !_options.facts.model) { - _options.facts = _options.catalog.facts(); - } - _permitted.insert(_options.catalog.permitted.begin(), _options.catalog.permitted.end()); - for (auto const& [screenId, document] : _options.documents) { - for (ActionUse& use : actionUses(*document, _options.facts)) { - std::string action = use.actionId; - _uses[std::move(action)].emplace_back(screenId, std::move(use)); - } - } - _root->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); - _root->setTestId("explorer"); - _root->setSizes({kListWidth, kDetailWidth}); - _listScroll->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); - _detailScroll->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); - _list->setGap(2); - _list->setLayout({.width = Sizing::stretch(), .height = {}}); - _detail->setGap(4); - _detail->setLayout({.width = Sizing::stretch(), .height = {}}); - _detail->setTestId("explorer_detail"); - listAll(); - showNothingChosen(); - } + ContainerWidget& page MORPH_LIFETIMEBOUND, ExplorerOptions options); Explorer(Explorer const&) = delete; Explorer& operator=(Explorer const&) = delete; @@ -503,12 +209,7 @@ class Explorer final : public ScreenHandle { /// @brief Closes when asked. /// @param done Called with `true`. - void requestClose(std::function done) override { - clearDetail(); - if (done) { - done(true); - } - } + void requestClose(std::function done) override; /// @brief Closes the "Try it" screen. void forceClose() override { clearDetail(); } @@ -516,15 +217,7 @@ class Explorer final : public ScreenHandle { /// @brief Shows an action's sections, as choosing it in the list does. /// @param actionId The action id. /// @return Whether a listed model has the action. - bool select(std::string const& actionId) { - for (Model const& model : _models) { - if (std::ranges::contains(model.actions, actionId, &ActionEntry::id)) { - showAction(model, actionId); - return true; - } - } - return false; - } + bool select(std::string const& actionId); /// @brief The action shown. /// @return Its id; empty with none. @@ -557,152 +250,26 @@ class Explorer final : public ScreenHandle { std::unique_ptr button; }; - [[nodiscard]] static std::string lower(std::string_view text) { - std::string out{text}; - std::ranges::transform(out, out.begin(), [](char byte) { - return static_cast(std::tolower(static_cast(byte))); - }); - return out; - } + [[nodiscard]] static std::string lower(std::string_view text); - [[nodiscard]] static std::string titleOf(CatalogEntry const& entry) { - if (std::string const* const text = std::get_if(&entry.title.data)) { - return *text; - } - if (auto const* const object = std::get_if(&entry.title.data)) { - for (auto const& [key, value] : *object) { - std::string const* const text = std::get_if(&value.data); - if (key == "fallback" && text != nullptr) { - return *text; - } - } - } - return entry.id; - } + [[nodiscard]] static std::string titleOf(CatalogEntry const& entry); // The model types the catalog names: its models and every action's model, in name order. - [[nodiscard]] std::set> modelTypes() const { - std::set> types; - if (_options.catalog.models) { - for (auto const& [type, info] : *_options.catalog.models) { - static_cast(info); - types.insert(type); - } - } - if (_options.catalog.actions) { - for (auto const& [action, info] : *_options.catalog.actions) { - static_cast(action); - if (!info.modelType.empty()) { - types.insert(info.modelType); - } - } - } - for (auto const& [type, document] : _options.schemas) { - static_cast(document); - types.insert(type); - } - return types; - } + [[nodiscard]] std::set> modelTypes() const; [[nodiscard]] std::unique_ptr text(ContainerWidget& parent, std::string_view content, - TextRole role = TextRole::Normal) const { - auto made = _backend->createText(&parent); - made->setText(content); - made->setRole(role); - return made; - } + TextRole role = TextRole::Normal) const; - void listAll() { - _search = _backend->createTextInput(_list.get(), TextInputMode::SingleLine); - _search->setTestId("explorer_search"); - _search->setPlaceholder("Search"); - _search->setAccessibleName("Search screens and actions"); - _search->setOnChange([this](std::string const& wanted) { filter(wanted); }); - _screensHeading = text(*_list, {}, TextRole::Heading); - for (CatalogEntry const& entry : _options.catalog.entries) { - ScreenItem item{.title = titleOf(entry), .button = _backend->createButton(_list.get())}; - item.button->setLabel(item.title); - item.button->setTestId("explorer_screen_" + entry.id); - item.button->setEnabled(entry.available || entry.isPublic); - item.button->setOnClick([this, screenId = entry.id] { open(screenId); }); - _screens.push_back(std::move(item)); - } - _screensHeading->setText("Screens (" + std::to_string(_screens.size()) + ")"); - _modelsHeading = text(*_list, {}, TextRole::Heading); - for (std::string const& type : modelTypes()) { - Model model{.type = type, - .refusal = {}, - .box = _backend->createCollapsible(_list.get()), - .column = {}, - .note = {}, - .actions = {}}; - model.box->setTitle(type); - model.box->setTestId("explorer_model_" + type); - model.column = _backend->createStack(model.box.get(), Axis::Vertical); - model.column->setGap(1); - auto const found = _options.schemas.find(type); - if (found == _options.schemas.end()) { - model.refusal = "not described: the schemas did not arrive"; - } else if (!found->second) { - model.refusal = "not described: " + found->second.error(); - } else if (auto read = schemasOf(*found->second)) { - for (auto& [action, schema] : *read) { - ActionEntry entry{.id = action, .schema = std::move(schema), .button = {}}; - entry.button = _backend->createButton(model.column.get()); - entry.button->setLabel(action); - entry.button->setTestId("explorer_action_" + action); - entry.button->setOnClick([this, id = action] { select(id); }); - model.actions.push_back(std::move(entry)); - } - } else { - model.refusal = "not described: " + read.error(); - } - if (!model.refusal.empty()) { - model.note = text(*model.column, model.refusal, TextRole::Muted); - } - _models.push_back(std::move(model)); - } - _modelsHeading->setText("Models (" + std::to_string(_models.size()) + ")"); - } + void listAll(); // Shows what a search matches: a screen by its title, an action by its id, a model by its type or any of its // actions; a model with a matching action opens. - void filter(std::string const& wanted) { - std::string const needle = lower(wanted); - auto const matches = [&needle](std::string_view text) { - return needle.empty() || lower(text).contains(needle); - }; - for (ScreenItem& item : _screens) { - item.button->setVisible(matches(item.title)); - } - for (Model& model : _models) { - bool const typeMatches = matches(model.type); - bool any = false; - for (ActionEntry& action : model.actions) { - bool const shown = typeMatches || matches(action.id); - action.button->setVisible(shown); - any = any || shown; - } - model.box->setVisible(typeMatches || any); - if (!needle.empty() && any) { - model.box->setOpen(true); - } - } - } + void filter(std::string const& wanted); - void open(std::string const& screenId) const { - if (_options.onOpen) { - _options.onOpen(screenId); - } - } + void open(std::string const& screenId) const; // Takes the detail's widgets in reverse, so each child goes before its parent; the "Try it" screen goes first. - void clearDetail() { - _tryIt.reset(); - while (!_sections.empty()) { - _sections.pop_back(); - } - } + void clearDetail(); // Keeps a widget of the detail until the next choice. template @@ -712,254 +279,42 @@ class Explorer final : public ScreenHandle { return kept; } - void showNothingChosen() { - clearDetail(); - _selected.clear(); - keep(text(*_detail, "Choose an action to see its facts, its fields, where it is used, and to try it.", - TextRole::Muted)) - .setTestId("explorer_hint"); - } + void showNothingChosen(); // A card with a title, its content in a column the caller fills. - StackWidget& section(std::string_view title, std::string const& testId) { - PanelWidget& panel = keep(_backend->createPanel(_detail.get())); - panel.setTitle(title); - panel.setTestId(testId); - StackWidget& column = keep(_backend->createStack(&panel, Axis::Vertical)); - column.setGap(2); - return column; - } + StackWidget& section(std::string_view title, std::string const& testId); // A grid of texts, @p columns wide: the first row a heading when @p headed, else the first column labels. - void grid(StackWidget& parent, int columns, std::vector const& cells, bool headed) { - GridWidget& made = keep(_backend->createGrid(&parent)); - made.setColumns(columns); - made.setGap(2); - made.setLayout({.width = Sizing::stretch(), .height = {}}); - auto const width = static_cast(columns); - for (std::size_t index = 0; index < cells.size(); ++index) { - bool const muted = headed ? index < width : index % width == 0; - keep(text(made, cells.at(index), muted ? TextRole::Muted : TextRole::Normal)); - } - } + void grid(StackWidget& parent, int columns, std::vector const& cells, bool headed); - [[nodiscard]] std::string_view permission(std::string const& actionId) const { - if (_permitted.contains(actionId)) { - return "permitted"; - } - // The catalog's `permitted` covers only actions a served document names. - bool const named = _options.catalog.actions && _options.catalog.actions->contains(actionId); - return named ? "not permitted" : "decided when it runs"; - } + [[nodiscard]] std::string_view permission(std::string const& actionId) const; // The catalog's facts of an action, as label and value cells; none when the catalog has none for it. - [[nodiscard]] std::vector catalogFacts(std::string const& actionId) const { - if (!_options.catalog.actions || !_options.catalog.actions->contains(actionId)) { - return {}; - } - ActionInfo const& info = _options.catalog.actions->at(actionId); - auto const listed = [](std::vector const& names) { - return names.empty() ? std::string{"—"} : detail::explorer::joined(names, ", "); - }; - std::vector cells{"sends a credential", - info.credential ? "yes" : "no", - "server-calculated", - listed(info.calculatedFields), - "secret", - listed(info.secretFields)}; - if (info.listFields) { - cells.insert(cells.end(), {"list fields", listed(*info.listFields)}); - } - cells.insert(cells.end(), {"effects", effectsText(info)}); - if (!info.records.empty()) { - cells.insert(cells.end(), {"records", recordsText(info)}); - } - return cells; - } + [[nodiscard]] std::vector catalogFacts(std::string const& actionId) const; // What an action declares it changes (spec 8 §5): why a screen did or did not update after it ran. - [[nodiscard]] static std::string effectsText(ActionInfo const& info) { - if (!info.effects) { - return "reads"; - } - std::vector effects; - for (ActionEffect const& effect : *info.effects) { - if (effect.kind == "changesInstance") { - effects.emplace_back("changes its instance"); - } else if (effect.record) { - effects.push_back(effect.kind + " " + *effect.record); - } else { - effects.push_back(effect.kind); - } - } - return detail::explorer::joined(effects, ", "); - } + [[nodiscard]] static std::string effectsText(ActionInfo const& info); // The records an action's result holds, each with its key field and where the result holds it. - [[nodiscard]] static std::string recordsText(ActionInfo const& info) { - std::vector records; - for (ActionRecordInfo const& record : info.records) { - std::vector paths; - paths.reserve(record.paths.size()); - for (std::string const& path : record.paths) { - paths.push_back(path.empty() ? std::string{"the result"} : path); - } - std::string key{" keyless"}; - if (auto const& field = record.keyField) { - key = " by " + *field; - } - records.push_back(record.record + key + " at " + detail::explorer::joined(paths, ", ")); - } - return detail::explorer::joined(records, "; "); - } + [[nodiscard]] static std::string recordsText(ActionInfo const& info); // The payload fingerprint and shape a schema carries, as label and value cells. - [[nodiscard]] static std::vector payloadFacts(std::string const& schema) { - std::vector cells; - auto parsed = parseJson(schema); - auto const* const object = parsed ? std::get_if(&parsed->data) : nullptr; - if (object == nullptr) { - return cells; - } - for (auto const& [key, value] : *object) { - if (key != "x-payloadFingerprint" && key != "x-payloadShape") { - continue; - } - std::string const* const plain = std::get_if(&value.data); - cells.emplace_back(key == "x-payloadFingerprint" ? "payload fingerprint" : "payload shape"); - cells.push_back(plain != nullptr ? *plain : glz::write_json(value).value_or(std::string{})); - } - return cells; - } + [[nodiscard]] static std::vector payloadFacts(std::string const& schema); - void showFacts(Model const& model, ActionEntry const& action) { - std::vector cells{"model", model.type}; - std::ranges::move(catalogFacts(action.id), std::back_inserter(cells)); - std::ranges::move(payloadFacts(action.schema), std::back_inserter(cells)); - cells.insert(cells.end(), {"may run it", std::string{permission(action.id)}}); - grid(section("Facts", "explorer_facts"), 2, cells, false); - } + void showFacts(Model const& model, ActionEntry const& action); // Returns whether the schema reads. - bool showFields(ActionEntry const& action) { - StackWidget& content = section("Fields", "explorer_fields"); - auto const fields = actionFields(action.schema); - if (!fields) { - keep(text(content, "unreadable schema: " + fields.error(), TextRole::Error)); - keep(text(content, action.schema.substr(0, kShownBytes), TextRole::Muted)); - return false; - } - if (fields->empty()) { - keep(text(content, "No fields.", TextRole::Muted)); - return true; - } - std::vector cells{"name", "type", "required", "rules"}; - for (ActionField const& field : *fields) { - cells.insert(cells.end(), - {field.name, field.type, field.required ? "required" : "optional", - field.rules.empty() ? std::string{"—"} : detail::explorer::joined(field.rules, ", ")}); - } - grid(content, 4, cells, true); - return true; - } + bool showFields(ActionEntry const& action); - void showUses(std::string const& actionId) { - StackWidget& content = section("Used by", "explorer_uses"); - auto const found = _uses.find(actionId); - if (found == _uses.end()) { - keep(text(content, "No loaded document names it.", TextRole::Muted)); - return; - } - std::size_t index = 0; - for (auto const& [screenId, use] : found->second) { - StackWidget& row = keep(_backend->createStack(&content, Axis::Horizontal)); - row.setGap(3); - keep(text(row, screenId + " " + use.pointer + " (" + std::string{actionUseKindName(use.kind)} + ")")) - .setLayout({.width = Sizing::stretch(), .height = {}}); - // The app document is no screen to open. - if (screenId != "app") { - ButtonWidget& button = keep(_backend->createButton(&row)); - button.setLabel("Open"); - button.setTestId("explorer_open_" + std::to_string(index)); - button.setOnClick([this, target = screenId] { open(target); }); - } - ++index; - } - } + void showUses(std::string const& actionId); - [[nodiscard]] TryItKind tryItKind(std::string const& actionId) const { - if (_options.catalog.views && _options.catalog.views->contains(actionId)) { - return TryItKind::Collection; - } - if (_options.catalog.wizards && _options.catalog.wizards->contains(actionId)) { - return TryItKind::Wizard; - } - return TryItKind::Form; - } + [[nodiscard]] TryItKind tryItKind(std::string const& actionId) const; - void showTryIt(Model const& model, ActionEntry const& action, bool readable) { - StackWidget& content = section("Try it", "explorer_tryit"); - auto const status = [this, &content](std::string const& reason) { - keep(text(content, reason, TextRole::Muted)).setTestId("explorer_tryit_status"); - }; - if (_options.host == nullptr || !_options.provide) { - status("Not offered here."); - return; - } - if (!readable) { - status("Not offered: the schema cannot be read."); - return; - } - if (permission(action.id) == "not permitted") { - status("not permitted"); - return; - } - std::string const screenId = tryItScreenId(action.id); - auto loaded = loadDocumentText(tryItDocument(action.id, model.type, tryItKind(action.id)), - LoadOptions{.catalog = tryItCatalog(_options.facts, _options.schemas)}); - if (!loaded) { - status("Cannot build it: " + loaded.error().message()); - return; - } - _options.provide(screenId, std::make_shared(std::move(*loaded))); - SlotWidget& slot = keep(_backend->createSlot(&content)); - slot.setLayout({.width = Sizing::stretch(), .height = {}}); - auto mounted = _options.host->mountInto(screenId, {}, slot); - if (!mounted) { - status("Cannot mount it: " + mounted.error().reason); - return; - } - _tryIt = std::move(*mounted); - } + void showTryIt(Model const& model, ActionEntry const& action, bool readable); - void showSchema(std::string const& actionId, ActionEntry const& action) { - CollapsibleWidget& box = keep(_backend->createCollapsible(_detail.get())); - box.setTitle("Schema JSON"); - box.setTestId("explorer_schema"); - StackWidget& column = keep(_backend->createStack(&box, Axis::Vertical)); - column.setGap(2); - keep(text(column, action.schema, TextRole::Muted)); - for (auto const* const documents : {&_options.catalog.views, &_options.catalog.wizards}) { - if (!*documents) { - continue; - } - if (auto const found = (*documents)->find(actionId); found != (*documents)->end()) { - keep(text(column, found->second, TextRole::Muted)); - } - } - } + void showSchema(std::string const& actionId, ActionEntry const& action); - void showAction(Model const& model, std::string const& actionId) { - clearDetail(); - _selected = actionId; - auto const& action = *std::ranges::find(model.actions, actionId, &ActionEntry::id); - keep(text(*_detail, model.type + " / " + actionId, TextRole::Heading)).setTestId("explorer_title"); - showFacts(model, action); - bool const readable = showFields(action); - showUses(actionId); - showTryIt(model, action, readable); - showSchema(actionId, action); - } + void showAction(Model const& model, std::string const& actionId); IViewBackend* _backend; ExplorerOptions _options; diff --git a/src/ui/explorer.cpp b/src/ui/explorer.cpp new file mode 100644 index 000000000..2ec9672a4 --- /dev/null +++ b/src/ui/explorer.cpp @@ -0,0 +1,735 @@ +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace morph::ui::detail::explorer { +namespace { + +/// @brief The scopes around a node, innermost last: the aliases in its reach. +using ScopeChain = std::vector; + +/// @brief The model type an alias binds, from the innermost scope that declares it. +/// @param scopes The scopes around the use. +/// @param alias The alias. +/// @return The type; empty when no scope declares the alias. +std::string typeOf(ScopeChain const& scopes, std::string_view alias) { + for (ScopeDecl const* const scope : scopes | std::views::reverse) { + auto const found = std::ranges::find(scope->models, alias, &ModelDecl::name); + if (found != scope->models.end()) { + return found->type; + } + } + return {}; +} + +/// @brief Records one use, its model type the alias's, else the catalog's for the action. +/// @param uses Where it is recorded. +/// @param scopes The scopes around the use. +/// @param catalog The facts a borrowed alias's type is read from. +/// @param alias The alias the use goes through. +/// @param action The action id. +/// @param kind What names it. +/// @param pointer Its JSON Pointer. +void addUse(std::vector& uses, ScopeChain const& scopes, Catalog const& catalog, std::string_view alias, + std::string action, ActionUseKind kind, std::string pointer) { + std::string type = typeOf(scopes, alias); + // A borrowed alias has no type of its own in the document: the catalog says which model has the action. + if (type.empty() && catalog.action) { + if (std::optional const info = catalog.action(action)) { + type = info->modelType; + } + } + uses.push_back(ActionUse{ + .actionId = std::move(action), .modelType = std::move(type), .kind = kind, .pointer = std::move(pointer)}); +} + +/// @brief Records the queries and mutations of the innermost scope. +/// @param uses Where they are recorded. +/// @param scopes The scopes, the one read last. +/// @param catalog The facts a borrowed alias's type is read from. +void scopeUses(std::vector& uses, ScopeChain const& scopes, Catalog const& catalog) { + ScopeDecl const& scope = *scopes.back(); + for (QueryDecl const& query : scope.queries) { + addUse(uses, scopes, catalog, query.model, query.action, ActionUseKind::Query, query.path); + } + for (MutationDecl const& mutation : scope.mutations) { + addUse(uses, scopes, catalog, mutation.model, mutation.action, ActionUseKind::Mutation, mutation.path); + } +} + +/// @brief Records the uses of a node and everything under it, with the scope it creates. +/// @param uses Where they are recorded. +/// @param scopes The scopes around the node; restored on return. +/// @param catalog The facts a borrowed alias's type is read from. +/// @param node The node. +// NOLINTNEXTLINE(misc-no-recursion): a node's children are nodes. +void nodeUses(std::vector& uses, ScopeChain& scopes, Catalog const& catalog, DocNode const& node) { + if (node.scope) { + scopes.push_back(&*node.scope); + scopeUses(uses, scopes, catalog); + } + static constexpr std::array, 3> kNamed{ + {{"form", ActionUseKind::Form}, {"collection", ActionUseKind::Collection}, {"wizard", ActionUseKind::Wizard}}}; + for (auto const& [kind, use] : kNamed) { + if (node.kind == kind) { + addUse(uses, scopes, catalog, node.name("model"), std::string{node.name("action")}, use, node.path); + } + } + for (auto const& [key, nodes] : node.children) { + static_cast(key); + for (DocNodePtr const& child : nodes) { + nodeUses(uses, scopes, catalog, *child); + } + } + for (auto const& [key, parts] : node.parts) { + static_cast(key); + for (DocNodePtr const& part : parts) { + nodeUses(uses, scopes, catalog, *part); + } + } + if (node.scope) { + scopes.pop_back(); + } +} + +/// @brief Texts joined by a separator. +/// @param parts The texts. +/// @param separator What goes between two. +/// @return The joined text. +std::string joined(std::vector const& parts, std::string_view separator) { + std::string out; + for (std::string const& part : parts) { + out += out.empty() ? part : std::string{separator} + part; + } + return out; +} + +/// @brief A field's type as the explorer lists it. +/// @param field The field, as the forms engine reads it. +/// @return The type. +std::string typeText(forms::FieldSpec const& field) { + using forms::FieldKind; + if (field.kind == FieldKind::Enum) { + std::vector labels; + labels.reserve(field.enumOptions.size()); + for (forms::ChoiceOption const& option : field.enumOptions) { + labels.push_back(option.label); + } + return "one of: " + joined(labels, ", "); + } + if (field.kind == FieldKind::Quantity) { + std::string const text = "quantity in " + (field.unit.empty() ? field.unitAscii : field.unit); + std::vector others; + for (std::size_t index = 1; index < field.units.size(); ++index) { + others.push_back(field.units.at(index).display); + } + return others.empty() ? text : text + " (or " + joined(others, ", ") + ")"; + } + if (field.kind == FieldKind::Decimal && field.decimalPlaces) { + return "decimal, " + std::to_string(*field.decimalPlaces) + " places"; + } + if (field.kind == FieldKind::Choice && field.choice) { + return "choice from " + field.choice->optionsAction; + } + if (field.kind == FieldKind::Array) { + return "list of " + field.itemType; + } + if (field.kind == FieldKind::ObjectArray) { + return "list of objects"; + } + return std::string{forms::fieldKindName(field.kind)}; +} + +} // namespace +} // namespace morph::ui::detail::explorer + +namespace morph::ui { + +std::vector actionUses(Document const& document, Catalog const& catalog) { + std::vector uses; + detail::explorer::ScopeChain scopes{&document.scope}; + detail::explorer::scopeUses(uses, scopes, catalog); + if (document.view) { + detail::explorer::nodeUses(uses, scopes, catalog, *document.view); + } + return uses; +} + +std::expected, std::string> actionFields(std::string_view schemaJson) { + auto model = forms::FormModel::fromSchema("", schemaJson); + if (!model) { + std::string const& where = model.error().path; + return std::unexpected(where.empty() ? model.error().message : where + ": " + model.error().message); + } + std::vector fields; + for (forms::FieldSpec const& spec : model->fields()) { + ActionField field{.name = spec.name, .type = detail::explorer::typeText(spec), .required = spec.required}; + if (auto const& minimum = spec.exactMinimum ? spec.exactMinimum : spec.minimum) { + field.rules.push_back("min " + *minimum); + } + if (auto const& maximum = spec.exactMaximum ? spec.exactMaximum : spec.maximum) { + field.rules.push_back("max " + *maximum); + } + if (spec.multipleOf) { + field.rules.push_back("multiple of " + *spec.multipleOf); + } + if (spec.readOnly) { + field.rules.emplace_back("read-only"); + } + if (spec.hidden) { + field.rules.emplace_back("hidden"); + } + for (forms::RuleExpr const& rule : model->rules()) { + if (rule.names(spec.name)) { + field.rules.emplace_back(rule.kindName()); + } + } + fields.push_back(std::move(field)); + } + return fields; +} + +std::string tryItDocument(std::string_view actionId, std::string_view modelType, TryItKind kind) { + auto const quoted = [](std::string_view text) { return glz::write_json(std::string{text}).value_or("\"\""); }; + std::string const action = quoted(actionId); + std::string node; + if (kind == TryItKind::Form) { + node = R"({"kind":"form","testId":"tryit","model":"target","action":)" + action + + R"(,"submit":"explicit", + "onSuccess":[{"set":"reply","value":{"ref":"event"}},{"set":"failure","value":null}], + "onError":[{"set":"failure","value":{"ref":"event"}},{"set":"reply","value":null}]}, + {"kind":"text","testId":"tryit_result","role":"success","text":{"ref":"reply"}}, + {"kind":"text","testId":"tryit_error","role":"error","text":{"if":[ + {"fn":"engaged","args":[{"ref":"failure"}]}, + {"fn":"format","args":["Failed: {0}",{"ref":"failure"}]},""]}})"; + } else { + node = std::string{R"({"kind":")"} + (kind == TryItKind::Collection ? "collection" : "wizard") + + R"(","testId":"tryit","model":"target","action":)" + action + "}"; + } + return R"({"vocab":"ui/1","id":)" + quoted(tryItScreenId(actionId)) + R"(,"title":)" + + quoted("Try " + std::string{actionId}) + R"(, + "models":{"target":{"type":)" + + quoted(modelType) + R"(,"instance":"private"}}, + "state":{"reply":{"init":null},"failure":{"init":null}}, + "view":{"kind":"column","gap":3,"children":[)" + + node + "]}}"; +} + +std::expected>, std::string> schemasOf(std::string_view document) { + auto parsed = parseJson(document); + if (!parsed) { + return std::unexpected(std::move(parsed.error())); + } + auto const* const actions = std::get_if(&parsed->data); + if (actions == nullptr) { + return std::unexpected(std::string{"the schemas document is not an object"}); + } + std::map> schemas; + for (auto const& [action, schema] : *actions) { + schemas.emplace(action, glz::write_json(schema).value_or(std::string{})); + } + return schemas; +} + +Catalog tryItCatalog(Catalog catalog, SchemasByModel const& schemas) { + auto const known = std::make_shared, std::less<>>>(); + for (auto const& [type, document] : schemas) { + if (!document) { + continue; + } + if (auto read = schemasOf(*document)) { + for (auto& [action, schema] : *read) { + known->emplace(action, std::pair{type, std::move(schema)}); + } + } + } + catalog.action = [inner = std::move(catalog.action), + known](std::string_view actionId) -> std::optional { + if (inner) { + if (std::optional info = inner(actionId)) { + return info; + } + } + auto const found = known->find(actionId); + if (found == known->end()) { + return std::nullopt; + } + ActionInfo info; + info.modelType = found->second.first; + return info; + }; + catalog.schema = [inner = std::move(catalog.schema), + known](std::string_view actionId) -> std::optional { + if (inner) { + if (std::optional schema = inner(actionId)) { + return schema; + } + } + auto const found = known->find(actionId); + if (found == known->end()) { + return std::nullopt; + } + return found->second.second; + }; + return catalog; +} + +Explorer::Explorer(reactive::Runtime& runtime MORPH_LIFETIMEBOUND, IViewBackend& backend MORPH_LIFETIMEBOUND, + ContainerWidget& page MORPH_LIFETIMEBOUND, ExplorerOptions options) + : _backend{&backend}, + _options{std::move(options)}, + _scope{runtime}, + _title{_scope.computed([] { return std::string{"Explorer"}; })}, + _dirty{_scope.computed([] { return false; })}, + _identity{_scope.computed([] { return Value{}; })}, + _root{backend.createSplitter(&page, Axis::Horizontal)}, + _listScroll{backend.createScroll(_root.get(), Axis::Vertical)}, + _list{backend.createStack(_listScroll.get(), Axis::Vertical)}, + _detailScroll{backend.createScroll(_root.get(), Axis::Vertical)}, + _detail{backend.createStack(_detailScroll.get(), Axis::Vertical)} { + if (!_options.facts.action && !_options.facts.model) { + _options.facts = _options.catalog.facts(); + } + _permitted.insert(_options.catalog.permitted.begin(), _options.catalog.permitted.end()); + for (auto const& [screenId, document] : _options.documents) { + for (ActionUse& use : actionUses(*document, _options.facts)) { + std::string action = use.actionId; + _uses[std::move(action)].emplace_back(screenId, std::move(use)); + } + } + _root->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); + _root->setTestId("explorer"); + _root->setSizes({kListWidth, kDetailWidth}); + _listScroll->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); + _detailScroll->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); + _list->setGap(2); + _list->setLayout({.width = Sizing::stretch(), .height = {}}); + _detail->setGap(4); + _detail->setLayout({.width = Sizing::stretch(), .height = {}}); + _detail->setTestId("explorer_detail"); + listAll(); + showNothingChosen(); +} + +void Explorer::requestClose(std::function done) { + clearDetail(); + if (done) { + done(true); + } +} + +bool Explorer::select(std::string const& actionId) { + for (Model const& model : _models) { + if (std::ranges::contains(model.actions, actionId, &ActionEntry::id)) { + showAction(model, actionId); + return true; + } + } + return false; +} + +std::string Explorer::lower(std::string_view text) { + std::string out{text}; + std::ranges::transform( + out, out.begin(), [](char byte) { return static_cast(std::tolower(static_cast(byte))); }); + return out; +} + +std::string Explorer::titleOf(CatalogEntry const& entry) { + if (std::string const* const text = std::get_if(&entry.title.data)) { + return *text; + } + if (auto const* const object = std::get_if(&entry.title.data)) { + for (auto const& [key, value] : *object) { + std::string const* const text = std::get_if(&value.data); + if (key == "fallback" && text != nullptr) { + return *text; + } + } + } + return entry.id; +} + +std::set> Explorer::modelTypes() const { + std::set> types; + if (_options.catalog.models) { + for (auto const& [type, info] : *_options.catalog.models) { + static_cast(info); + types.insert(type); + } + } + if (_options.catalog.actions) { + for (auto const& [action, info] : *_options.catalog.actions) { + static_cast(action); + if (!info.modelType.empty()) { + types.insert(info.modelType); + } + } + } + for (auto const& [type, document] : _options.schemas) { + static_cast(document); + types.insert(type); + } + return types; +} + +std::unique_ptr Explorer::text(ContainerWidget& parent, std::string_view content, TextRole role) const { + auto made = _backend->createText(&parent); + made->setText(content); + made->setRole(role); + return made; +} + +void Explorer::listAll() { + _search = _backend->createTextInput(_list.get(), TextInputMode::SingleLine); + _search->setTestId("explorer_search"); + _search->setPlaceholder("Search"); + _search->setAccessibleName("Search screens and actions"); + _search->setOnChange([this](std::string const& wanted) { filter(wanted); }); + _screensHeading = text(*_list, {}, TextRole::Heading); + for (CatalogEntry const& entry : _options.catalog.entries) { + ScreenItem item{.title = titleOf(entry), .button = _backend->createButton(_list.get())}; + item.button->setLabel(item.title); + item.button->setTestId("explorer_screen_" + entry.id); + item.button->setEnabled(entry.available || entry.isPublic); + item.button->setOnClick([this, screenId = entry.id] { open(screenId); }); + _screens.push_back(std::move(item)); + } + _screensHeading->setText("Screens (" + std::to_string(_screens.size()) + ")"); + _modelsHeading = text(*_list, {}, TextRole::Heading); + for (std::string const& type : modelTypes()) { + Model model{.type = type, + .refusal = {}, + .box = _backend->createCollapsible(_list.get()), + .column = {}, + .note = {}, + .actions = {}}; + model.box->setTitle(type); + model.box->setTestId("explorer_model_" + type); + model.column = _backend->createStack(model.box.get(), Axis::Vertical); + model.column->setGap(1); + auto const found = _options.schemas.find(type); + if (found == _options.schemas.end()) { + model.refusal = "not described: the schemas did not arrive"; + } else if (!found->second) { + model.refusal = "not described: " + found->second.error(); + } else if (auto read = schemasOf(*found->second)) { + for (auto& [action, schema] : *read) { + ActionEntry entry{.id = action, .schema = std::move(schema), .button = {}}; + entry.button = _backend->createButton(model.column.get()); + entry.button->setLabel(action); + entry.button->setTestId("explorer_action_" + action); + entry.button->setOnClick([this, id = action] { select(id); }); + model.actions.push_back(std::move(entry)); + } + } else { + model.refusal = "not described: " + read.error(); + } + if (!model.refusal.empty()) { + model.note = text(*model.column, model.refusal, TextRole::Muted); + } + _models.push_back(std::move(model)); + } + _modelsHeading->setText("Models (" + std::to_string(_models.size()) + ")"); +} + +void Explorer::filter(std::string const& wanted) { + std::string const needle = lower(wanted); + auto const matches = [&needle](std::string_view text) { return needle.empty() || lower(text).contains(needle); }; + for (ScreenItem& item : _screens) { + item.button->setVisible(matches(item.title)); + } + for (Model& model : _models) { + bool const typeMatches = matches(model.type); + bool any = false; + for (ActionEntry& action : model.actions) { + bool const shown = typeMatches || matches(action.id); + action.button->setVisible(shown); + any = any || shown; + } + model.box->setVisible(typeMatches || any); + if (!needle.empty() && any) { + model.box->setOpen(true); + } + } +} + +void Explorer::open(std::string const& screenId) const { + if (_options.onOpen) { + _options.onOpen(screenId); + } +} + +void Explorer::clearDetail() { + _tryIt.reset(); + while (!_sections.empty()) { + _sections.pop_back(); + } +} + +void Explorer::showNothingChosen() { + clearDetail(); + _selected.clear(); + keep(text(*_detail, "Choose an action to see its facts, its fields, where it is used, and to try it.", + TextRole::Muted)) + .setTestId("explorer_hint"); +} + +StackWidget& Explorer::section(std::string_view title, std::string const& testId) { + PanelWidget& panel = keep(_backend->createPanel(_detail.get())); + panel.setTitle(title); + panel.setTestId(testId); + StackWidget& column = keep(_backend->createStack(&panel, Axis::Vertical)); + column.setGap(2); + return column; +} + +void Explorer::grid(StackWidget& parent, int columns, std::vector const& cells, bool headed) { + GridWidget& made = keep(_backend->createGrid(&parent)); + made.setColumns(columns); + made.setGap(2); + made.setLayout({.width = Sizing::stretch(), .height = {}}); + auto const width = static_cast(columns); + for (std::size_t index = 0; index < cells.size(); ++index) { + bool const muted = headed ? index < width : index % width == 0; + keep(text(made, cells.at(index), muted ? TextRole::Muted : TextRole::Normal)); + } +} + +std::string_view Explorer::permission(std::string const& actionId) const { + if (_permitted.contains(actionId)) { + return "permitted"; + } + // The catalog's `permitted` covers only actions a served document names. + bool const named = _options.catalog.actions && _options.catalog.actions->contains(actionId); + return named ? "not permitted" : "decided when it runs"; +} + +std::vector Explorer::catalogFacts(std::string const& actionId) const { + if (!_options.catalog.actions || !_options.catalog.actions->contains(actionId)) { + return {}; + } + ActionInfo const& info = _options.catalog.actions->at(actionId); + auto const listed = [](std::vector const& names) { + return names.empty() ? std::string{"—"} : detail::explorer::joined(names, ", "); + }; + std::vector cells{"sends a credential", + info.credential ? "yes" : "no", + "server-calculated", + listed(info.calculatedFields), + "secret", + listed(info.secretFields)}; + if (info.listFields) { + cells.insert(cells.end(), {"list fields", listed(*info.listFields)}); + } + cells.insert(cells.end(), {"effects", effectsText(info)}); + if (!info.records.empty()) { + cells.insert(cells.end(), {"records", recordsText(info)}); + } + return cells; +} + +std::string Explorer::effectsText(ActionInfo const& info) { + if (!info.effects) { + return "reads"; + } + std::vector effects; + for (ActionEffect const& effect : *info.effects) { + if (effect.kind == "changesInstance") { + effects.emplace_back("changes its instance"); + } else if (effect.record) { + effects.push_back(effect.kind + " " + *effect.record); + } else { + effects.push_back(effect.kind); + } + } + return detail::explorer::joined(effects, ", "); +} + +std::string Explorer::recordsText(ActionInfo const& info) { + std::vector records; + for (ActionRecordInfo const& record : info.records) { + std::vector paths; + paths.reserve(record.paths.size()); + for (std::string const& path : record.paths) { + paths.push_back(path.empty() ? std::string{"the result"} : path); + } + std::string key{" keyless"}; + if (auto const& field = record.keyField) { + key = " by " + *field; + } + records.push_back(record.record + key + " at " + detail::explorer::joined(paths, ", ")); + } + return detail::explorer::joined(records, "; "); +} + +std::vector Explorer::payloadFacts(std::string const& schema) { + std::vector cells; + auto parsed = parseJson(schema); + auto const* const object = parsed ? std::get_if(&parsed->data) : nullptr; + if (object == nullptr) { + return cells; + } + for (auto const& [key, value] : *object) { + if (key != "x-payloadFingerprint" && key != "x-payloadShape") { + continue; + } + std::string const* const plain = std::get_if(&value.data); + cells.emplace_back(key == "x-payloadFingerprint" ? "payload fingerprint" : "payload shape"); + cells.push_back(plain != nullptr ? *plain : glz::write_json(value).value_or(std::string{})); + } + return cells; +} + +void Explorer::showFacts(Model const& model, ActionEntry const& action) { + std::vector cells{"model", model.type}; + std::ranges::move(catalogFacts(action.id), std::back_inserter(cells)); + std::ranges::move(payloadFacts(action.schema), std::back_inserter(cells)); + cells.insert(cells.end(), {"may run it", std::string{permission(action.id)}}); + grid(section("Facts", "explorer_facts"), 2, cells, false); +} + +bool Explorer::showFields(ActionEntry const& action) { + StackWidget& content = section("Fields", "explorer_fields"); + auto const fields = actionFields(action.schema); + if (!fields) { + keep(text(content, "unreadable schema: " + fields.error(), TextRole::Error)); + keep(text(content, action.schema.substr(0, kShownBytes), TextRole::Muted)); + return false; + } + if (fields->empty()) { + keep(text(content, "No fields.", TextRole::Muted)); + return true; + } + std::vector cells{"name", "type", "required", "rules"}; + for (ActionField const& field : *fields) { + cells.insert(cells.end(), + {field.name, field.type, field.required ? "required" : "optional", + field.rules.empty() ? std::string{"—"} : detail::explorer::joined(field.rules, ", ")}); + } + grid(content, 4, cells, true); + return true; +} + +void Explorer::showUses(std::string const& actionId) { + StackWidget& content = section("Used by", "explorer_uses"); + auto const found = _uses.find(actionId); + if (found == _uses.end()) { + keep(text(content, "No loaded document names it.", TextRole::Muted)); + return; + } + std::size_t index = 0; + for (auto const& [screenId, use] : found->second) { + StackWidget& row = keep(_backend->createStack(&content, Axis::Horizontal)); + row.setGap(3); + keep(text(row, screenId + " " + use.pointer + " (" + std::string{actionUseKindName(use.kind)} + ")")) + .setLayout({.width = Sizing::stretch(), .height = {}}); + // The app document is no screen to open. + if (screenId != "app") { + ButtonWidget& button = keep(_backend->createButton(&row)); + button.setLabel("Open"); + button.setTestId("explorer_open_" + std::to_string(index)); + button.setOnClick([this, target = screenId] { open(target); }); + } + ++index; + } +} + +TryItKind Explorer::tryItKind(std::string const& actionId) const { + if (_options.catalog.views && _options.catalog.views->contains(actionId)) { + return TryItKind::Collection; + } + if (_options.catalog.wizards && _options.catalog.wizards->contains(actionId)) { + return TryItKind::Wizard; + } + return TryItKind::Form; +} + +void Explorer::showTryIt(Model const& model, ActionEntry const& action, bool readable) { + StackWidget& content = section("Try it", "explorer_tryit"); + auto const status = [this, &content](std::string const& reason) { + keep(text(content, reason, TextRole::Muted)).setTestId("explorer_tryit_status"); + }; + if (_options.host == nullptr || !_options.provide) { + status("Not offered here."); + return; + } + if (!readable) { + status("Not offered: the schema cannot be read."); + return; + } + if (permission(action.id) == "not permitted") { + status("not permitted"); + return; + } + std::string const screenId = tryItScreenId(action.id); + auto loaded = loadDocumentText(tryItDocument(action.id, model.type, tryItKind(action.id)), + LoadOptions{.catalog = tryItCatalog(_options.facts, _options.schemas)}); + if (!loaded) { + status("Cannot build it: " + loaded.error().message()); + return; + } + _options.provide(screenId, std::make_shared(std::move(*loaded))); + SlotWidget& slot = keep(_backend->createSlot(&content)); + slot.setLayout({.width = Sizing::stretch(), .height = {}}); + auto mounted = _options.host->mountInto(screenId, {}, slot); + if (!mounted) { + status("Cannot mount it: " + mounted.error().reason); + return; + } + _tryIt = std::move(*mounted); +} + +void Explorer::showSchema(std::string const& actionId, ActionEntry const& action) { + CollapsibleWidget& box = keep(_backend->createCollapsible(_detail.get())); + box.setTitle("Schema JSON"); + box.setTestId("explorer_schema"); + StackWidget& column = keep(_backend->createStack(&box, Axis::Vertical)); + column.setGap(2); + keep(text(column, action.schema, TextRole::Muted)); + for (auto const* const documents : {&_options.catalog.views, &_options.catalog.wizards}) { + if (!*documents) { + continue; + } + if (auto const found = (*documents)->find(actionId); found != (*documents)->end()) { + keep(text(column, found->second, TextRole::Muted)); + } + } +} + +void Explorer::showAction(Model const& model, std::string const& actionId) { + clearDetail(); + _selected = actionId; + auto const& action = *std::ranges::find(model.actions, actionId, &ActionEntry::id); + keep(text(*_detail, model.type + " / " + actionId, TextRole::Heading)).setTestId("explorer_title"); + showFacts(model, action); + bool const readable = showFields(action); + showUses(actionId); + showTryIt(model, action, readable); + showSchema(actionId, action); +} +} // namespace morph::ui From 66a0b19a770d245a7b210c4f222ffb366fa542c4 Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 01:40:43 +0100 Subject: [PATCH 17/38] Move the navigator's non-template code into src/ui/navigator.cpp Navigator's member bodies of two or more lines move to the compiled library, and the class carries MORPH_API. The one member template stays in the header. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- CMakeLists.txt | 1 + include/morph/ui/navigator.hpp | 600 ++------------------------------ src/ui/navigator.cpp | 613 +++++++++++++++++++++++++++++++++ 3 files changed, 652 insertions(+), 562 deletions(-) create mode 100644 src/ui/navigator.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index de8494b5c..b0f0f3725 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -420,6 +420,7 @@ add_library(morph STATIC src/ui/host.cpp src/ui/backend.cpp src/ui/explorer.cpp + src/ui/navigator.cpp src/ui/service_client.cpp src/ui/theme.cpp src/ui/shell_frame.cpp diff --git a/include/morph/ui/navigator.hpp b/include/morph/ui/navigator.hpp index b666af451..cd4c3df66 100644 --- a/include/morph/ui/navigator.hpp +++ b/include/morph/ui/navigator.hpp @@ -6,6 +6,7 @@ #include #include #include +#include #include #include #include @@ -74,35 +75,13 @@ struct NavigatorOptions { /// Test ids: `navigator`, `navigator_search`, `navigator_pins`, `nav_row_`, `nav_`, /// `nav_content_`, `nav_badge_`, `pin_`, `navigator_group_/` for a /// heading and `navigator_group_/_section` for its column. -class Navigator { +class MORPH_API Navigator { public: /// @brief The navigator, appended to @p parent. /// @param backend The backend its widgets are made with. Borrowed. /// @param parent The container it is appended to; null makes it a backend root. /// @param options The entries, the pins and the handlers. - Navigator(IViewBackend& backend MORPH_LIFETIMEBOUND, ContainerWidget* parent, NavigatorOptions options) - : _backend{&backend}, _options{std::move(options)}, _root{backend.createStack(parent, Axis::Vertical)} { - _root->setTestId("navigator"); - // The search, the pins and the groups stand a spacing step apart; a hidden pin row or group takes no gap. - _root->setGap(3); - _search = backend.createTextInput(_root.get(), TextInputMode::SingleLine); - _search->setTestId("navigator_search"); - _search->setPlaceholder("Search"); - _search->setAccessibleName("Search screens"); - _search->setOnChange([this](std::string const& text) { filter(text); }); - _pinRow = backend.createStack(_root.get(), Axis::Horizontal); - _pinRow->setTestId("navigator_pins"); - listEntries(); - arrange(); - std::vector stored = std::move(_options.pins); - _options.pins.clear(); - for (std::string& screenId : stored) { - if (_pins.size() < _options.maxPins && known(screenId) && !pinned(screenId)) { - _pins.push_back(std::move(screenId)); - } - } - showPins(); - } + Navigator(IViewBackend& backend MORPH_LIFETIMEBOUND, ContainerWidget* parent, NavigatorOptions options); Navigator(Navigator const&) = delete; Navigator& operator=(Navigator const&) = delete; @@ -120,25 +99,12 @@ class Navigator { /// @brief Pins a screen at the end of the pins. /// @param screenId The screen id. /// @return Whether it was pinned: `false` for an unknown or already pinned screen, or when the pins are full. - bool pin(std::string const& screenId) { - if (!known(screenId) || pinned(screenId) || _pins.size() >= _options.maxPins) { - return false; - } - _pins.push_back(screenId); - pinsChanged(); - return true; - } + bool pin(std::string const& screenId); /// @brief Removes a pin. /// @param screenId The screen id. /// @return Whether it was pinned. - bool unpin(std::string const& screenId) { - if (std::erase(_pins, screenId) == 0) { - return false; - } - pinsChanged(); - return true; - } + bool unpin(std::string const& screenId); /// @brief The pins, in order. /// @return Their screen ids. @@ -147,26 +113,7 @@ class Navigator { /// @brief Marks the entry of the screen that is open, and clears the mark of the one marked before. A pin is not /// marked. /// @param screenId The open screen's id; one the navigator does not list, or empty, leaves no entry marked. - void setCurrent(std::string_view screenId) { - if (screenId == _current) { - return; - } - if (Item const* const previous = itemOf(_current)) { - previous->button->setSelected(false); - } - _current = std::string{screenId}; - if (Item const* const next = itemOf(_current)) { - next->button->setSelected(true); - if (CatalogEntry const* const entry = entryOf(_current); - entry != nullptr && _openModule != entry->module) { - _openModule = entry->module; - refreshVisibility(); - } - } else { - _current.clear(); - } - changed(); - } + void setCurrent(std::string_view screenId); /// @brief The screen whose entry is marked. /// @return Its id; empty when none is. @@ -177,35 +124,12 @@ class Navigator { /// @param screenId The screen whose entry it goes on. /// @param badge The count, or `std::nullopt` to take it away. /// @return Whether the navigator lists the screen: `false`, changing nothing, for one it does not list. - bool setBadge(std::string_view screenId, std::optional const& badge) { - Item* const item = itemOf(screenId); - if (item == nullptr) { - return false; - } - if (item->shown == badge) { - return true; - } - item->shown = badge; - std::string const& title = item->titles.front(); - if (badge) { - item->badge->setText(badge->text); - item->badge->setTone(badge->tone); - item->button->setAccessibleName(title + ", " + badge->text); - } else { - item->button->setAccessibleName(title); - } - item->badge->setVisible(badge.has_value()); - changed(); - return true; - } + bool setBadge(std::string_view screenId, std::optional const& badge); /// @brief The count on a screen's entry. /// @param screenId The screen. /// @return It, or `std::nullopt` for an entry without one or a screen the navigator does not list. - [[nodiscard]] std::optional badgeOf(std::string_view screenId) const { - Item const* const item = itemOf(screenId); - return item == nullptr ? std::nullopt : item->shown; - } + [[nodiscard]] std::optional badgeOf(std::string_view screenId) const; /// @brief The navigator as the entries of a menu: the pins first, then a separator, then each group as a /// submenu labelled by its heading (the entries of a group with no heading at the top level instead). @@ -217,44 +141,14 @@ class Navigator { /// @brief Opens the entry at @p path of `menuEntries()`, as choosing it in the navigator does. /// @param path The entry's index at each level from the top, separators counted. /// @return Whether it named an available entry, which was opened. - bool choose(std::vector const& path) { - Menu const shown = menu(); - std::vector const* level = &shown.targets; - MenuSlot const* slot = nullptr; - for (std::size_t const index : path) { - if (index >= level->size()) { - return false; - } - slot = &level->at(index); - level = &slot->items; - } - if (slot == nullptr || slot->screenId.empty() || !slot->items.empty()) { - return false; - } - CatalogEntry const* const entry = entryOf(slot->screenId); - if (entry == nullptr || !entry->available) { - return false; - } - if (_options.onOpen) { - _options.onOpen(slot->screenId); - } - return true; - } + bool choose(std::vector const& path); /// @brief Collapses the navigator to one row per module: the row holds the module's label, a chevron and, while /// the module is closed, its count; only the open module lists its entries, under the headings of its /// later groups (the first group's heading is the module's label). A module with one entry is that /// entry's row. A search text shows the matching entries of every module and hides the module rows. /// @param grouped Whether to collapse. - void setModuleGroups(bool grouped) { - if (_moduleGroups == grouped) { - return; - } - _moduleGroups = grouped; - arrange(); - refreshVisibility(); - changed(); - } + void setModuleGroups(bool grouped); /// @brief Whether modules are collapsed. /// @return `true` after `setModuleGroups(true)`. @@ -263,17 +157,7 @@ class Navigator { /// @brief Opens a module's entries and closes the one open before. /// @param module The module. /// @return Whether the navigator lists the module. - bool setOpenModule(std::string_view module) { - if (!listsModule(module)) { - return false; - } - if (_openModule != module) { - _openModule = std::string{module}; - refreshVisibility(); - changed(); - } - return true; - } + bool setOpenModule(std::string_view module); /// @brief The module whose entries are listed. /// @return It; empty when none is open. @@ -283,82 +167,28 @@ class Navigator { /// @param closed Said of a closed module. /// @param open Said of the open module. /// @param countFailed Said when the count could not be read. - void setModuleTexts(std::string closed, std::string open, std::string countFailed) { - _closedWord = std::move(closed); - _openWord = std::move(open); - _failedWord = std::move(countFailed); - for (Module const& module : _modules) { - nameModule(module); - } - } + void setModuleTexts(std::string closed, std::string open, std::string countFailed); /// @brief Puts a count on a module's row while the module is closed, or takes it away. /// @param module The module. /// @param badge The count, or `std::nullopt` for none. /// @param failed Whether the count could not be read, which draws an error marker beside the label. /// @return Whether the navigator lists the module. - bool setModuleBadge(std::string_view module, std::optional const& badge, bool failed = false) { - Module* const found = moduleOf(module); - if (found == nullptr) { - return false; - } - if (found->shown == badge && found->failed == failed) { - return true; - } - found->shown = badge; - found->failed = failed; - if (badge) { - found->badge->setText(badge->text); - found->badge->setTone(badge->tone); - } - found->error->setVisible(failed); - nameModule(*found); - refreshVisibility(); - changed(); - return true; - } + bool setModuleBadge(std::string_view module, std::optional const& badge, bool failed = false); /// @brief The count on a module's row. /// @param module The module. /// @return It; empty for none or for a module the navigator does not list. - [[nodiscard]] std::optional moduleBadgeOf(std::string_view module) const { - Module const* const found = moduleOf(module); - return found == nullptr ? std::nullopt : found->shown; - } + [[nodiscard]] std::optional moduleBadgeOf(std::string_view module) const; /// @brief Shows or hides the navigator's own search field, which a shell with a global search replaces. /// @param shown Whether it shows; hiding it clears its text. - void setSearchShown(bool shown) { - if (!shown) { - _search->setText({}); - filter({}); - } - _search->setVisible(shown); - } + void setSearchShown(bool shown); /// @brief Reads every entry's titles and every heading again, as after a change of locale: the entry buttons, /// their accessible names, the pins, the headings and the search filter follow. The pins, the current /// entry, the badges and the search text stay. Calls the handler `setOnChanged` set. - void relabel() { - for (Group& group : _groups) { - group.heading->setText(headingOf(group)); - for (Item& item : group.items) { - item.titles = titlesOf(*item.entry); - item.button->setLabel(item.titles.front()); - item.label->setText(item.titles.front()); - if (item.shown) { - item.button->setAccessibleName(item.titles.front() + ", " + item.shown->text); - } - } - } - for (Module const& module : _modules) { - module.label->setText(moduleLabel(module)); - nameModule(module); - } - showPins(); - filter(_searchText); - changed(); - } + void relabel(); /// @brief Sets what is called after anything `menuEntries()` lists changed: a count, the current entry, a pin. /// @param onChanged The handler; empty calls nothing. @@ -413,133 +243,24 @@ class Navigator { }; // One entry of the menu: its title, then its count. - [[nodiscard]] MenuEntry menuEntry(CatalogEntry const& entry) const { - MenuEntry made; - made.label = titlesOf(entry).front(); - if (Item const* const item = itemOf(entry.id); item != nullptr && item->shown) { - made.label += " · " + item->shown->text; - } - if (entry.id == _current) { - made.checked = true; - } - made.enabled = entry.available; - return made; - } + [[nodiscard]] MenuEntry menuEntry(CatalogEntry const& entry) const; - [[nodiscard]] Menu menu() const { - Menu out; - for (std::string const& screenId : _pins) { - out.entries.push_back(menuEntry(*entryOf(screenId))); - out.targets.push_back(MenuSlot{.screenId = screenId, .items = {}}); - } - if (!_pins.empty() && !_groups.empty()) { - out.entries.push_back(MenuEntry{.label = {}, - .icon = {}, - .keys = {}, - .checked = std::nullopt, - .enabled = true, - .items = {}, - .separator = true, - .description = {}}); - out.targets.push_back(MenuSlot{}); - } - if (_moduleGroups) { - moduleMenu(out); - return out; - } - for (Group const* const listed : catalogOrder()) { - Group const& group = *listed; - std::string const heading = headingOf(group); - MenuEntry submenu; - MenuSlot slot; - for (Item const& item : group.items) { - (heading.empty() ? out.entries : submenu.items).push_back(menuEntry(*item.entry)); - (heading.empty() ? out.targets : slot.items) - .push_back(MenuSlot{.screenId = item.entry->id, .items = {}}); - } - if (!heading.empty()) { - submenu.label = heading; - out.entries.push_back(std::move(submenu)); - out.targets.push_back(std::move(slot)); - } - } - return out; - } + [[nodiscard]] Menu menu() const; // The collapsed form as a menu: one submenu per module, its count after the label, the module's later groups as // heading entries inside it; a module with one entry is that entry at the top level. - void moduleMenu(Menu& out) const { - for (Module const& module : _modules) { - MenuEntry submenu; - MenuSlot slot; - bool first = true; - for (Group const& group : _groups) { - if (group.module != module.module) { - continue; - } - bool const lone = module.entries <= 1; - if (!first && !lone && !headingOf(group).empty()) { - MenuEntry heading; - heading.label = headingOf(group); - heading.heading = true; - heading.enabled = false; - submenu.items.push_back(std::move(heading)); - slot.items.push_back(MenuSlot{}); - } - first = false; - for (Item const& item : group.items) { - (lone ? out.entries : submenu.items).push_back(menuEntry(*item.entry)); - (lone ? out.targets : slot.items).push_back(MenuSlot{.screenId = item.entry->id, .items = {}}); - } - } - if (module.entries > 1) { - submenu.label = moduleLabel(module); - if (module.shown) { - submenu.label += " · " + module.shown->text; - } - if (module.failed) { - submenu.label += " · !"; - } - out.entries.push_back(std::move(submenu)); - out.targets.push_back(std::move(slot)); - } - } - } + void moduleMenu(Menu& out) const; // The group, or the module when the entry has no group, through the label. - [[nodiscard]] std::string headingOf(Group const& group) const { - std::string const& text = group.group.empty() ? group.module : group.group; - return _options.label ? _options.label(text) : text; - } + [[nodiscard]] std::string headingOf(Group const& group) const; - void changed() const { - if (_onChanged) { - _onChanged(); - } - } + void changed() const; - [[nodiscard]] static std::string lower(std::string_view text) { - std::string out{text}; - std::ranges::transform(out, out.begin(), [](char byte) { - return static_cast(std::tolower(static_cast(byte))); - }); - return out; - } + [[nodiscard]] static std::string lower(std::string_view text); - [[nodiscard]] std::vector titlesOf(CatalogEntry const& entry) const { - if (_options.titles) { - std::vector titles = _options.titles(entry); - if (!titles.empty()) { - return titles; - } - } - return catalogTitles(entry, nullptr); - } + [[nodiscard]] std::vector titlesOf(CatalogEntry const& entry) const; - [[nodiscard]] CatalogEntry const* entryOf(std::string_view screenId) const { - auto const found = std::ranges::find(_options.entries, screenId, &CatalogEntry::id); - return found == _options.entries.end() ? nullptr : &*found; - } + [[nodiscard]] CatalogEntry const* entryOf(std::string_view screenId) const; [[nodiscard]] bool known(std::string_view screenId) const { return entryOf(screenId) != nullptr; } @@ -567,288 +288,43 @@ class Navigator { } // Wires a button to open, and prefetch on hover, an available entry. - void wire(ButtonWidget& button, CatalogEntry const& entry, std::string const& title) { - button.setLabel(title); - button.setEnabled(entry.available); - if (!entry.available) { - button.setTooltip(entry.reason.value_or(std::string{})); - return; - } - std::string const screenId = entry.id; - button.setOnClick([this, screenId] { - if (_options.onOpen) { - _options.onOpen(screenId); - } - }); - button.setOnHover([this, screenId] { - if (_options.onPrefetch) { - _options.onPrefetch(screenId); - } - }); - } + void wire(ButtonWidget& button, CatalogEntry const& entry, std::string const& title); - void listEntries() { - // Entries are listed module by module, a module's groups together, each in order of first appearance. - std::vector moduleOrder; - for (CatalogEntry const& entry : _options.entries) { - if (!std::ranges::contains(moduleOrder, entry.module)) { - moduleOrder.push_back(entry.module); - } - } - for (std::string const& moduleName : moduleOrder) { - makeModuleRow(moduleName); - std::vector groupOrder; - for (CatalogEntry const& entry : _options.entries) { - if (entry.module == moduleName && !std::ranges::contains(groupOrder, entry.group)) { - groupOrder.push_back(entry.group); - } - } - for (std::string const& groupName : groupOrder) { - _groups.push_back( - Group{.module = moduleName, .group = groupName, .section = {}, .heading = {}, .items = {}}); - makeGroup(_groups.back()); - } - } - refreshVisibility(); - } + void listEntries(); // The module's row of the collapsed form, hidden until module groups are on. - void makeModuleRow(std::string const& moduleName) { - Module made; - made.module = moduleName; - made.entries = - static_cast(std::ranges::count(_options.entries, moduleName, &CatalogEntry::module)); - made.row = _backend->createStack(_root.get(), Axis::Horizontal); - made.row->setTestId("nav_module_row_" + moduleName); - made.row->setLayout({.width = Sizing::stretch(), .height = {}}); - made.row->setAlign(Align::Center); - made.row->setVisible(false); - made.button = _backend->createButton(made.row.get()); - made.button->setTestId("nav_module_" + moduleName); - made.button->setStyle(ButtonStyle::Item); - made.button->setLayout({.width = Sizing::stretch(), .height = {}}); - made.button->setOnClick([this, moduleName] { - if (_openModule == moduleName) { - _openModule.clear(); - refreshVisibility(); - changed(); - } else { - setOpenModule(moduleName); - } - }); - ContainerWidget& content = made.button->content(); - made.content = _backend->createStack(&content, Axis::Horizontal); - made.content->setGap(1); - made.content->setAlign(Align::Center); - made.content->setLayout({.width = Sizing::stretch(), .height = {}}); - made.chevron = _backend->createText(made.content.get()); - made.chevron->setTestId("nav_module_chevron_" + moduleName); - made.label = _backend->createText(made.content.get()); - made.label->setTestId("nav_module_label_" + moduleName); - made.label->setLayout({.width = Sizing::stretch(), .height = {}}); - made.error = _backend->createText(made.content.get()); - made.error->setTestId("shell_count_error_" + moduleName); - made.error->setText("!"); - made.error->setVisible(false); - made.badge = _backend->createBadge(made.content.get()); - made.badge->setTestId("nav_module_badge_" + moduleName); - made.badge->setVisible(false); - _modules.push_back(std::move(made)); - Module& stored = _modules.back(); - stored.label->setText(moduleLabel(stored)); - nameModule(stored); - } + void makeModuleRow(std::string const& moduleName); - void makeGroup(Group& group) { - // The heading and its entries are a column of their own, a step apart from the next group's; the heading - // sits a step under whatever precedes it, and the entries' own heights keep them apart. - group.section = _backend->createStack(_root.get(), Axis::Vertical); - group.section->setGap(1); - group.section->setTestId("navigator_group_" + group.module + "/" + group.group + "_section"); - group.heading = _backend->createText(group.section.get()); - // An overline, which a theme may draw as small capitals; by default it looks as a section does. - group.heading->setRole(TextRole::Overline); - group.heading->setTestId("navigator_group_" + group.module + "/" + group.group); - group.heading->setText(headingOf(group)); - for (CatalogEntry const& entry : _options.entries) { - if (entry.module != group.module || entry.group != group.group) { - continue; - } - Item item{.entry = &entry, - .titles = titlesOf(entry), - .row = _backend->createStack(group.section.get(), Axis::Horizontal), - .button = {}, - .content = {}, - .label = {}, - .badge = {}, - .shown = std::nullopt}; - item.row->setTestId("nav_row_" + entry.id); - item.row->setLayout({.width = Sizing::stretch(), .height = {}}); - item.row->setAlign(Align::Center); - item.button = _backend->createButton(item.row.get()); - item.button->setTestId("nav_" + entry.id); - item.button->setStyle(ButtonStyle::Item); - item.button->setLayout({.width = Sizing::stretch(), .height = {}}); - wire(*item.button, entry, item.titles.front()); - // The title and the badge are the button's content, so its selection spans both. The badge is hidden - // until a count is set; the button's accessible name carries the count, so the entry stays one - // control to assistive technology. - ContainerWidget& content = item.button->content(); - item.content = _backend->createStack(&content, Axis::Horizontal); - item.content->setTestId("nav_content_" + entry.id); - item.content->setGap(1); - item.content->setAlign(Align::Center); - item.content->setLayout({.width = Sizing::stretch(), .height = {}}); - item.label = _backend->createText(item.content.get()); - item.label->setText(item.titles.front()); - item.label->setTestId("nav_title_" + entry.id); - item.label->setLayout({.width = Sizing::stretch(), .height = {}}); - item.badge = _backend->createBadge(item.content.get()); - item.badge->setTestId("nav_badge_" + entry.id); - item.badge->setVisible(false); - group.items.push_back(std::move(item)); - } - } + void makeGroup(Group& group); // The groups in the order the catalog first names each (module, group) pair: the order of the sidebar and the menu // while modules are not grouped. - [[nodiscard]] std::vector catalogOrder() const { - std::vector out; - for (CatalogEntry const& entry : _options.entries) { - auto const found = std::ranges::find_if(_groups, [&entry](Group const& candidate) { - return candidate.module == entry.module && candidate.group == entry.group; - }); - if (found != _groups.end() && !std::ranges::contains(out, &*found)) { - out.push_back(&*found); - } - } - return out; - } + [[nodiscard]] std::vector catalogOrder() const; // Places the groups' sections: module by module, each under its module's row, while modules are grouped; in // catalog order otherwise. A catalog that never interleaves its modules has one order, and nothing moves. - void arrange() { - std::vector const listed = catalogOrder(); - bool interleaved = false; - for (std::size_t index = 0; index < listed.size(); ++index) { - interleaved = interleaved || listed.at(index) != &_groups.at(index); - } - bool const moduleMajor = _moduleGroups || !interleaved; - if (moduleMajor == _moduleMajor) { - return; - } - _moduleMajor = moduleMajor; - // After the search field and the pins. - std::size_t at = 2; - if (moduleMajor) { - for (Module& module : _modules) { - _root->moveChild(*module.row, at++); - for (Group& group : _groups) { - if (group.module == module.module) { - _root->moveChild(*group.section, at++); - } - } - } - return; - } - for (Module& module : _modules) { - _root->moveChild(*module.row, at++); - } - for (Group const* const group : listed) { - _root->moveChild(*group->section, at++); - } - } + void arrange(); - void filter(std::string const& text) { - _searchText = text; - refreshVisibility(); - } + void filter(std::string const& text); - [[nodiscard]] Module const* moduleOf(std::string_view module) const { - auto const found = std::ranges::find(_modules, module, &Module::module); - return found == _modules.end() ? nullptr : &*found; - } + [[nodiscard]] Module const* moduleOf(std::string_view module) const; - [[nodiscard]] Module* moduleOf(std::string_view module) { - auto const found = std::ranges::find(_modules, module, &Module::module); - return found == _modules.end() ? nullptr : &*found; - } + [[nodiscard]] Module* moduleOf(std::string_view module); [[nodiscard]] bool listsModule(std::string_view module) const { return moduleOf(module) != nullptr; } // The heading of the module's first group, through the label: what its row says. - [[nodiscard]] std::string moduleLabel(Module const& module) const { - auto const first = std::ranges::find(_groups, module.module, &Group::module); - if (first != _groups.end()) { - return headingOf(*first); - } - return _options.label ? _options.label(module.module) : module.module; - } + [[nodiscard]] std::string moduleLabel(Module const& module) const; // The row's accessible name: the label, the count and whether the module is open. - void nameModule(Module const& module) const { - std::string name = moduleLabel(module); - if (module.shown && module.module != _openModule) { - name += ", " + module.shown->text; - } - if (module.failed) { - name += ", " + _failedWord; - } - name += ", " + (module.module == _openModule ? _openWord : _closedWord); - module.button->setAccessibleName(name); - } + void nameModule(Module const& module) const; // Shows what the search text, the module form and the open module leave: see `setModuleGroups`. - void refreshVisibility() { - std::string const wanted = lower(_searchText); - bool const collapsed = _moduleGroups && wanted.empty(); - for (Module const& module : _modules) { - bool const single = module.entries <= 1; - bool const open = module.module == _openModule; - module.row->setVisible(collapsed && !single); - module.chevron->setText(open ? "▾" : "▸"); - module.badge->setVisible(module.shown.has_value() && !open); - nameModule(module); - } - for (Group& group : _groups) { - Module const* const module = moduleOf(group.module); - bool const single = module != nullptr && module->entries <= 1; - bool const open = group.module == _openModule; - bool any = false; - for (Item& item : group.items) { - bool const matches = - wanted.empty() || std::ranges::any_of(item.titles, [&wanted](std::string const& title) { - return lower(title).contains(wanted); - }); - item.row->setVisible(matches); - any = any || matches; - } - bool const firstOfModule = &group == &*std::ranges::find(_groups, group.module, &Group::module); - group.section->setVisible(any && (!collapsed || single || open)); - // In the collapsed form the first group's heading is the module's row, and a single-entry module is - // its entry's row alone. - group.heading->setVisible(!_moduleGroups || !wanted.empty() ? true : !(firstOfModule || single)); - } - } + void refreshVisibility(); - void showPins() { - _pinButtons.clear(); - for (std::string const& screenId : _pins) { - CatalogEntry const* const entry = entryOf(screenId); - auto button = _backend->createButton(_pinRow.get()); - button->setTestId("pin_" + screenId); - wire(*button, *entry, titlesOf(*entry).front()); - _pinButtons.push_back(std::move(button)); - } - } + void showPins(); - void pinsChanged() { - showPins(); - if (_options.onPins) { - _options.onPins(_pins); - } - changed(); - } + void pinsChanged(); IViewBackend* _backend; NavigatorOptions _options; diff --git a/src/ui/navigator.cpp b/src/ui/navigator.cpp new file mode 100644 index 000000000..788a548f5 --- /dev/null +++ b/src/ui/navigator.cpp @@ -0,0 +1,613 @@ +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace morph::ui { + +Navigator::Navigator(IViewBackend& backend MORPH_LIFETIMEBOUND, ContainerWidget* parent, NavigatorOptions options) + : _backend{&backend}, _options{std::move(options)}, _root{backend.createStack(parent, Axis::Vertical)} { + _root->setTestId("navigator"); + // The search, the pins and the groups stand a spacing step apart; a hidden pin row or group takes no gap. + _root->setGap(3); + _search = backend.createTextInput(_root.get(), TextInputMode::SingleLine); + _search->setTestId("navigator_search"); + _search->setPlaceholder("Search"); + _search->setAccessibleName("Search screens"); + _search->setOnChange([this](std::string const& text) { filter(text); }); + _pinRow = backend.createStack(_root.get(), Axis::Horizontal); + _pinRow->setTestId("navigator_pins"); + listEntries(); + arrange(); + std::vector stored = std::move(_options.pins); + _options.pins.clear(); + for (std::string& screenId : stored) { + if (_pins.size() < _options.maxPins && known(screenId) && !pinned(screenId)) { + _pins.push_back(std::move(screenId)); + } + } + showPins(); +} + +bool Navigator::pin(std::string const& screenId) { + if (!known(screenId) || pinned(screenId) || _pins.size() >= _options.maxPins) { + return false; + } + _pins.push_back(screenId); + pinsChanged(); + return true; +} + +bool Navigator::unpin(std::string const& screenId) { + if (std::erase(_pins, screenId) == 0) { + return false; + } + pinsChanged(); + return true; +} + +void Navigator::setCurrent(std::string_view screenId) { + if (screenId == _current) { + return; + } + if (Item const* const previous = itemOf(_current)) { + previous->button->setSelected(false); + } + _current = std::string{screenId}; + if (Item const* const next = itemOf(_current)) { + next->button->setSelected(true); + if (CatalogEntry const* const entry = entryOf(_current); entry != nullptr && _openModule != entry->module) { + _openModule = entry->module; + refreshVisibility(); + } + } else { + _current.clear(); + } + changed(); +} + +bool Navigator::setBadge(std::string_view screenId, std::optional const& badge) { + Item* const item = itemOf(screenId); + if (item == nullptr) { + return false; + } + if (item->shown == badge) { + return true; + } + item->shown = badge; + std::string const& title = item->titles.front(); + if (badge) { + item->badge->setText(badge->text); + item->badge->setTone(badge->tone); + item->button->setAccessibleName(title + ", " + badge->text); + } else { + item->button->setAccessibleName(title); + } + item->badge->setVisible(badge.has_value()); + changed(); + return true; +} + +std::optional Navigator::badgeOf(std::string_view screenId) const { + Item const* const item = itemOf(screenId); + return item == nullptr ? std::nullopt : item->shown; +} + +bool Navigator::choose(std::vector const& path) { + Menu const shown = menu(); + std::vector const* level = &shown.targets; + MenuSlot const* slot = nullptr; + for (std::size_t const index : path) { + if (index >= level->size()) { + return false; + } + slot = &level->at(index); + level = &slot->items; + } + if (slot == nullptr || slot->screenId.empty() || !slot->items.empty()) { + return false; + } + CatalogEntry const* const entry = entryOf(slot->screenId); + if (entry == nullptr || !entry->available) { + return false; + } + if (_options.onOpen) { + _options.onOpen(slot->screenId); + } + return true; +} + +void Navigator::setModuleGroups(bool grouped) { + if (_moduleGroups == grouped) { + return; + } + _moduleGroups = grouped; + arrange(); + refreshVisibility(); + changed(); +} + +bool Navigator::setOpenModule(std::string_view module) { + if (!listsModule(module)) { + return false; + } + if (_openModule != module) { + _openModule = std::string{module}; + refreshVisibility(); + changed(); + } + return true; +} + +void Navigator::setModuleTexts(std::string closed, std::string open, std::string countFailed) { + _closedWord = std::move(closed); + _openWord = std::move(open); + _failedWord = std::move(countFailed); + for (Module const& module : _modules) { + nameModule(module); + } +} + +bool Navigator::setModuleBadge(std::string_view module, std::optional const& badge, bool failed) { + Module* const found = moduleOf(module); + if (found == nullptr) { + return false; + } + if (found->shown == badge && found->failed == failed) { + return true; + } + found->shown = badge; + found->failed = failed; + if (badge) { + found->badge->setText(badge->text); + found->badge->setTone(badge->tone); + } + found->error->setVisible(failed); + nameModule(*found); + refreshVisibility(); + changed(); + return true; +} + +std::optional Navigator::moduleBadgeOf(std::string_view module) const { + Module const* const found = moduleOf(module); + return found == nullptr ? std::nullopt : found->shown; +} + +void Navigator::setSearchShown(bool shown) { + if (!shown) { + _search->setText({}); + filter({}); + } + _search->setVisible(shown); +} + +void Navigator::relabel() { + for (Group& group : _groups) { + group.heading->setText(headingOf(group)); + for (Item& item : group.items) { + item.titles = titlesOf(*item.entry); + item.button->setLabel(item.titles.front()); + item.label->setText(item.titles.front()); + if (item.shown) { + item.button->setAccessibleName(item.titles.front() + ", " + item.shown->text); + } + } + } + for (Module const& module : _modules) { + module.label->setText(moduleLabel(module)); + nameModule(module); + } + showPins(); + filter(_searchText); + changed(); +} + +MenuEntry Navigator::menuEntry(CatalogEntry const& entry) const { + MenuEntry made; + made.label = titlesOf(entry).front(); + if (Item const* const item = itemOf(entry.id); item != nullptr && item->shown) { + made.label += " · " + item->shown->text; + } + if (entry.id == _current) { + made.checked = true; + } + made.enabled = entry.available; + return made; +} + +Navigator::Menu Navigator::menu() const { + Menu out; + for (std::string const& screenId : _pins) { + out.entries.push_back(menuEntry(*entryOf(screenId))); + out.targets.push_back(MenuSlot{.screenId = screenId, .items = {}}); + } + if (!_pins.empty() && !_groups.empty()) { + out.entries.push_back(MenuEntry{.label = {}, + .icon = {}, + .keys = {}, + .checked = std::nullopt, + .enabled = true, + .items = {}, + .separator = true, + .description = {}}); + out.targets.push_back(MenuSlot{}); + } + if (_moduleGroups) { + moduleMenu(out); + return out; + } + for (Group const* const listed : catalogOrder()) { + Group const& group = *listed; + std::string const heading = headingOf(group); + MenuEntry submenu; + MenuSlot slot; + for (Item const& item : group.items) { + (heading.empty() ? out.entries : submenu.items).push_back(menuEntry(*item.entry)); + (heading.empty() ? out.targets : slot.items).push_back(MenuSlot{.screenId = item.entry->id, .items = {}}); + } + if (!heading.empty()) { + submenu.label = heading; + out.entries.push_back(std::move(submenu)); + out.targets.push_back(std::move(slot)); + } + } + return out; +} + +void Navigator::moduleMenu(Menu& out) const { + for (Module const& module : _modules) { + MenuEntry submenu; + MenuSlot slot; + bool first = true; + for (Group const& group : _groups) { + if (group.module != module.module) { + continue; + } + bool const lone = module.entries <= 1; + if (!first && !lone && !headingOf(group).empty()) { + MenuEntry heading; + heading.label = headingOf(group); + heading.heading = true; + heading.enabled = false; + submenu.items.push_back(std::move(heading)); + slot.items.push_back(MenuSlot{}); + } + first = false; + for (Item const& item : group.items) { + (lone ? out.entries : submenu.items).push_back(menuEntry(*item.entry)); + (lone ? out.targets : slot.items).push_back(MenuSlot{.screenId = item.entry->id, .items = {}}); + } + } + if (module.entries > 1) { + submenu.label = moduleLabel(module); + if (module.shown) { + submenu.label += " · " + module.shown->text; + } + if (module.failed) { + submenu.label += " · !"; + } + out.entries.push_back(std::move(submenu)); + out.targets.push_back(std::move(slot)); + } + } +} + +std::string Navigator::headingOf(Group const& group) const { + std::string const& text = group.group.empty() ? group.module : group.group; + return _options.label ? _options.label(text) : text; +} + +void Navigator::changed() const { + if (_onChanged) { + _onChanged(); + } +} + +std::string Navigator::lower(std::string_view text) { + std::string out{text}; + std::ranges::transform( + out, out.begin(), [](char byte) { return static_cast(std::tolower(static_cast(byte))); }); + return out; +} + +std::vector Navigator::titlesOf(CatalogEntry const& entry) const { + if (_options.titles) { + std::vector titles = _options.titles(entry); + if (!titles.empty()) { + return titles; + } + } + return catalogTitles(entry, nullptr); +} + +CatalogEntry const* Navigator::entryOf(std::string_view screenId) const { + auto const found = std::ranges::find(_options.entries, screenId, &CatalogEntry::id); + return found == _options.entries.end() ? nullptr : &*found; +} + +void Navigator::wire(ButtonWidget& button, CatalogEntry const& entry, std::string const& title) { + button.setLabel(title); + button.setEnabled(entry.available); + if (!entry.available) { + button.setTooltip(entry.reason.value_or(std::string{})); + return; + } + std::string const screenId = entry.id; + button.setOnClick([this, screenId] { + if (_options.onOpen) { + _options.onOpen(screenId); + } + }); + button.setOnHover([this, screenId] { + if (_options.onPrefetch) { + _options.onPrefetch(screenId); + } + }); +} + +void Navigator::listEntries() { + // Entries are listed module by module, a module's groups together, each in order of first appearance. + std::vector moduleOrder; + for (CatalogEntry const& entry : _options.entries) { + if (!std::ranges::contains(moduleOrder, entry.module)) { + moduleOrder.push_back(entry.module); + } + } + for (std::string const& moduleName : moduleOrder) { + makeModuleRow(moduleName); + std::vector groupOrder; + for (CatalogEntry const& entry : _options.entries) { + if (entry.module == moduleName && !std::ranges::contains(groupOrder, entry.group)) { + groupOrder.push_back(entry.group); + } + } + for (std::string const& groupName : groupOrder) { + _groups.push_back( + Group{.module = moduleName, .group = groupName, .section = {}, .heading = {}, .items = {}}); + makeGroup(_groups.back()); + } + } + refreshVisibility(); +} + +void Navigator::makeModuleRow(std::string const& moduleName) { + Module made; + made.module = moduleName; + made.entries = static_cast(std::ranges::count(_options.entries, moduleName, &CatalogEntry::module)); + made.row = _backend->createStack(_root.get(), Axis::Horizontal); + made.row->setTestId("nav_module_row_" + moduleName); + made.row->setLayout({.width = Sizing::stretch(), .height = {}}); + made.row->setAlign(Align::Center); + made.row->setVisible(false); + made.button = _backend->createButton(made.row.get()); + made.button->setTestId("nav_module_" + moduleName); + made.button->setStyle(ButtonStyle::Item); + made.button->setLayout({.width = Sizing::stretch(), .height = {}}); + made.button->setOnClick([this, moduleName] { + if (_openModule == moduleName) { + _openModule.clear(); + refreshVisibility(); + changed(); + } else { + setOpenModule(moduleName); + } + }); + ContainerWidget& content = made.button->content(); + made.content = _backend->createStack(&content, Axis::Horizontal); + made.content->setGap(1); + made.content->setAlign(Align::Center); + made.content->setLayout({.width = Sizing::stretch(), .height = {}}); + made.chevron = _backend->createText(made.content.get()); + made.chevron->setTestId("nav_module_chevron_" + moduleName); + made.label = _backend->createText(made.content.get()); + made.label->setTestId("nav_module_label_" + moduleName); + made.label->setLayout({.width = Sizing::stretch(), .height = {}}); + made.error = _backend->createText(made.content.get()); + made.error->setTestId("shell_count_error_" + moduleName); + made.error->setText("!"); + made.error->setVisible(false); + made.badge = _backend->createBadge(made.content.get()); + made.badge->setTestId("nav_module_badge_" + moduleName); + made.badge->setVisible(false); + _modules.push_back(std::move(made)); + Module& stored = _modules.back(); + stored.label->setText(moduleLabel(stored)); + nameModule(stored); +} + +void Navigator::makeGroup(Group& group) { + // The heading and its entries are a column of their own, a step apart from the next group's; the heading + // sits a step under whatever precedes it, and the entries' own heights keep them apart. + group.section = _backend->createStack(_root.get(), Axis::Vertical); + group.section->setGap(1); + group.section->setTestId("navigator_group_" + group.module + "/" + group.group + "_section"); + group.heading = _backend->createText(group.section.get()); + // An overline, which a theme may draw as small capitals; by default it looks as a section does. + group.heading->setRole(TextRole::Overline); + group.heading->setTestId("navigator_group_" + group.module + "/" + group.group); + group.heading->setText(headingOf(group)); + for (CatalogEntry const& entry : _options.entries) { + if (entry.module != group.module || entry.group != group.group) { + continue; + } + Item item{.entry = &entry, + .titles = titlesOf(entry), + .row = _backend->createStack(group.section.get(), Axis::Horizontal), + .button = {}, + .content = {}, + .label = {}, + .badge = {}, + .shown = std::nullopt}; + item.row->setTestId("nav_row_" + entry.id); + item.row->setLayout({.width = Sizing::stretch(), .height = {}}); + item.row->setAlign(Align::Center); + item.button = _backend->createButton(item.row.get()); + item.button->setTestId("nav_" + entry.id); + item.button->setStyle(ButtonStyle::Item); + item.button->setLayout({.width = Sizing::stretch(), .height = {}}); + wire(*item.button, entry, item.titles.front()); + // The title and the badge are the button's content, so its selection spans both. The badge is hidden + // until a count is set; the button's accessible name carries the count, so the entry stays one + // control to assistive technology. + ContainerWidget& content = item.button->content(); + item.content = _backend->createStack(&content, Axis::Horizontal); + item.content->setTestId("nav_content_" + entry.id); + item.content->setGap(1); + item.content->setAlign(Align::Center); + item.content->setLayout({.width = Sizing::stretch(), .height = {}}); + item.label = _backend->createText(item.content.get()); + item.label->setText(item.titles.front()); + item.label->setTestId("nav_title_" + entry.id); + item.label->setLayout({.width = Sizing::stretch(), .height = {}}); + item.badge = _backend->createBadge(item.content.get()); + item.badge->setTestId("nav_badge_" + entry.id); + item.badge->setVisible(false); + group.items.push_back(std::move(item)); + } +} + +std::vector Navigator::catalogOrder() const { + std::vector out; + for (CatalogEntry const& entry : _options.entries) { + auto const found = std::ranges::find_if(_groups, [&entry](Group const& candidate) { + return candidate.module == entry.module && candidate.group == entry.group; + }); + if (found != _groups.end() && !std::ranges::contains(out, &*found)) { + out.push_back(&*found); + } + } + return out; +} + +void Navigator::arrange() { + std::vector const listed = catalogOrder(); + bool interleaved = false; + for (std::size_t index = 0; index < listed.size(); ++index) { + interleaved = interleaved || listed.at(index) != &_groups.at(index); + } + bool const moduleMajor = _moduleGroups || !interleaved; + if (moduleMajor == _moduleMajor) { + return; + } + _moduleMajor = moduleMajor; + // After the search field and the pins. + std::size_t at = 2; + if (moduleMajor) { + for (Module& module : _modules) { + _root->moveChild(*module.row, at++); + for (Group& group : _groups) { + if (group.module == module.module) { + _root->moveChild(*group.section, at++); + } + } + } + return; + } + for (Module& module : _modules) { + _root->moveChild(*module.row, at++); + } + for (Group const* const group : listed) { + _root->moveChild(*group->section, at++); + } +} + +void Navigator::filter(std::string const& text) { + _searchText = text; + refreshVisibility(); +} + +Navigator::Module const* Navigator::moduleOf(std::string_view module) const { + auto const found = std::ranges::find(_modules, module, &Module::module); + return found == _modules.end() ? nullptr : &*found; +} + +Navigator::Module* Navigator::moduleOf(std::string_view module) { + auto const found = std::ranges::find(_modules, module, &Module::module); + return found == _modules.end() ? nullptr : &*found; +} + +std::string Navigator::moduleLabel(Module const& module) const { + auto const first = std::ranges::find(_groups, module.module, &Group::module); + if (first != _groups.end()) { + return headingOf(*first); + } + return _options.label ? _options.label(module.module) : module.module; +} + +void Navigator::nameModule(Module const& module) const { + std::string name = moduleLabel(module); + if (module.shown && module.module != _openModule) { + name += ", " + module.shown->text; + } + if (module.failed) { + name += ", " + _failedWord; + } + name += ", " + (module.module == _openModule ? _openWord : _closedWord); + module.button->setAccessibleName(name); +} + +void Navigator::refreshVisibility() { + std::string const wanted = lower(_searchText); + bool const collapsed = _moduleGroups && wanted.empty(); + for (Module const& module : _modules) { + bool const single = module.entries <= 1; + bool const open = module.module == _openModule; + module.row->setVisible(collapsed && !single); + module.chevron->setText(open ? "▾" : "▸"); + module.badge->setVisible(module.shown.has_value() && !open); + nameModule(module); + } + for (Group& group : _groups) { + Module const* const module = moduleOf(group.module); + bool const single = module != nullptr && module->entries <= 1; + bool const open = group.module == _openModule; + bool any = false; + for (Item& item : group.items) { + bool const matches = + wanted.empty() || std::ranges::any_of(item.titles, [&wanted](std::string const& title) { + return lower(title).contains(wanted); + }); + item.row->setVisible(matches); + any = any || matches; + } + bool const firstOfModule = &group == &*std::ranges::find(_groups, group.module, &Group::module); + group.section->setVisible(any && (!collapsed || single || open)); + // In the collapsed form the first group's heading is the module's row, and a single-entry module is + // its entry's row alone. + group.heading->setVisible(!_moduleGroups || !wanted.empty() ? true : !(firstOfModule || single)); + } +} + +void Navigator::showPins() { + _pinButtons.clear(); + for (std::string const& screenId : _pins) { + CatalogEntry const* const entry = entryOf(screenId); + auto button = _backend->createButton(_pinRow.get()); + button->setTestId("pin_" + screenId); + wire(*button, *entry, titlesOf(*entry).front()); + _pinButtons.push_back(std::move(button)); + } +} + +void Navigator::pinsChanged() { + showPins(); + if (_options.onPins) { + _options.onPins(_pins); + } + changed(); +} +} // namespace morph::ui From a2d1dfe9c71cb6c5d97f83da8f2665ce4607f856 Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 01:49:28 +0100 Subject: [PATCH 18/38] Prune service.hpp's and theme.hpp's includes, and fix the service spec's header-only claim theme.hpp no longer includes bundle.hpp and control_shape.hpp (884 MB alone, front end), and service.hpp drops the logger, wire, session, catalogue and shell-parts includes its remaining declarations do not use. The reload note in docs/spec/ui/service.md says the functions live in the morph library. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- docs/spec/ui/service.md | 2 +- include/morph/ui/service.hpp | 7 ------- include/morph/ui/theme.hpp | 2 -- 3 files changed, 1 insertion(+), 10 deletions(-) diff --git a/docs/spec/ui/service.md b/docs/spec/ui/service.md index f5d887c00..681ea66d7 100644 --- a/docs/spec/ui/service.md +++ b/docs/spec/ui/service.md @@ -358,7 +358,7 @@ ids to `reloadDocuments` with the shown screen and reports each refusal as a pro nothing polls, and the digest is read once per connection, by the `open` that loaded the bundle. **In every build.** The reload is compiled into every client and runs only in development mode; nothing in the build -turns it on or off. The library functions above are header-only and are emitted only where a client calls them. +turns it on or off. The library functions above live in the `morph` library, and a client links them only where it calls them. ## Not yet - **Several vocabulary versions of one screen.** There is one vocabulary version, `ui/1`; the registry keeps one diff --git a/include/morph/ui/service.hpp b/include/morph/ui/service.hpp index 85dbbbdc5..bd9f7a416 100644 --- a/include/morph/ui/service.hpp +++ b/include/morph/ui/service.hpp @@ -18,17 +18,10 @@ #include #include -#include "../core/logger.hpp" #include "../core/remote.hpp" -#include "../core/wire.hpp" -#include "../session/session.hpp" #include "bundle.hpp" -#include "catalogue.hpp" -#include "document.hpp" #include "file_store.hpp" -#include "shell_parts.hpp" #include "theme.hpp" -#include "value.hpp" /// @file /// @brief The server side of the UI service (spec 5 §12, §12b, §13): `UiRegistry` collects an application's screens diff --git a/include/morph/ui/theme.hpp b/include/morph/ui/theme.hpp index 58764507a..fd17bb062 100644 --- a/include/morph/ui/theme.hpp +++ b/include/morph/ui/theme.hpp @@ -20,8 +20,6 @@ #include #include -#include "bundle.hpp" -#include "control_shape.hpp" #include "value.hpp" /// @file From c2fda26816ee9d5fa88f001d6cf949f50ddbdcfc Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 04:09:22 +0100 Subject: [PATCH 19/38] Clear the clang-tidy findings the moved bodies exposed Const-correctness, redundant lambda parameter lists and trailing commas are applied, with the designated initialisers the trailing-comma fix-it mangled restored by hand; the check's empty-brace misfires, the menu walks' recursion and the interface-bound signatures carry NOLINT with their reason. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- src/ui/backend.cpp | 2 +- src/ui/host.cpp | 40 +++++--- src/ui/navigator.cpp | 36 ++++--- src/ui/service.cpp | 182 ++++++++++++++++++++++------------- src/ui/service_client.cpp | 54 ++++++----- src/ui/shell_frame.cpp | 30 +++--- src/ui/shell_parts_model.cpp | 2 +- src/ui/theme.cpp | 2 +- src/ui/workspace.cpp | 153 ++++++++++++++++++----------- 9 files changed, 309 insertions(+), 192 deletions(-) diff --git a/src/ui/backend.cpp b/src/ui/backend.cpp index b9ada2b30..6a6f512ae 100644 --- a/src/ui/backend.cpp +++ b/src/ui/backend.cpp @@ -35,4 +35,4 @@ std::string widthClassOf(double units) { } return "expanded"; } -} // namespace morph::ui +}; // namespace morph::ui diff --git a/src/ui/host.cpp b/src/ui/host.cpp index d15875cb5..23c89cb39 100644 --- a/src/ui/host.cpp +++ b/src/ui/host.cpp @@ -119,6 +119,7 @@ bool ScreenHead::submit(std::string_view toolId) { return false; } +// NOLINTNEXTLINE(performance-unnecessary-value-param): the signature is the virtual's. void ScreenHandle::save(std::function done) { if (done) { done(false); @@ -237,8 +238,10 @@ std::expected DocumentScreenHost::remount(ScreenHandle& handle std::shared_ptr document) { auto* const own = dynamic_cast(&handle); if (own == nullptr || !document) { - return std::unexpected(MountError{.screenId = document ? document->id : std::string{}, - .reason = "not a document screen of this host"}); + return std::unexpected(MountError{ + .screenId = document ? document->id : std::string{}, + .reason = "not a document screen of this host", + }); } return own->remount(_interpreter, std::move(document), *_options.backend); } @@ -255,11 +258,13 @@ std::optional DocumentScreenHost::chatContext(ScreenHandle& h context.identity = identityKey(handle.identity().peek()).value_or(std::string{}); context.paramsJson = glz::write_json(valueToJson(Value{own->params()})).value_or(std::string{"{}"}); for (Screen::BoundAlias const& alias : screen->boundAliases()) { - context.models.push_back(chat::ModelRef{.path = alias.decl->path, - .alias = alias.decl->name, - .modelType = alias.decl->type, - .instanceId = alias.facts.instanceId, - .primary = alias.facts.primary}); + context.models.push_back(chat::ModelRef{ + .path = alias.decl->path, + .alias = alias.decl->name, + .modelType = alias.decl->type, + .instanceId = alias.facts.instanceId, + .primary = alias.facts.primary, + }); } return context; } @@ -294,10 +299,11 @@ void DocumentScreenHost::settleCall(std::string_view screenId, ParamMap const& p std::shared_ptr const call = std::move(*found); _unclaimed.erase(found); if (_options.diagnostics) { - _options.diagnostics( - Refusal{.document = std::string{screenId}, - .path = {}, - .reason = "navigate to " + std::string{screenId} + " mounted no screen; its call was cancelled"}); + _options.diagnostics(Refusal{ + .document = std::string{screenId}, + .path = {}, + .reason = "navigate to " + std::string{screenId} + " mounted no screen; its call was cancelled", + }); } call->answer(std::nullopt); } @@ -579,11 +585,13 @@ bool DocumentScreenHost::navigate(NavigateRequest const& request, std::function< forwarded.call = onResult || onCancel; if (forwarded.call) { ValueRecord const* const params = request.params.asRecord(); - _unclaimed.push_back(std::make_shared(Call{.screen = request.screen, - .params = params == nullptr ? ParamMap{} : *params, - .onResult = std::move(onResult), - .onCancel = std::move(onCancel), - .answered = false})); + _unclaimed.push_back(std::make_shared(Call{ + .screen = request.screen, + .params = params == nullptr ? ParamMap{} : *params, + .onResult = std::move(onResult), + .onCancel = std::move(onCancel), + .answered = false, + })); } onNavigate(forwarded); return true; diff --git a/src/ui/navigator.cpp b/src/ui/navigator.cpp index 788a548f5..da5fc47f5 100644 --- a/src/ui/navigator.cpp +++ b/src/ui/navigator.cpp @@ -236,14 +236,16 @@ Navigator::Menu Navigator::menu() const { out.targets.push_back(MenuSlot{.screenId = screenId, .items = {}}); } if (!_pins.empty() && !_groups.empty()) { - out.entries.push_back(MenuEntry{.label = {}, - .icon = {}, - .keys = {}, - .checked = std::nullopt, - .enabled = true, - .items = {}, - .separator = true, - .description = {}}); + out.entries.push_back(MenuEntry{ + .label = {}, + .icon = {}, + .keys = {}, + .checked = std::nullopt, + .enabled = true, + .items = {}, + .separator = true, + .description = {}, + }); out.targets.push_back(MenuSlot{}); } if (_moduleGroups) { @@ -444,14 +446,16 @@ void Navigator::makeGroup(Group& group) { if (entry.module != group.module || entry.group != group.group) { continue; } - Item item{.entry = &entry, - .titles = titlesOf(entry), - .row = _backend->createStack(group.section.get(), Axis::Horizontal), - .button = {}, - .content = {}, - .label = {}, - .badge = {}, - .shown = std::nullopt}; + Item item{ + .entry = &entry, + .titles = titlesOf(entry), + .row = _backend->createStack(group.section.get(), Axis::Horizontal), + .button = {}, + .content = {}, + .label = {}, + .badge = {}, + .shown = std::nullopt, + }; item.row->setTestId("nav_row_" + entry.id); item.row->setLayout({.width = Sizing::stretch(), .height = {}}); item.row->setAlign(Align::Center); diff --git a/src/ui/service.cpp b/src/ui/service.cpp index f0fb66901..49be4b1c1 100644 --- a/src/ui/service.cpp +++ b/src/ui/service.cpp @@ -213,7 +213,7 @@ std::expected UiRegistry::setShellParts(ShellParts parts, Catalog Catalog previousCatalog = _catalog; std::optional previous = std::exchange(_shellParts, std::move(parts)); _catalog = withReads(_baseCatalog, std::move(reads)); - std::expected outcome = [&]() -> std::expected { + std::expected outcome = [&] -> std::expected { if (auto named = checkShellNames()) { return std::unexpected(std::move(*named)); } @@ -272,13 +272,18 @@ std::expected UiRegistry::addScreenImpl(CatalogEntry entry, std:: } logWarnings(*loaded); DocumentActions const named{*loaded}; - Screen screen{.served = ServedScreen{.entry = std::move(entry), - .hash = contentHash(text), - .topQueries = named.topQueries(), - .actions = named.actions(), - .modelTypes = named.modelTypes()}, - .text = std::move(text), - .components = {}}; + Screen screen{ + .served = + ServedScreen{ + .entry = std::move(entry), + .hash = contentHash(text), + .topQueries = named.topQueries(), + .actions = named.actions(), + .modelTypes = named.modelTypes(), + }, + .text = std::move(text), + .components = {}, + }; for (auto const& [name, component] : loaded->components) { static_cast(name); if (!component.qml.empty()) { @@ -300,7 +305,8 @@ std::expected UiRegistry::addEntryImpl(CatalogEntry entry) { .served = ServedScreen{.entry = std::move(entry), .hash = {}, .topQueries = {}, .actions = {}, .modelTypes = {}}, .text = {}, - .components = {}}); + .components = {}, + }); return {}; } @@ -371,11 +377,13 @@ std::optional UiRegistry::checkThemes() const { bool const held = std::ranges::any_of( _files, [&fileId](BundleFile const& file) { return file.kind == kIconFile && file.id == fileId; }); if (!held) { - return Refusal{.document = indexId, - .path = {}, - .reason = std::format("the theme index names the icon `{}` as `{}`, which is not " - "an icon file of the bundle", - name, fileId)}; + return Refusal{ + .document = indexId, + .path = {}, + .reason = std::format("the theme index names the icon `{}` as `{}`, which is not " + "an icon file of the bundle", + name, fileId), + }; } } } @@ -441,12 +449,14 @@ std::expected UiRegistry::addTheme(BundleFile const& file) { } std::expected UiRegistry::applyShellParts(bool replace) { - auto found = std::ranges::find_if(_files, [](BundleFile const& file) { return file.kind == kAppFile; }); + auto const found = std::ranges::find_if(_files, [](BundleFile const& file) { return file.kind == kAppFile; }); if (found == _files.end()) { - BundleFile file{.kind = std::string{kAppFile}, - .id = std::string{kAppFile}, - .bytes = R"({"vocab":"ui/1","id":"app"})", - .isPublic = true}; + BundleFile file{ + .kind = std::string{kAppFile}, + .id = std::string{kAppFile}, + .bytes = R"({"vocab":"ui/1","id":"app"})", + .isPublic = true, + }; auto patched = withShellParts(std::move(file), false); if (!patched) { return std::unexpected(std::move(patched.error())); @@ -472,6 +482,7 @@ std::expected UiRegistry::applyShellParts(bool replace) { std::expected UiRegistry::withShellParts(BundleFile file, bool replace) const { auto document = parseJson(file.bytes); auto* const object = document ? std::get_if(&document->data) : nullptr; + // NOLINTNEXTLINE(bugprone-unchecked-optional-access): every caller holds `_shellParts`. auto shell = parseJson(glz::write_json(*_shellParts).value_or("{}")); if (object == nullptr || !shell) { return refuse(file.id, "the app document is a JSON object"); @@ -519,14 +530,14 @@ Catalog UiRegistry::withReads(Catalog base, Catalog reads) { if (reads.model) { base.model = [first = std::move(base.model), second = std::move(reads.model)](std::string_view typeId) -> std::optional { - auto found = first ? first(typeId) : std::nullopt; + auto const found = first ? first(typeId) : std::nullopt; return found ? found : second(typeId); }; } if (reads.action) { base.action = [first = std::move(base.action), second = std::move(reads.action)](std::string_view actionId) -> std::optional { - auto found = first ? first(actionId) : std::nullopt; + auto const found = first ? first(actionId) : std::nullopt; return found ? found : second(actionId); }; } @@ -542,13 +553,16 @@ std::optional UiRegistry::checkShellNames() const { return screen.served.entry.module == module; }); }; - auto const hasScreen = [this](std::string const& id) { - return std::ranges::any_of(_screens, [&id](Screen const& screen) { return screen.served.entry.id == id; }); + auto const hasScreen = [this](std::string const& screenId) { + return std::ranges::any_of(_screens, + [&screenId](Screen const& screen) { return screen.served.entry.id == screenId; }); }; auto const unknown = [](std::string path, std::string const& kind, std::string const& name) { - return Refusal{.document = std::string{kAppFile}, - .path = std::move(path), - .reason = "the shell names the " + kind + " `" + name + "`, which no screen registered has"}; + return Refusal{ + .document = std::string{kAppFile}, + .path = std::move(path), + .reason = "the shell names the " + kind + " `" + name + "`, which no screen registered has", + }; }; for (std::size_t index = 0; index < _shellParts->modules.size(); ++index) { if (auto const& module = _shellParts->modules.at(index).module; !hasModule(module)) { @@ -582,9 +596,11 @@ std::optional UiRegistry::checkBuildable() const { for (Screen const& screen : _screens) { for (auto const& [path, hash] : screen.components) { if (!componentHashes.contains(hash)) { - return Refusal{.document = screen.served.entry.id, - .path = path, - .reason = "the delivered component is not in the bundle"}; + return Refusal{ + .document = screen.served.entry.id, + .path = path, + .reason = "the delivered component is not in the bundle", + }; } } } @@ -592,7 +608,8 @@ std::optional UiRegistry::checkBuildable() const { return Refusal{ .document = {}, .path = {}, - .reason = "the bundle holds more than " + std::to_string(kMaxBundleFiles) + " files or entries"}; + .reason = "the bundle holds more than " + std::to_string(kMaxBundleFiles) + " files or entries", + }; } std::vector const vocabularies{_vocabularies.begin(), _vocabularies.end()}; if (auto reason = detail::checkNames(vocabularies, kMaxListItems, "the vocabularies", "a vocabulary")) { @@ -603,10 +620,15 @@ std::optional UiRegistry::checkBuildable() const { void UiRegistry::serveFiles(ServedBundle& bundle) const { Manifest manifest{.application = _application.id, .version = _application.version, .files = {}}; - auto serve = [&bundle, &manifest](BundleFile const& file, std::optional screen) { + auto const serve = [&bundle, &manifest](BundleFile const& file, std::optional screen) { std::string const hash = contentHash(file.bytes); manifest.files.push_back(ManifestFile{ - .id = file.id, .kind = file.kind, .hash = hash, .size = file.bytes.size(), .isPublic = file.isPublic}); + .id = file.id, + .kind = file.kind, + .hash = hash, + .size = file.bytes.size(), + .isPublic = file.isPublic, + }); ServedFile& served = bundle.files.try_emplace(hash).first->second; served.bytes = file.bytes; served.holders.push_back( @@ -614,11 +636,14 @@ void UiRegistry::serveFiles(ServedBundle& bundle) const { }; for (Screen const& screen : _screens) { if (!screen.served.hash.empty()) { - serve(BundleFile{.kind = std::string{kScreenFile}, - .id = screen.served.entry.id, - .bytes = screen.text, - .isPublic = screen.served.entry.isPublic}, - bundle.screens.size()); + serve( + BundleFile{ + .kind = std::string{kScreenFile}, + .id = screen.served.entry.id, + .bytes = screen.text, + .isPublic = screen.served.entry.isPublic, + }, + bundle.screens.size()); } bundle.screens.push_back(screen.served); } @@ -630,11 +655,18 @@ void UiRegistry::serveFiles(ServedBundle& bundle) const { }); bundle.manifest = manifestText(manifest); bundle.digest = contentHash(bundle.manifest); - bundle.files.insert_or_assign( - bundle.digest, - ServedFile{.bytes = bundle.manifest, - .holders = {ServedFile::Holder{ - .kind = "manifest", .id = _application.id, .isPublic = true, .screen = std::nullopt}}}); + bundle.files.insert_or_assign(bundle.digest, ServedFile{ + .bytes = bundle.manifest, + .holders = + { + ServedFile::Holder{ + .kind = "manifest", + .id = _application.id, + .isPublic = true, + .screen = std::nullopt, + }, + }, + }); } void UiRegistry::addFacts(ServedBundle& bundle) const { @@ -723,9 +755,11 @@ UiService::Answer UiService::helloAnswer(::morph::wire::Envelope const& request, ::morph::backend::ConnectionFacts& facts) const { std::string const application = _bundle->application.id; if (!gate(authorizer, request, kHelloAction)) { - return Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), - .subject = application, - .outcome = "refused: unauthorized"}; + return Answer{ + .encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), + .subject = application, + .outcome = "refused: unauthorized", + }; } auto client = parseHelloRequest(request.body); if (!client) { @@ -745,13 +779,17 @@ UiService::Answer UiService::helloAnswer(::morph::wire::Envelope const& request, if (client->events) { facts.events = true; } - return Answer{.encoded = ok(request, detail::writeMessage(HelloReply{.application = _bundle->application.id, - .version = _bundle->application.version, - .vocabularies = _bundle->vocabularies, - .digest = _bundle->digest, - .events = client->events})), - .subject = application, - .outcome = "ok, digest " + _bundle->digest}; + return Answer{ + .encoded = ok(request, detail::writeMessage(HelloReply{ + .application = _bundle->application.id, + .version = _bundle->application.version, + .vocabularies = _bundle->vocabularies, + .digest = _bundle->digest, + .events = client->events, + })), + .subject = application, + .outcome = "ok, digest " + _bundle->digest, + }; } std::string UiService::evaluate(::morph::wire::Envelope const& request, @@ -836,9 +874,11 @@ UiService::Answer UiService::catalogAnswer(::morph::wire::Envelope const& reques ::morph::session::IAuthorizer const& authorizer) const { std::string const application = _bundle->application.id; if (!gate(authorizer, request, kCatalogAction)) { - return Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), - .subject = application, - .outcome = "refused: unauthorized"}; + return Answer{ + .encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), + .subject = application, + .outcome = "refused: unauthorized", + }; } CatalogReply reply; Fetchable const fetchable = listEntries(reply, request.session, authorizer); @@ -877,9 +917,11 @@ UiService::Answer UiService::catalogAnswer(::morph::wire::Envelope const& reques }; documents(_bundle->views, reply.views); documents(_bundle->wizards, reply.wizards); - return Answer{.encoded = ok(request, detail::writeMessage(reply)), - .subject = application, - .outcome = std::format("ok, {} entries", reply.entries.size())}; + return Answer{ + .encoded = ok(request, detail::writeMessage(reply)), + .subject = application, + .outcome = std::format("ok, {} entries", reply.entries.size()), + }; } UiService::Fetchable UiService::listEntries(CatalogReply& reply, ::morph::session::Context const& session, @@ -930,15 +972,19 @@ UiService::Answer UiService::fetchAnswer(::morph::wire::Envelope const& request, if (isPublic) { return gate(authorizer, request, kHelloAction) ? Answer{.encoded = ok(request, found->second.bytes), .subject = hash, .outcome = "ok"} - : Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), - .subject = hash, - .outcome = "refused: unauthorized"}; + : Answer{ + .encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), + .subject = hash, + .outcome = "refused: unauthorized", + }; } // The fetch gate comes before the lookup's answer, so a caller it refuses cannot learn which hashes exist. if (!gate(authorizer, request, kFetchAction)) { - return Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), - .subject = hash, - .outcome = "refused: unauthorized"}; + return Answer{ + .encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), + .subject = hash, + .outcome = "refused: unauthorized", + }; } if (found == _bundle->files.end()) { return Answer{.encoded = err(request, "not found"), .subject = hash, .outcome = "refused: not found"}; @@ -947,9 +993,11 @@ UiService::Answer UiService::fetchAnswer(::morph::wire::Envelope const& request, return !holder.screen || screenAdmits(_bundle->screens.at(*holder.screen), request.session, authorizer); }); return admitted ? Answer{.encoded = ok(request, found->second.bytes), .subject = hash, .outcome = "ok"} - : Answer{.encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), - .subject = hash, - .outcome = "refused: unauthorized"}; + : Answer{ + .encoded = err(request, std::string{::morph::wire::kUnauthorizedMessage}), + .subject = hash, + .outcome = "refused: unauthorized", + }; } bool UiService::screenAdmits(ServedScreen const& screen, ::morph::session::Context const& session, diff --git a/src/ui/service_client.cpp b/src/ui/service_client.cpp index 1e4079d34..769d5a28c 100644 --- a/src/ui/service_client.cpp +++ b/src/ui/service_client.cpp @@ -7,13 +7,13 @@ #include #include #include +#include #include #include #include #include #include #include -#include #include #include #include @@ -141,15 +141,17 @@ void UiClient::poll(::morph::session::Context session, std::string knownDigest, std::expected UiClient::openOffline(std::string_view application) const { auto const digest = _shared->cache.store().lastDigest(application); if (!digest) { - return std::unexpected( - ConnectError{.kind = ConnectError::Kind::Unreachable, - .message = "no verified bundle of `" + std::string{application} + "` is cached"}); + return std::unexpected(ConnectError{ + .kind = ConnectError::Kind::Unreachable, + .message = "no verified bundle of `" + std::string{application} + "` is cached", + }); } auto const text = _shared->cache.get(*digest); if (!text) { return std::unexpected(ConnectError{ .kind = ConnectError::Kind::Unreachable, - .message = "the cached manifest of `" + std::string{application} + "` is gone or does not verify"}); + .message = "the cached manifest of `" + std::string{application} + "` is gone or does not verify", + }); } auto manifest = parseManifest(*text); if (!manifest) { @@ -261,14 +263,16 @@ std::expected UiClient::verified(ExchangeReply reply, return body; } if (body->size() > kMaxFileBytes) { - return std::unexpected( - ConnectError{.kind = ConnectError::Kind::Unverified, - .message = expected.what + " is larger than " + std::to_string(kMaxFileBytes) + " bytes"}); + return std::unexpected(ConnectError{ + .kind = ConnectError::Kind::Unverified, + .message = expected.what + " is larger than " + std::to_string(kMaxFileBytes) + " bytes", + }); } if (std::string const actual = contentHash(*body); actual != expected.hash) { - return std::unexpected(ConnectError{.kind = ConnectError::Kind::Unverified, - .message = expected.what + " does not match its hash (expected " + - expected.hash + ", got " + actual + ")"}); + return std::unexpected(ConnectError{ + .kind = ConnectError::Kind::Unverified, + .message = expected.what + " does not match its hash (expected " + expected.hash + ", got " + actual + ")", + }); } return body; } @@ -444,7 +448,7 @@ evaluatorOver(Exchange exchange, ::morph::session::Context session, ::morph::exe return [exchange = std::move(exchange), session = std::move(session), cbExec]( std::string const& typeId, std::string const& actionId, std::string const& bodyJson) { auto [completion, promise] = ::morph::async::Completion::makeSettleable(cbExec); - auto settle = std::make_shared(std::move(promise)); + auto const settle = std::make_shared(std::move(promise)); ::morph::wire::Envelope request; request.kind = std::string{kEvaluateKind}; request.session = session; @@ -468,7 +472,7 @@ std::function<::morph::async::Completion(std::string const&, std::s return [exchange = std::move(exchange), currentSession = std::move(currentSession), cbExec]( std::string const& kind, std::string const& bodyJson) { auto [completion, promise] = ::morph::async::Completion::makeSettleable(cbExec); - auto settle = std::make_shared(std::move(promise)); + auto const settle = std::make_shared(std::move(promise)); ::morph::wire::Envelope request; request.kind = kind; request.session = currentSession ? currentSession() : ::morph::session::Context{}; @@ -496,11 +500,13 @@ FileTransfer::FileTransfer(Exchange exchange, ::morph::session::Context session) void FileTransfer::upload(FileInfo info, std::string bytes, std::string model, std::string action, std::function progress, std::function)> done) const { - auto const run = std::make_shared(Upload{.shared = _shared, - .bytes = std::move(bytes), - .upload = {}, - .progress = std::move(progress), - .done = std::move(done)}); + auto const run = std::make_shared(Upload{ + .shared = _shared, + .bytes = std::move(bytes), + .upload = {}, + .progress = std::move(progress), + .done = std::move(done), + }); FileRequest begin; begin.op = "begin"; begin.name = std::move(info.name); @@ -520,11 +526,13 @@ void FileTransfer::upload(FileInfo info, std::string bytes, std::string model, s void FileTransfer::download(std::string ref, std::function progress, std::function)> done) const { - auto const run = std::make_shared(Download{.shared = _shared, - .ref = std::move(ref), - .file = {}, - .progress = std::move(progress), - .done = std::move(done)}); + auto const run = std::make_shared(Download{ + .shared = _shared, + .ref = std::move(ref), + .file = {}, // NOLINT(readability-trailing-comma): the last designator is empty braces. + .progress = std::move(progress), + .done = std::move(done), + }); readChunk(run); } diff --git a/src/ui/shell_frame.cpp b/src/ui/shell_frame.cpp index 848d6fae4..cc284ed27 100644 --- a/src/ui/shell_frame.cpp +++ b/src/ui/shell_frame.cpp @@ -682,12 +682,14 @@ void ShellFrame::showParts() { : nullptr; std::string const label = chosen == nullptr ? std::string{} : chosen->label; std::string const detail = chosen == nullptr ? std::string{} : chosen->detail; - _context->setTrigger(MenuTrigger{.label = label.empty() ? labels.scope : label, - .icon = {}, - .emphasis = ButtonEmphasis::Normal, - .detail = detail, - .avatar = {}, - .caret = MenuCaret::UpDown}); + _context->setTrigger(MenuTrigger{ + .label = label.empty() ? labels.scope : label, + .icon = {}, + .emphasis = ButtonEmphasis::Normal, + .detail = detail, + .avatar = {}, + .caret = MenuCaret::UpDown, + }); _context->setEnabled(_parts.context.enabled); _context->setAccessibleName(labels.scope + ": " + label + (detail.empty() ? "" : ", " + detail)); } @@ -730,12 +732,14 @@ void ShellFrame::showParts() { _principalMenu->setVisible(person.shown && !_compact); if (person.shown) { _principalMenu->setItems(principalEntries()); - _principalMenu->setTrigger(MenuTrigger{.label = person.name, - .icon = {}, - .emphasis = ButtonEmphasis::Ghost, - .detail = person.subtitle, - .avatar = person.initials, - .caret = MenuCaret::Down}); + _principalMenu->setTrigger(MenuTrigger{ + .label = person.name, + .icon = {}, + .emphasis = ButtonEmphasis::Ghost, + .detail = person.subtitle, + .avatar = person.initials, + .caret = MenuCaret::Down, + }); _principalMenu->setAccessibleName(labels.signedInAs + " " + person.name); } // The help button. @@ -856,7 +860,7 @@ MenuEntry ShellFrame::principalMenuEntry() { void ShellFrame::answerConfirm(bool yes) { _confirm->setOpen(false); - if (auto done = std::exchange(_confirmDone, {})) { + if (auto const done = std::exchange(_confirmDone, {})) { done(yes); } } diff --git a/src/ui/shell_parts_model.cpp b/src/ui/shell_parts_model.cpp index 003e3ca91..7656edc44 100644 --- a/src/ui/shell_parts_model.cpp +++ b/src/ui/shell_parts_model.cpp @@ -652,4 +652,4 @@ ShellPrincipalView ShellPartsModel::principalView(FormatContext const& format) c } return out; } -} // namespace morph::ui +}; // namespace morph::ui diff --git a/src/ui/theme.cpp b/src/ui/theme.cpp index d56c102d2..f537f2fce 100644 --- a/src/ui/theme.cpp +++ b/src/ui/theme.cpp @@ -1263,4 +1263,4 @@ std::vector themeProblems(ThemeIndex const& index, TokenFileLookup } return problems; } -} // namespace morph::ui +}; // namespace morph::ui diff --git a/src/ui/workspace.cpp b/src/ui/workspace.cpp index a60b0969c..01d9bf875 100644 --- a/src/ui/workspace.cpp +++ b/src/ui/workspace.cpp @@ -204,27 +204,43 @@ HeadParts Workspace::headPartsForActive() const { // of its own: with one, a lead's natural width would never be less than it. Row lead = buildHeadLead(*tab, LeadPlacement::Below); lead.common.layout.minWidth.reset(); - return HeadParts{.eyebrow = ui::text(buildHeadEyebrow(*tab)), - .lead = ui::row(std::move(lead)), - .trail = ui::actionBar(buildHeadTrail(*tab)), - .inlineLead = ui::row(buildHeadLead(*tab, LeadPlacement::Inline))}; + return HeadParts{ + .eyebrow = ui::text(buildHeadEyebrow(*tab)), + .lead = ui::row(std::move(lead)), + .trail = ui::actionBar(buildHeadTrail(*tab)), + .inlineLead = ui::row(buildHeadLead(*tab, LeadPlacement::Inline)), + }; } - Text eyebrow{.text = std::string{}, .role = TextRole::Muted, .field = {}, .common = {}}; + Text eyebrow{.text = std::string{}, + .role = TextRole::Muted, + .field = {}, + .common = {}}; // NOLINT(readability-trailing-comma): the last designator is empty braces. eyebrow.common.testId = "head_eyebrow"; eyebrow.common.visible = false; - Row lead{.children = {}, .gap = 0, .common = {}, .tone = std::nullopt}; + Row lead{.children = {}, + .gap = 0, + .common = {}, + .tone = std::nullopt}; // NOLINT(readability-trailing-comma): the last designator is empty braces. lead.common.testId = "head_lead"; lead.common.visible = false; - Row trail{.children = {}, .gap = 0, .common = {}, .tone = std::nullopt}; + Row trail{.children = {}, + .gap = 0, + .common = {}, + .tone = std::nullopt}; // NOLINT(readability-trailing-comma): the last designator is empty braces. trail.common.testId = "head_trail"; trail.common.visible = false; - Row inlineLead{.children = {}, .gap = 0, .common = {}, .tone = std::nullopt}; + Row inlineLead{.children = {}, + .gap = 0, + .common = {}, + .tone = std::nullopt}; // NOLINT(readability-trailing-comma): the last designator is empty braces. inlineLead.common.testId = "head_lead_inline"; inlineLead.common.visible = false; - return HeadParts{.eyebrow = ui::text(std::move(eyebrow)), - .lead = ui::row(std::move(lead)), - .trail = ui::row(std::move(trail)), - .inlineLead = ui::row(std::move(inlineLead))}; + return HeadParts{ + .eyebrow = ui::text(std::move(eyebrow)), + .lead = ui::row(std::move(lead)), + .trail = ui::row(std::move(trail)), + .inlineLead = ui::row(std::move(inlineLead)), + }; } LeadPlacement Workspace::activeLeadPlacement() const { @@ -321,9 +337,11 @@ std::vector Workspace::tabs() const { std::vector out; for (WorkspaceTabId const tab : _model->order()) { ScreenHandle const& handle = *_model->handleOf(tab); - out.push_back(WorkspaceTab{.screenId = std::string{screenOf(tab)}, - .identity = handle.identity().peek(), - .caption = captionOf(handle)}); + out.push_back(WorkspaceTab{ + .screenId = std::string{screenOf(tab)}, + .identity = handle.identity().peek(), + .caption = captionOf(handle), + }); } return out; } @@ -377,11 +395,13 @@ void Workspace::showOverlay(Overlay& overlay, ContainerWidget& footer) { overlay.reported = true; _runtime->untracked([this, &overlay] { if (_diagnostics) { - _diagnostics(Refusal{.document = overlay.screenId, - .path = {}, - .reason = "a dialog or drawer does not show the head menu or tools " - "of " + - overlay.screenId}); + _diagnostics(Refusal{ + .document = overlay.screenId, + .path = {}, + .reason = "a dialog or drawer does not show the head menu or tools " + "of " + + overlay.screenId, + }); } }); } @@ -418,10 +438,12 @@ Node Workspace::overlayActions(ScreenHead& head) { bar.children.push_back(ui::forEach( [&head] { return head.actions().get(); }, [](HeadAction const& action) { return Key{action.id}; }, [&head](reactive::Signal const& action) { - Button button{.label = Prop{[&action] { return action.get().label; }}, - .emphasis = action.peek().emphasis, - .onClick = [&head, actionId = action.peek().id] { head.run(actionId); }, - .common = {}}; + Button button{ + .label = Prop{[&action] { return action.get().label; }}, + .emphasis = action.peek().emphasis, + .onClick = [&head, actionId = action.peek().id] { head.run(actionId); }, + .common = {}, // NOLINT(readability-trailing-comma): the last designator is empty braces. + }; button.common.testId = "overlay_action_" + action.peek().id; button.common.enabled = Prop{[&action] { return action.get().enabled; }}; return ui::button(std::move(button)); @@ -443,6 +465,7 @@ void Workspace::closeOverlays() { } } +// NOLINTNEXTLINE(misc-no-recursion): menu entries nest, and the walk follows them. std::string Workspace::shapeOf(std::vector const& entries) { std::string shape; for (HeadMenuEntry const& entry : entries) { @@ -471,6 +494,7 @@ HeadMenuEntry const* Workspace::entryAt(std::vector const& entrie return entry; } +// NOLINTNEXTLINE(misc-no-recursion): menu entries nest, and the walk follows them. std::vector Workspace::headMenuItems(WorkspaceTabId tab, reactive::Signal const& menu, std::vector const& level, std::vector const& outer) const { @@ -554,8 +578,10 @@ std::expected, MountError> Workspace::mountPage(Wo } else { HostScreenFactory const* const factory = _hosts == nullptr ? nullptr : _hosts->find(facts.host); if (factory == nullptr) { - return std::unexpected(MountError{.screenId = std::string{screenId}, - .reason = "no host screen `" + facts.host + "` is registered"}); + return std::unexpected(MountError{ + .screenId = std::string{screenId}, + .reason = "no host screen `" + facts.host + "` is registered", + }); } handle = (*factory)(params, *page->slot); } @@ -613,7 +639,10 @@ Text Workspace::buildHeadEyebrow(WorkspaceTabId tab) const { reactive::Computed const* const eyebrow = head == nullptr ? nullptr : head->eyebrow(); return eyebrow == nullptr ? std::string{} : eyebrow->get(); }; - Text text{.text = Prop{plain}, .role = TextRole::Muted, .field = {}, .common = {}}; + Text text{.text = Prop{plain}, + .role = TextRole::Muted, + .field = {}, + .common = {}}; // NOLINT(readability-trailing-comma): the last designator is empty braces. text.spans = Prop>{[this, tab] { return eyebrowRunsOf(tab); }}; text.common.testId = "head_eyebrow"; text.common.visible = Prop{[this, tab] { return eyebrowHasContent(tab); }}; @@ -696,6 +725,7 @@ Node Workspace::headTool(WorkspaceTabId tab, reactive::Signal const& t return ui::textInput(std::move(input)); } +// NOLINTNEXTLINE(modernize-use-string-view): the declaration returns std::string. std::string Workspace::idSuffix(LeadPlacement place) { if (place == LeadPlacement::Inline) { return "_inline"; @@ -713,7 +743,10 @@ Row Workspace::buildHeadLead(WorkspaceTabId tab, LeadPlacement place) const { ScreenHead const* const head = headOf(tab); return head == nullptr ? std::vector{} : head->status().get(); }; - Row row{.children = {}, .gap = 1, .common = {}, .tone = std::nullopt}; + Row row{.children = {}, + .gap = 1, + .common = {}, + .tone = std::nullopt}; // NOLINT(readability-trailing-comma): the last designator is empty braces. row.wrap = true; row.align = Align::Center; row.common.testId = "head_lead" + suffix; @@ -736,7 +769,10 @@ Row Workspace::buildHeadLead(WorkspaceTabId tab, LeadPlacement place) const { } return runs; }; - Text text{.text = Prop{subtitle}, .role = TextRole::Muted, .field = {}, .common = {}}; + Text text{.text = Prop{subtitle}, + .role = TextRole::Muted, + .field = {}, + .common = {}}; // NOLINT(readability-trailing-comma): the last designator is empty braces. text.spans = Prop>{spans}; text.common.testId = "head_subtitle" + suffix; text.common.visible = Prop{[spans] { return !spans().empty(); }}; @@ -751,10 +787,12 @@ Row Workspace::buildHeadLead(WorkspaceTabId tab, LeadPlacement place) const { }, [](PlacedBadge const& placed) { return Key{static_cast(placed.index)}; }, [suffix](reactive::Signal const& placed) { - Badge badge{.tone = Prop{[&placed] { return placed.get().badge.tone; }}, - .text = Prop{[&placed] { return placed.get().badge.text; }}, - .icon = placed.peek().badge.icon, - .common = {}}; + Badge badge{ + .tone = Prop{[&placed] { return placed.get().badge.tone; }}, + .text = Prop{[&placed] { return placed.get().badge.text; }}, + .icon = placed.peek().badge.icon, + .common = {}, + }; badge.common.testId = "head_status" + suffix + "_" + std::to_string(placed.peek().index); return ui::badge(std::move(badge)); }, @@ -781,20 +819,22 @@ ActionBar Workspace::buildHeadTrail(WorkspaceTabId tab) const { row.children.push_back(ui::forEach( actions, [](HeadAction const& action) { return Key{action.id}; }, [this, tab](reactive::Signal const& action) { - Button button{.label = Prop{[&action] { - HeadAction const& current = action.get(); - return current.iconOnly ? std::string{} : current.label; - }}, - .emphasis = action.peek().emphasis, - .onClick = - [this, tab, actionId = action.peek().id] { - ScreenHandle* const handle = _model->handleOf(tab); - if (ScreenHead* const head = handle == nullptr ? nullptr : handle->head()) { - head->run(actionId); - } - }, - .common = {}, - .icon = action.peek().icon}; + Button button{ + .label = Prop{[&action] { + HeadAction const& current = action.get(); + return current.iconOnly ? std::string{} : current.label; + }}, + .emphasis = action.peek().emphasis, + .onClick = + [this, tab, actionId = action.peek().id] { + ScreenHandle* const handle = _model->handleOf(tab); + if (ScreenHead* const head = handle == nullptr ? nullptr : handle->head()) { + head->run(actionId); + } + }, + .common = {}, // NOLINT(readability-trailing-comma): the last designator is empty braces. + .icon = action.peek().icon, + }; button.common.testId = "head_action_" + action.peek().id; // An icon-only button is named and titled by its label, which it does not draw. auto const labelWhenIconOnly = [&action] { @@ -818,12 +858,14 @@ ActionBar Workspace::buildHeadTrail(WorkspaceTabId tab) const { }, [](ShapedMenu const& menu) { return Key{menu.shape}; }, [this, tab](reactive::Signal const& menu) { - Menu spec{.items = headMenuItems(tab, menu, menu.peek().entries, {}), - .common = {}, - .style = MenuStyle::Button, - .label = {}, - .icon = "more", - .emphasis = ButtonEmphasis::Normal}; + Menu spec{ + .items = headMenuItems(tab, menu, menu.peek().entries, {}), + .common = {}, // NOLINT(readability-trailing-comma): the last designator is empty braces. + .style = MenuStyle::Button, + .label = {}, + .icon = "more", + .emphasis = ButtonEmphasis::Normal, + }; // The trigger draws the icon alone; its name is the head's `menuLabel`. Prop const name{[this, tab] { ScreenHead const* const head = headOf(tab); @@ -840,7 +882,10 @@ ActionBar Workspace::buildHeadTrail(WorkspaceTabId tab) const { } Node Workspace::headRow(WorkspaceTabId tab) const { - Row row{.children = {}, .gap = 2, .common = {}, .tone = std::nullopt}; + Row row{.children = {}, + .gap = 2, + .common = {}, + .tone = std::nullopt}; // NOLINT(readability-trailing-comma): the last designator is empty braces. row.children.push_back(ui::row(buildHeadLead(tab, LeadPlacement::Below))); row.children.push_back(ui::actionBar(buildHeadTrail(tab))); row.common.testId = "head"; From c8c7338c93572a0047f9f45eb0c69bed15ca622a Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 04:13:23 +0100 Subject: [PATCH 20/38] Fix the two GCC findings in the moved code A stray semicolon after the closing namespace brace in three .cpp files, and a second declaration of detail::weightOf in theme.hpp. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- include/morph/ui/theme.hpp | 2 -- src/ui/backend.cpp | 2 +- src/ui/shell_parts_model.cpp | 2 +- src/ui/theme.cpp | 2 +- 4 files changed, 3 insertions(+), 5 deletions(-) diff --git a/include/morph/ui/theme.hpp b/include/morph/ui/theme.hpp index fd17bb062..01cbb3ddf 100644 --- a/include/morph/ui/theme.hpp +++ b/include/morph/ui/theme.hpp @@ -175,8 +175,6 @@ namespace detail { /// @return Why it is not one, or nothing. [[nodiscard]] MORPH_API std::optional checkShadow(Json const& value); -MORPH_API std::optional weightOf(Json const& value); - /// @brief Reads the tokens of one group into @p out. /// @param group The group's members. /// @param prefix The group's path, with a trailing `.`; empty at the top. diff --git a/src/ui/backend.cpp b/src/ui/backend.cpp index 6a6f512ae..b9ada2b30 100644 --- a/src/ui/backend.cpp +++ b/src/ui/backend.cpp @@ -35,4 +35,4 @@ std::string widthClassOf(double units) { } return "expanded"; } -}; // namespace morph::ui +} // namespace morph::ui diff --git a/src/ui/shell_parts_model.cpp b/src/ui/shell_parts_model.cpp index 7656edc44..003e3ca91 100644 --- a/src/ui/shell_parts_model.cpp +++ b/src/ui/shell_parts_model.cpp @@ -652,4 +652,4 @@ ShellPrincipalView ShellPartsModel::principalView(FormatContext const& format) c } return out; } -}; // namespace morph::ui +} // namespace morph::ui diff --git a/src/ui/theme.cpp b/src/ui/theme.cpp index f537f2fce..d56c102d2 100644 --- a/src/ui/theme.cpp +++ b/src/ui/theme.cpp @@ -1263,4 +1263,4 @@ std::vector themeProblems(ThemeIndex const& index, TokenFileLookup } return problems; } -}; // namespace morph::ui +} // namespace morph::ui From 0041f8d9efc76fa81dfcae271e172d57a497fd3d Mon Sep 17 00:00:00 2001 From: Yaraslau Tamashevich Date: Sun, 15 Nov 2026 08:12:39 +0100 Subject: [PATCH 21/38] Make the moved service, shell and theme sources clang-tidy clean Placement of the suppressions that the move left behind (a theme NOLINTBEGIN without its END in either file), plus the findings the new translation units raise on their own: short names, nested conditionals, unchecked optionals, range loops and emplace. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01No1Nzo5wbYPDDynGBphgqj --- include/morph/ui/theme.hpp | 2 ++ src/ui/backend.cpp | 2 ++ src/ui/explorer.cpp | 2 +- src/ui/navigator.cpp | 15 +++++---- src/ui/shell_frame.cpp | 64 ++++++++++++++++++++---------------- src/ui/shell_parts_model.cpp | 14 ++++++-- src/ui/theme.cpp | 3 ++ src/ui/workspace.cpp | 20 +++++------ 8 files changed, 73 insertions(+), 49 deletions(-) diff --git a/include/morph/ui/theme.hpp b/include/morph/ui/theme.hpp index 01cbb3ddf..81571b789 100644 --- a/include/morph/ui/theme.hpp +++ b/include/morph/ui/theme.hpp @@ -185,6 +185,7 @@ namespace detail { // group's path, then the type it passes down. [[nodiscard]] MORPH_API std::optional readGroup(Json::object_t const& group, std::string const& prefix, std::string const& inherited, TokenSet& out); +// NOLINTEND(misc-no-recursion,bugprone-easily-swappable-parameters) } // namespace detail @@ -242,6 +243,7 @@ using TokenFileLookup = std::function; std::string_view variant, std::string_view density, std::string_view surface); +// NOLINTEND(bugprone-easily-swappable-parameters) namespace detail { diff --git a/src/ui/backend.cpp b/src/ui/backend.cpp index b9ada2b30..e4f4cd99e 100644 --- a/src/ui/backend.cpp +++ b/src/ui/backend.cpp @@ -14,6 +14,7 @@ namespace morph::ui { +// NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the first row, the count, the total: the order setters take. void TableWidget::setRealizedWindow(std::size_t first, std::size_t count, std::size_t total) { static_cast(first); static_cast(count); @@ -26,6 +27,7 @@ std::unique_ptr IViewBackend::createCustom(ContainerWidget* parent return nullptr; } +// NOLINTNEXTLINE(modernize-use-string-view): the declaration returns std::string. std::string widthClassOf(double units) { if (units < 80.0) { return "compact"; diff --git a/src/ui/explorer.cpp b/src/ui/explorer.cpp index 2ec9672a4..a5b9a5027 100644 --- a/src/ui/explorer.cpp +++ b/src/ui/explorer.cpp @@ -443,7 +443,7 @@ void Explorer::listAll() { entry.button = _backend->createButton(model.column.get()); entry.button->setLabel(action); entry.button->setTestId("explorer_action_" + action); - entry.button->setOnClick([this, id = action] { select(id); }); + entry.button->setOnClick([this, actionId = action] { select(actionId); }); model.actions.push_back(std::move(entry)); } } else { diff --git a/src/ui/navigator.cpp b/src/ui/navigator.cpp index da5fc47f5..e956a97eb 100644 --- a/src/ui/navigator.cpp +++ b/src/ui/navigator.cpp @@ -270,6 +270,7 @@ Navigator::Menu Navigator::menu() const { return out; } +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one block per module and per group within it. void Navigator::moduleMenu(Menu& out) const { for (Module const& module : _modules) { MenuEntry submenu; @@ -296,8 +297,8 @@ void Navigator::moduleMenu(Menu& out) const { } if (module.entries > 1) { submenu.label = moduleLabel(module); - if (module.shown) { - submenu.label += " · " + module.shown->text; + if (auto const& shown = module.shown) { + submenu.label += " · " + shown->text; } if (module.failed) { submenu.label += " · !"; @@ -509,23 +510,23 @@ void Navigator::arrange() { } _moduleMajor = moduleMajor; // After the search field and the pins. - std::size_t at = 2; + std::size_t slot = 2; if (moduleMajor) { for (Module& module : _modules) { - _root->moveChild(*module.row, at++); + _root->moveChild(*module.row, slot++); for (Group& group : _groups) { if (group.module == module.module) { - _root->moveChild(*group.section, at++); + _root->moveChild(*group.section, slot++); } } } return; } for (Module& module : _modules) { - _root->moveChild(*module.row, at++); + _root->moveChild(*module.row, slot++); } for (Group const* const group : listed) { - _root->moveChild(*group->section, at++); + _root->moveChild(*group->section, slot++); } } diff --git a/src/ui/shell_frame.cpp b/src/ui/shell_frame.cpp index cc284ed27..630625024 100644 --- a/src/ui/shell_frame.cpp +++ b/src/ui/shell_frame.cpp @@ -77,7 +77,7 @@ ShellFrame::ShellFrame(IViewBackend& backend MORPH_LIFETIMEBOUND, ContainerWidge _sideStart->setLayout({.width = Sizing::fixed(0), .height = {}}); _side->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); _side->setGap(3); - _sideTop->setLayout({.width = {}, .height = Sizing::fixed(0)}); + _sideTop->setLayout({.width = {}, .height = Sizing::fixed(0)}); // NOLINT(readability-trailing-comma) _sideEnd->setLayout({.width = Sizing::fixed(0), .height = {}}); _name->setRole(TextRole::Heading); _name->setText(options.applicationName); @@ -85,7 +85,7 @@ ShellFrame::ShellFrame(IViewBackend& backend MORPH_LIFETIMEBOUND, ContainerWidge // The principal and the sign-out button sit at the sidebar's foot: the navigator takes the sidebar's spare // height above them. Left on the top line they would compete with the head's actions for its trailing edge. - _navigator->root().setLayout({.width = {}, .height = Sizing::stretch()}); + _navigator->root().setLayout({.width = {}, .height = Sizing::stretch()}); // NOLINT(readability-trailing-comma) _principal->setRole(TextRole::Muted); _principal->setTestId("shell_principal"); _signOut->setLabel("Sign out"); @@ -106,8 +106,8 @@ ShellFrame::ShellFrame(IViewBackend& backend MORPH_LIFETIMEBOUND, ContainerWidge // own gap; the line is centred across the bar. _topBar->setGap(2); _topBar->setHeadBar(true); - _topAbove->setLayout({.width = {}, .height = Sizing::fixed(0)}); - _topBelow->setLayout({.width = {}, .height = Sizing::fixed(0)}); + _topAbove->setLayout({.width = {}, .height = Sizing::fixed(0)}); // NOLINT(readability-trailing-comma) + _topBelow->setLayout({.width = {}, .height = Sizing::fixed(0)}); // NOLINT(readability-trailing-comma) _topLine->setGap(4); _topLine->setAlign(Align::Center); _topLine->setTestId("shell_topbar_line"); @@ -129,6 +129,7 @@ ShellFrame::ShellFrame(IViewBackend& backend MORPH_LIFETIMEBOUND, ContainerWidge _navMenu->setOnActivate([this](std::vector const& path) { chooseNav(path); }); _navMenu->setVisible(false); _navigator->setOnChanged([this] { showNavEntries(); }); + // NOLINTNEXTLINE(readability-trailing-comma) _leadBlock->setLayout({.width = Sizing::stretch(), .height = {}, .minWidth = kShellHeadLeadMinimum}); _eyebrow->setTestId("shell_head_eyebrow"); _eyebrow->setVisible(false); @@ -169,7 +170,7 @@ ShellFrame::ShellFrame(IViewBackend& backend MORPH_LIFETIMEBOUND, ContainerWidge _page->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); _page->setGap(4); _page->setTestId("shell_page"); - _top->setLayout({.width = {}, .height = Sizing::fixed(0)}); + _top->setLayout({.width = {}, .height = Sizing::fixed(0)}); // NOLINT(readability-trailing-comma) _padded->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); _padded->setGap(4); _left->setLayout({.width = Sizing::fixed(0), .height = {}}); @@ -184,9 +185,9 @@ ShellFrame::ShellFrame(IViewBackend& backend MORPH_LIFETIMEBOUND, ContainerWidge _chatStart->setLayout({.width = Sizing::fixed(0), .height = {}}); _chatColumn->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); _chatColumn->setGap(3); - _chatTop->setLayout({.width = {}, .height = Sizing::fixed(0)}); + _chatTop->setLayout({.width = {}, .height = Sizing::fixed(0)}); // NOLINT(readability-trailing-comma) _chatSlot->setLayout({.width = Sizing::stretch(), .height = Sizing::stretch()}); - _chatBottom->setLayout({.width = {}, .height = Sizing::fixed(0)}); + _chatBottom->setLayout({.width = {}, .height = Sizing::fixed(0)}); // NOLINT(readability-trailing-comma) _chatEnd->setLayout({.width = Sizing::fixed(0), .height = {}}); buildParts(); showChat(); @@ -311,6 +312,7 @@ void ShellFrame::setSearchText(std::string_view text) { showSearch(); } +// NOLINTNEXTLINE(bugprone-easily-swappable-parameters,readability-identifier-length): the message, yes, then no. void ShellFrame::confirm(std::string_view message, std::string_view yes, std::string_view no, std::function done) { if (_confirm == nullptr) { @@ -355,7 +357,8 @@ void ShellFrame::showTitle() { std::string ShellFrame::connectionText(ConnectionState state) const { ShellLabels const& labels = _parts.labels; - return state == ConnectionState::Connected ? labels.connected + return state == ConnectionState::Connected ? labels.connected + // NOLINTNEXTLINE(readability-avoid-nested-conditional-operator): a three-way pick over the state. : state == ConnectionState::Reconnecting ? labels.reconnecting : labels.offline; } @@ -386,8 +389,8 @@ void ShellFrame::showNavEntries() { std::vector navigation = _navigator->menuEntries(); _navEntryCount = navigation.size(); std::size_t const firstNavigation = entries.size(); - for (std::size_t index = 0; index < navigation.size(); ++index) { - add(std::move(navigation.at(index)), NavTarget::Kind::Navigator, firstNavigation); + for (MenuEntry& item : navigation) { + add(std::move(item), NavTarget::Kind::Navigator, firstNavigation); } if (_parts.help.shown) { add(MenuEntry{.separator = true}, NavTarget::Kind::Separator, 0); @@ -439,6 +442,7 @@ void ShellFrame::chooseNav(std::vector const& path) { case NavTarget::Kind::Context: if (path.size() == 2 && path.at(1) < _contextMap.size() && _contextMap.at(path.at(1)) && _handlers.onContext) { + // NOLINTNEXTLINE(bugprone-unchecked-optional-access): the condition above checked this slot. _handlers.onContext(*_contextMap.at(path.at(1))); } return; @@ -534,6 +538,7 @@ void ShellFrame::buildParts() { _tools->setVisible(false); _searchBox = _backend.createStack(_tools.get(), Axis::Vertical); _searchBox->setLayout( + // NOLINTNEXTLINE(readability-trailing-comma) {.width = Sizing::stretch(), .height = {}, .minWidth = std::nullopt, .maxWidth = kShellSearchWidth}); _searchBox->setTestId("shell_search_box"); _search = _backend.createTextInput(_searchBox.get(), TextInputMode::SingleLine); @@ -659,16 +664,18 @@ void ShellFrame::showBrand() { _footer->setVisible(connection || (brand.shown && !brand.version.empty())); _footerDot->setVisible(connection); _footerState->setVisible(connection); - if (connection) { - _footerState->setText(connectionText(*_parts.connection)); - _footerDot->setRole(*_parts.connection == ConnectionState::Connected ? TextRole::Success - : *_parts.connection == ConnectionState::Reconnecting ? TextRole::Muted - : TextRole::Error); + if (auto const state = _parts.connection) { + _footerState->setText(connectionText(*state)); + _footerDot->setRole(*state == ConnectionState::Connected ? TextRole::Success + // NOLINTNEXTLINE(readability-avoid-nested-conditional-operator) + : *state == ConnectionState::Reconnecting ? TextRole::Muted + : TextRole::Error); } _footerVersion->setVisible(brand.shown && !brand.version.empty()); _footerVersion->setText(brand.version); } +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one block per declared shell part. void ShellFrame::showParts() { bool const bar = barParts(); ShellLabels const& labels = _parts.labels; @@ -764,16 +771,16 @@ std::vector ShellFrame::contextEntries() { heading.label = option.group; heading.heading = true; heading.enabled = false; - entries.push_back(std::move(heading)); - _contextMap.push_back(std::nullopt); + entries.emplace_back(std::move(heading)); + _contextMap.emplace_back(std::nullopt); } group = option.group; MenuEntry entry; entry.label = option.label; entry.description = option.detail; entry.checked = _parts.context.chosen == index; - entries.push_back(std::move(entry)); - _contextMap.push_back(index); + entries.emplace_back(std::move(entry)); + _contextMap.emplace_back(index); } return entries; } @@ -899,10 +906,10 @@ std::string ShellFrame::hitSignature() const { } std::optional> ShellFrame::hitAt(std::size_t flat) const { - for (std::size_t source = 0; source < _parts.search.sources.size(); ++source) { - std::size_t const size = _parts.search.sources.at(source).hits.size(); + for (ShellSourceView const& view : _parts.search.sources) { + std::size_t const size = view.hits.size(); if (flat < size) { - return std::pair{_parts.search.sources.at(source).source, flat}; + return std::pair{view.source, flat}; } flat -= size; } @@ -948,8 +955,8 @@ void ShellFrame::searchChord(std::string const& chord) { std::size_t const total = hitCount(); if (chord == "Down" || chord == "Up") { if (total != 0) { - std::size_t const at = _highlight.value_or(chord == "Down" ? total - 1 : 0); - _highlight = chord == "Down" ? (at + 1) % total : (at + total - 1) % total; + std::size_t const current = _highlight.value_or(chord == "Down" ? total - 1 : 0); + _highlight = chord == "Down" ? (current + 1) % total : (current + total - 1) % total; showSearch(); } } else if (chord == "Shift+Enter" || chord == "Alt+Enter") { @@ -1010,7 +1017,7 @@ std::string ShellFrame::resultsKey(bool panel, bool overlay) const { for (ShellHitView const& hit : source.hits) { key += "\x1e" + hit.kind + "\x1d" + hit.title + "\x1d" + hit.detail; } - key += "\x1f"; + key += '\x1f'; } return key; } @@ -1027,11 +1034,11 @@ void ShellFrame::retire(ResultsColumn& column) { void ShellFrame::renderResults(StackWidget& into, ResultsColumn& column) { ShellLabels const& labels = _parts.labels; - auto const text = [&](std::string const& value, TextRole role, std::string const& id) { + auto const text = [&](std::string const& value, TextRole role, std::string const& testId) { auto widget = _backend.createText(&into); widget->setText(value); widget->setRole(role); - widget->setTestId(id); + widget->setTestId(testId); column.texts.push_back(std::move(widget)); }; bool pending = false; @@ -1044,8 +1051,7 @@ void ShellFrame::renderResults(StackWidget& into, ResultsColumn& column) { text(labels.searching, TextRole::Muted, "shell_search_busy"); } std::size_t flat = 0; - for (std::size_t index = 0; index < _parts.search.sources.size(); ++index) { - ShellSourceView const& source = _parts.search.sources.at(index); + for (ShellSourceView const& source : _parts.search.sources) { if (source.hits.empty() && !source.failed) { continue; } diff --git a/src/ui/shell_parts_model.cpp b/src/ui/shell_parts_model.cpp index 003e3ca91..789ee26f0 100644 --- a/src/ui/shell_parts_model.cpp +++ b/src/ui/shell_parts_model.cpp @@ -25,6 +25,7 @@ namespace { /// @param key A `morph.shell.*` key. /// @param locale The session's locale; only its language matters. /// @return The text; the key when it names none. +// NOLINTNEXTLINE(bugprone-easily-swappable-parameters): a message key, then a locale tag. std::string builtinShellText(std::string_view key, std::string_view locale) { struct Entry { std::string_view key; @@ -32,6 +33,7 @@ std::string builtinShellText(std::string_view key, std::string_view locale) { std::string_view de; }; static constexpr std::array kRows = {{ + // NOLINTBEGIN(modernize-use-designated-initializers): the columns are key, English, German. {"morph.shell.context", "Scope", "Bereich"}, {"morph.shell.search", "Search", "Suche"}, {"morph.shell.searchResults", "Search results", "Suchergebnisse"}, @@ -60,8 +62,10 @@ std::string builtinShellText(std::string_view key, std::string_view locale) { {"morph.shell.connected", "Connected", "Verbunden"}, {"morph.shell.reconnecting", "Reconnecting…", "Verbindung wird wiederhergestellt…"}, {"morph.shell.offline", "Offline", "Offline"}, + // NOLINTEND(modernize-use-designated-initializers) }}; bool const german = locale.starts_with("de"); + // NOLINTNEXTLINE(readability-qualified-auto): an array iterator is a pointer on some standard libraries only. auto const found = std::ranges::find_if(kRows, [key](Entry const& row) { return row.key == key; }); if (found == kRows.end()) { return std::string{key}; @@ -76,7 +80,7 @@ namespace morph::ui { std::string shellText(std::string_view key, FormatContext const& format) { if (format.translations) { - if (auto const pattern = format.translations(std::string{key}, format.locale)) { + if (auto const pattern = format.translations(key, format.locale)) { return *pattern; } } @@ -202,6 +206,7 @@ void ShellPartsModel::setSearchText(std::string const& text) { static_cast(_root->setState(shell_names::kSearchText, Value{text})); } +// NOLINTNEXTLINE(bugprone-easily-swappable-parameters): the source index, then the hit index within it. std::optional ShellPartsModel::hit(std::size_t source, std::size_t hit) const { std::vector const hits = sourceHits(source); if (hit >= hits.size()) { @@ -278,6 +283,7 @@ void ShellPartsModel::problem(std::string const& text) const { } } +// NOLINTNEXTLINE(readability-function-cognitive-complexity): one branch per value shape. std::string ShellPartsModel::describe(Value const& value, FormatContext const& format) { if (ValueRecord const* const record = value.asRecord()) { auto const key = record->find("t"); @@ -357,6 +363,7 @@ std::optional ShellPartsModel::countOf(Value const& reply, std::strin std::vector ShellPartsModel::parseOptions(AppRoot::QueryRead const& read, FormatContext const& format) { std::vector