The app explorer: what a morph application is made of — its screens, the models they use with every action, and for one action its facts, its fields, the places that use it and the widget the framework builds for it, mounted live. More...

#include <algorithm>
#include <cctype>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <functional>
#include <iterator>
#include <map>
#include <memory>
#include <optional>
#include <ranges>
#include <set>
#include <string>
#include <string_view>
#include <utility>
#include <variant>
#include <vector>
#include "../attributes.hpp"
#include "../forms/engine/field_model.hpp"
#include "backend.hpp"
#include "bundle.hpp"
#include "document.hpp"
#include "host.hpp"
#include "value.hpp"

Classes
struct	morph::ui::ActionUse
	One place a document names an action. More...
struct	morph::ui::ActionField
	One field of an action, as the explorer lists it. More...
struct	morph::ui::ExplorerOptions
	What an Explorer shows, and what it reports. More...
class	morph::ui::Explorer
	The app explorer, as a host screen (spec 6 §15): a splitter with the list — a search, the catalog's screens, and every model the catalog names with every action of it — and the chosen action's sections: its facts, its fields, the places that use it, and "Try it", the widget the framework builds for it, mounted live. More...

Typedefs
using	morph::ui::detail::explorer::ScopeChain = std::vector<ScopeDecl const*>
	The scopes around a node, innermost last: the aliases in its reach.
using	morph::ui::ModelSchemas = std::expected<std::string, std::string>
	A model's schemas document: {actionType: schema}, or why the server would not describe the model.
using	morph::ui::SchemasByModel = std::map<std::string, ModelSchemas, std::less<>>
	The schemas documents of the models, by model type.

Enumerations
enum class	morph::ui::ActionUseKind : std::uint8_t { Query , Mutation , Form , Collection , Wizard }
	What names an action in a document. More...
enum class	morph::ui::TryItKind : std::uint8_t { Form , Collection , Wizard }
	Which widget "Try it" builds for an action. More...

Functions
constexpr std::string_view	morph::ui::actionUseKindName (ActionUseKind kind) noexcept
	The name of an action use's kind.
std::string	morph::ui::detail::explorer::typeOf (ScopeChain const &scopes, std::string_view alias)
	The model type an alias binds, from the innermost scope that declares it.
void	morph::ui::detail::explorer::addUse (std::vector< ActionUse > &uses, ScopeChain const &scopes, Catalog const &catalog, std::string_view alias, std::string action, ActionUseKind kind, std::string pointer)
	Records one use, its model type the alias's, else the catalog's for the action.
void	morph::ui::detail::explorer::scopeUses (std::vector< ActionUse > &uses, ScopeChain const &scopes, Catalog const &catalog)
	Records the queries and mutations of the innermost scope.
void	morph::ui::detail::explorer::nodeUses (std::vector< ActionUse > &uses, ScopeChain &scopes, Catalog const &catalog, DocNode const &node)
	Records the uses of a node and everything under it, with the scope it creates.
std::vector< ActionUse >	morph::ui::actionUses (Document const &document, Catalog const &catalog={})
	Every place a loaded document names an action: its queries and mutations at any scope, and its form, collection and wizard nodes, in document order.
std::string	morph::ui::detail::explorer::joined (std::vector< std::string > const &parts, std::string_view separator)
	Texts joined by a separator.
std::string	morph::ui::detail::explorer::typeText (forms::FieldSpec const &field)
	A field's type as the explorer lists it.
std::expected< std::vector< ActionField >, std::string >	morph::ui::actionFields (std::string_view schemaJson)
	The fields of an action, in x-order, as the forms engine reads its schema.
std::string	morph::ui::tryItScreenId (std::string_view actionId)
	The screen id "Try it" mounts an action's document under.
std::string	morph::ui::tryItDocument (std::string_view actionId, std::string_view modelType, TryItKind kind)
	The one-node document "Try it" mounts for an action.
std::expected< std::map< std::string, std::string, std::less<> >, std::string >	morph::ui::schemasOf (std::string_view document)
	The actions a model's schemas document lists, with each one's schema.
