Render-ready UI definitions for configurations and actions, plus a Roslyn analyzer for unrenderable shapes

Shoko.Abstractions/Actions/ExecutableActionInfo.cs

@@ -1,4 +1,5 @@
 using System;
+using Shoko.Abstractions.UI;
 
 namespace Shoko.Abstractions.Actions;
 
@@ -44,6 +45,27 @@ namespace Shoko.Abstractions.Actions;
 /// <param name="PluginId">
 ///   The ID of the plugin that owns the action.
 /// </param>
+/// <param name="ParameterDefinition">
+///   A render-ready description of the action's invocation parameters, or
+///   <c>null</c> when the action declares none.
+/// </param>
+/// <remarks>
+///   <para>
+///     An action's parameters are simply its own settable, serialized
+///     properties, since the caller's payload is populated straight onto the
+///     action instance, so they are described by the very same
+///     <see cref="UiDefinition"/> a configuration is described by. A client
+///     renders an invocation form from it exactly as it renders a
+///     configuration editor.
+///   </para>
+///   <para>
+///     The action's own metadata surface (<see cref="Name"/>,
+///     <see cref="Description"/>, <see cref="Category"/>,
+///     <see cref="Permission"/>, <see cref="RequiresConfirmation"/>,
+///     <see cref="Scope"/> and the scoped context) is deliberately not part of
+///     it; those are described by this record instead.
+///   </para>
+/// </remarks>
 public sealed record ExecutableActionInfo(
     Guid ID,
     string Name,
@@ -55,5 +77,6 @@ public sealed record ExecutableActionInfo(
     ActionPermission Permission,
     bool RequiresConfirmation,
     string? ConfirmationMessage,
-    Guid PluginId
+    Guid PluginId,
+    UiDefinition? ParameterDefinition
 );

Shoko.Abstractions/Actions/Services/README.md

@@ -299,6 +299,11 @@ name with no matching property is ignored silently, typos included. Both the
 validation probe and the executing instance are populated, so `Validate` sees
 what `Execute` will.
 
+An omitted parameter keeps the value the instance was constructed with, so a
+parameter is optional unless the action marks it `[Required]` or declares it
+`required`. Such a parameter is marked required in the action's UI definition,
+and `ValidateParameters` refuses a body without it, an absent body included.
+
 ### Asking without running
 
 `ValidateAsync` runs everything `InvokeAsync` does before it queues (scope,

Shoko.Abstractions/Config/Attributes/ConfigurationActionAttribute.cs

@@ -20,7 +20,40 @@ public class ConfigurationActionAttribute(ConfigurationActionType actionType) :
     public ConfigurationActionType ActionType { get; set; } = actionType;
 
     /// <summary>
-    ///   The reactive event type this action handles.
+    ///   The reactive events this action handles. Leave it unset to handle
+    ///   every event.
     /// </summary>
-    public ReactiveEventType ReactiveEventType { get; set; } = ReactiveEventType.All;
+    /// <remarks>
+    ///   A request carries one event, while a handler is interested in as many
+    ///   as it likes, so this is the plural side of the same enum. A handler
+    ///   that names the raised event is preferred over one that named none.
+    ///   Only <see cref="ConfigurationActionType.LiveEdit"/> is raised by an
+    ///   event, so this says nothing on any other hook.
+    /// </remarks>
+    public ReactiveEventType[]? Events { get; set; }
+
+    /// <summary>
+    ///   The members this action watches. Leave it unset to watch everything in
+    ///   the class it is declared on, and everything below it that has no
+    ///   handler of its own.
+    /// </summary>
+    /// <remarks>
+    ///   <para>
+    ///     Naming the members is what lets a client tell whether an edit is
+    ///     worth sending at all: it reaches the element as
+    ///     <c>ReactsToLiveEdit</c>, and an edit to anything else is never sent.
+    ///   </para>
+    ///   <para>
+    ///     A name may descend into a nested class, spelled
+    ///     <c>$"{nameof(Nested)}.{nameof(NestedConfiguration.Member)}"</c>,
+    ///     which stays a constant and survives a rename. It cannot point
+    ///     through a list or a dictionary, which carries no index to say which
+    ///     entry it meant.
+    ///   </para>
+    ///   <para>
+    ///     Only <see cref="ConfigurationActionType.LiveEdit"/> is raised by an
+    ///     edit, so this says nothing on any other hook.
+    ///   </para>
+    /// </remarks>
+    public string[]? ReactiveMembers { get; set; }
 }

Shoko.Abstractions/Config/ConfigurationActionContext.cs

@@ -29,6 +29,19 @@ public class ConfigurationActionContext
     /// </summary>
     public required ConfigurationInfo Info { get; init; }
 
+    /// <summary>
+    /// What the handler before this one in the chain returned, or an empty
+    /// result for the first of them.
+    /// </summary>
+    /// <remarks>
+    /// Every handler along the edited path runs, innermost first, and each is
+    /// handed what the one before it decided so it can build on it. Returning
+    /// something else loses nothing: the messages and validation errors of every
+    /// handler are collected whatever each one returns, and they all edit the
+    /// same configuration instance.
+    /// </remarks>
+    public ConfigurationActionResult PreviousResult { get; init; } = new();
+
     /// <summary>
     /// The configuration service.
     /// </summary>

Shoko.Abstractions/Config/ConfigurationActionMessage.cs

@@ -1,4 +1,4 @@
-using Shoko.Abstractions.Config.Enums;
+using Shoko.Abstractions.UI.Enums;
 
 namespace Shoko.Abstractions.Config;
 

Shoko.Abstractions/Config/ConfigurationActionResult.cs

@@ -1,5 +1,5 @@
 using System.Collections.Generic;
-using Shoko.Abstractions.Config.Enums;
+using Shoko.Abstractions.UI.Enums;
 
 namespace Shoko.Abstractions.Config;
 

Shoko.Abstractions/Config/ConfigurationInfo.cs

@@ -4,6 +4,7 @@
 using NJsonSchema;
 using Shoko.Abstractions.Config.Services;
 using Shoko.Abstractions.Plugin.Models;
+using Shoko.Abstractions.UI;
 
 namespace Shoko.Abstractions.Config;
 
@@ -114,6 +115,32 @@ public IReadOnlySet<string> LoadedEnvironmentVariables
     /// </summary>
     public required JsonSchema Schema { get; init; }
 
+    private UiDefinition? _uiDefinition = null;
+
+    /// <summary>
+    /// A render-ready description of how to lay out an editor for the
+    /// configuration, in the same shape an executable action's parameters are
+    /// described by.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Unlike <see cref="Schema"/>, the returned document is meant to be
+    /// sufficient on its own: every element carries a concrete element kind,
+    /// its label, its default and the constraints needed for a cheap
+    /// client-side pre-check. The schema remains the authority for server-side
+    /// validation.
+    /// </para>
+    /// <para>
+    /// Built on first read and held from then on. A configuration's definition
+    /// can run to a hundred kilobytes or more, so nothing pays for one until it
+    /// asks for it, and nothing pays twice. Two threads racing the first read
+    /// both build one and the later assignment wins, which costs a discarded
+    /// tree and never a wrong answer.
+    /// </para>
+    /// </remarks>
+    public UiDefinition UiDefinition
+        => _uiDefinition ??= _configurationService.GenerateUiDefinition(Type);
+
     /// <summary>
     /// Information about the plugin that the configuration belongs to.
     /// </summary>