Catalog	morph::ui::tryItCatalog (Catalog catalog, SchemasByModel const &schemas)
	The catalog a "Try it" document loads with: `catalog`, whose action lookup also answers an action only a model's schemas document lists (load-time validation refuses an action the catalog does not know, and the catalog knows only those a served document names), and whose schema lookup also answers from the documents.

Detailed Description

The app explorer: what a morph application is made of — its screens, the models they use with every action, and for one action its facts, its fields, the places that use it and the widget the framework builds for it, mounted live.

Specified in docs/spec/ui/explorer.md.

Definition in file explorer.hpp.

Typedef Documentation

◆ ScopeChain

using morph::ui::detail::explorer::ScopeChain = std::vector<ScopeDecl const*>

The scopes around a node, innermost last: the aliases in its reach.

Definition at line 71 of file explorer.hpp.

◆ ModelSchemas

using morph::ui::ModelSchemas = std::expected<std::string, std::string>

A model's schemas document: {actionType: schema}, or why the server would not describe the model.

Definition at line 324 of file explorer.hpp.

◆ SchemasByModel

using morph::ui::SchemasByModel = std::map<std::string, ModelSchemas, std::less<>>

The schemas documents of the models, by model type.

Definition at line 327 of file explorer.hpp.

Enumeration Type Documentation

◆ ActionUseKind

enum class morph::ui::ActionUseKind : std::uint8_t

strong

What names an action in a document.

Enumerator
Query	A query declaration.
Mutation	A mutation declaration.
Form	A form node.
Collection	A collection node.
Wizard	A wizard node.

Definition at line 40 of file explorer.hpp.

◆ TryItKind

enum class morph::ui::TryItKind : std::uint8_t

strong

Which widget "Try it" builds for an action.

Enumerator
Form	A form over the action's schema.
Collection	A collection over the catalog's view document of the action.
Wizard	A wizard over the catalog's wizard document of the action.

Definition at line 282 of file explorer.hpp.

Function Documentation

◆ actionUseKindName()

std::string_view morph::ui::actionUseKindName ( ActionUseKind kind )

nodiscardconstexprnoexcept

The name of an action use's kind.

Parameters

kind The kind.

Returns: "query", "mutation", "form", "collection" or "wizard".

Definition at line 51 of file explorer.hpp.

◆ typeOf()

std::string morph::ui::detail::explorer::typeOf	(	ScopeChain const &	scopes,
		std::string_view	alias )

inlinenodiscard

The model type an alias binds, from the innermost scope that declares it.

Parameters

scopes	The scopes around the use.
alias	The alias.

Returns: The type; empty when no scope declares the alias.

Definition at line 77 of file explorer.hpp.

◆ addUse()

void morph::ui::detail::explorer::addUse	(	std::vector< ActionUse > &	uses,
		ScopeChain const &	scopes,
		Catalog const &	catalog,
		std::string_view	alias,
		std::string	action,
		ActionUseKind	kind,
		std::string	pointer )

inline

Records one use, its model type the alias's, else the catalog's for the action.

Parameters

uses	Where it is recorded.
scopes	The scopes around the use.
catalog	The facts a borrowed alias's type is read from.
alias	The alias the use goes through.
action	The action id.
kind	What names it.
pointer	Its JSON Pointer.

Definition at line 95 of file explorer.hpp.

◆ scopeUses()

void morph::ui::detail::explorer::scopeUses	(	std::vector< ActionUse > &	uses,
		ScopeChain const &	scopes,
		Catalog const &	catalog )

inline

Records the queries and mutations of the innermost scope.

Parameters

uses	Where they are recorded.
scopes	The scopes, the one read last.
catalog	The facts a borrowed alias's type is read from.

Definition at line 112 of file explorer.hpp.

◆ nodeUses()

void morph::ui::detail::explorer::nodeUses	(	std::vector< ActionUse > &	uses,
		ScopeChain &	scopes,
		Catalog const &	catalog,
		DocNode const &	node )

inline

Records the uses of a node and everything under it, with the scope it creates.

Parameters

uses	Where they are recorded.
scopes	The scopes around the node; restored on return.
catalog	The facts a borrowed alias's type is read from.
node	The node.

Definition at line 128 of file explorer.hpp.

◆ actionUses()

std::vector< ActionUse > morph::ui::actionUses	(	Document const &	document,
		Catalog const &	catalog = {} )

inlinenodiscard

Every place a loaded document names an action: its queries and mutations at any scope, and its form, collection and wizard nodes, in document order.

A model type is the alias's, from the nearest enclosing scope that declares it. An alias that borrows another has no type in the document, and takes the catalog's ActionInfo::modelType. A run command names a mutation, not an action, so it is no use of its own.

Parameters

document	The document: a screen, or the app document.
catalog	The facts a borrowed alias's model type is read from; empty leaves such a type empty.

Returns: The uses.

Definition at line 168 of file explorer.hpp.

◆ joined()

std::string morph::ui::detail::explorer::joined	(	std::vector< std::string > const &	parts,
		std::string_view	separator )

inlinenodiscard

Texts joined by a separator.

Parameters

parts	The texts.
separator	What goes between two.

Returns: The joined text.

Definition at line 198 of file explorer.hpp.

◆ typeText()

std::string morph::ui::detail::explorer::typeText ( forms::FieldSpec const & field )

inlinenodiscard

A field's type as the explorer lists it.

Parameters

field The field, as the forms engine reads it.

Returns: The type.

Definition at line 209 of file explorer.hpp.

◆ actionFields()

std::expected< std::vector< ActionField >, std::string > morph::ui::actionFields ( std::string_view schemaJson )

inlinenodiscard

The fields of an action, in x-order, as the forms engine reads its schema.

Parameters

schemaJson The action's schema, as forms::schemaJson<A>() emits it.

Returns: The rows; none for a schema without properties. Or why the schema cannot be read.

Definition at line 247 of file explorer.hpp.

◆ tryItScreenId()

std::string morph::ui::tryItScreenId ( std::string_view actionId )

inlinenodiscard

The screen id "Try it" mounts an action's document under.

Parameters

actionId The action id.

Returns: explorer:try:<action>.

Definition at line 291 of file explorer.hpp.

◆ tryItDocument()

std::string morph::ui::tryItDocument	(	std::string_view	actionId,
		std::string_view	modelType,
		TryItKind	kind )

inlinenodiscard

The one-node document "Try it" mounts for an action.

A private instance of the model under the alias target, the states reply and failure, and a column holding the node over the action (test id tryit) and, for a form, two texts showing the states (tryit_result, tryit_error). A form submits from its button only, and its onSuccess and onError set the states; a collection and a wizard show their own results and errors.

Parameters

actionId	The action id.
modelType	The model type the action belongs to.
kind	The node.

Returns: The document's JSON text, with the id tryItScreenId(actionId).

Definition at line 306 of file explorer.hpp.

◆ schemasOf()

std::expected< std::map< std::string, std::string, std::less<> >, std::string > morph::ui::schemasOf ( std::string_view document )

inlinenodiscard

The actions a model's schemas document lists, with each one's schema.

Parameters

document The document's JSON text.

Returns: The schemas by action id, or why the document cannot be read.

Definition at line 332 of file explorer.hpp.

◆ tryItCatalog()

Catalog morph::ui::tryItCatalog	(	Catalog	catalog,
		SchemasByModel const &	schemas )

inlinenodiscard

The catalog a "Try it" document loads with: catalog, whose action lookup also answers an action only a model's schemas document lists (load-time validation refuses an action the catalog does not know, and the catalog knows only those a served document names), and whose schema lookup also answers from the documents.

Parameters

catalog	The client's catalog.
schemas	The models' schemas documents.

Returns: The catalog.

Definition at line 357 of file explorer.hpp.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ScopeChain

◆ ModelSchemas

◆ SchemasByModel

Enumeration Type Documentation

◆ ActionUseKind

◆ TryItKind

Function Documentation

◆ actionUseKindName()

◆ typeOf()

◆ addUse()

◆ scopeUses()

◆ nodeUses()

◆ actionUses()

◆ joined()

◆ typeText()

◆ actionFields()

◆ tryItScreenId()

◆ tryItDocument()

◆ schemasOf()

◆ tryItCatalog()