Merge pull request #59 from SpineEventEngine/command-message-form-cre…

…ation Extend API for creating the `CommandMessageForm` component
SpineEventEngine · Oct 16, 2024 · aec1a89 · aec1a89
2 parents 0d26f83 + 92b8fbd
commit aec1a89
Show file tree

Hide file tree

Showing 6 changed files with 89 additions and 72 deletions.
diff --git a/client/src/main/kotlin/io/spine/chords/client/form/CommandMessageForm.kt b/client/src/main/kotlin/io/spine/chords/client/form/CommandMessageForm.kt
@@ -72,31 +72,39 @@ public class CommandMessageForm<C : CommandMessage> :
          * expected to include field editors for all command message's fields,
          * which are required to create a valid value of type [C].
          *
-         * @param C
-         *         a type of the command being edited with the form.
-         * @param B
-         *         a type of the command message builder.
-         * @param builder
-         *         a lambda that should create and return a new builder for
-         *         a command of type [C].
-         * @param value
-         *         the command message value to be edited within the form.
-         * @param props
-         *         a lambda that can set any additional props on the form.
-         * @param content
-         *         a form's content, which can contain an arbitrary layout along
-         *         with field editor declarations.
-         * @return a form's instance that has been created for this
-         *         declaration site.
+         * @param C A type of the command being edited with the form.
+         * @param B A type of the command message builder.
+         * @param builder A lambda that should create and return a new builder for
+         *   a command of type [C].
+         * @param value The command message value to be edited within the form.
+         * @param onBeforeBuild A lambda that allows to amend the command message
+         *   after any valid field is entered to it.
+         * @param props A lambda that can set any additional props on the form.
+         * @param content A form's content, which can contain an arbitrary layout along
+         *   with field editor declarations.
+         * @return A form's instance that has been created for this
+         *   declaration site.
          */
         @Composable
         public operator fun <C : CommandMessage, B: ValidatingBuilder<out C>> invoke(
             builder: () -> B,
             value: MutableState<C?> = mutableStateOf(null),
+            onBeforeBuild: ((B) -> B) = { it },
             props: ComponentProps<CommandMessageForm<C>> = ComponentProps {},
             content: @Composable FormPartScope<C>.() -> Unit
-        ): CommandMessageForm<C> = Multipart(builder, value, props) {
-            FormPart(content)
+        ): CommandMessageForm<C> = createAndRender({
+            this.value = value
+
+            @Suppress("UNCHECKED_CAST")
+            this.builder = builder as () -> ValidatingBuilder<C>
+            this.content = content
+
+            @Suppress("UNCHECKED_CAST")
+            this.onBeforeBuild = onBeforeBuild
+                    as (ValidatingBuilder<out C>) -> ValidatingBuilder<out C>
+            props.run { configure() }
+        }) {
+            Content()
         }
 
         /**
@@ -175,7 +183,7 @@ public class CommandMessageForm<C : CommandMessage> :
         public fun <C : CommandMessage, B: ValidatingBuilder<out C>> create(
             builder: () -> B,
             value: MutableState<C?> = mutableStateOf(null),
-            onBeforeBuild: B.() -> Unit = {},
+            onBeforeBuild: ((B) -> B) = { it },
             props: ComponentProps<CommandMessageForm<C>> = ComponentProps {}
         ): CommandMessageForm<C> =
             super.create(null) {
@@ -187,7 +195,8 @@ public class CommandMessageForm<C : CommandMessage> :
 
                 // Storing the builder as ValidatingBuilder internally.
                 @Suppress("UNCHECKED_CAST")
-                this.onBeforeBuild = onBeforeBuild as ValidatingBuilder<out C>.() -> Unit
+                this.onBeforeBuild = onBeforeBuild
+                        as (ValidatingBuilder<out C>) -> ValidatingBuilder<out C>
                 props.run { configure() }
             }
     }

diff --git a/client/src/main/kotlin/io/spine/chords/client/layout/CommandWizard.kt b/client/src/main/kotlin/io/spine/chords/client/layout/CommandWizard.kt
@@ -71,8 +71,11 @@ import io.spine.protobuf.ValidatingBuilder
 public abstract class CommandWizard<C : CommandMessage, B : ValidatingBuilder<out C>> : Wizard() {
 
     internal val commandMessageForm: CommandMessageForm<C> =
-        CommandMessageForm.create({ createCommandBuilder() },
-            onBeforeBuild = { beforeBuild(this) }) {
+        CommandMessageForm.create(
+            { createCommandBuilder() },
+            onBeforeBuild = { beforeBuild(it) }
+        )
+        {
             validationDisplayMode = MANUAL
             eventSubscription = { subscribeToEvent(it) }
         }
@@ -125,22 +128,24 @@ public abstract class CommandWizard<C : CommandMessage, B : ValidatingBuilder<ou
      * valid values. Note that there is no guarantee that the command message
      * that is about to be built is going to be valid.
      *
-     * The builder is passed as the receiver of this function,
-     * so properties can be set and read without referring to the builder
-     * explicitly. For example, if we wanted to set command's `field1` and
+     * The altered builder should be returned as a result of this method.
+     * For example, if we wanted to set command's `field1` and
      * `field2` explicitly, this could be done like this:
      *
      * ```
      *     class WizardImpl: CommandWizard(...) {
      *
-     *         override fun CommandMessage.Builder.onBeforeBuild() = {
-     *             field1 = field1Value
-     *             field2 = field2Value
+     *         override fun beforeBuild(builder: Message.Builder): Message.Builder {
+     *             with(builder) {
+     *                 field1 = field1Value
+     *                 field2 = field2Value
+     *             }
+     *             return builder
      *         }
      *     }
      * ```
      */
-    protected open fun beforeBuild(builder: B) {}
+    protected open fun beforeBuild(builder: B): B { return builder }
 
     override suspend fun submit(): Boolean {
         return commandMessageForm.postCommand()

diff --git a/dependencies.md b/dependencies.md
@@ -1,6 +1,6 @@
 
 
-# Dependencies of `io.spine.chords:spine-chords-client:2.0.0-SNAPSHOT.32`
+# Dependencies of `io.spine.chords:spine-chords-client:2.0.0-SNAPSHOT.33`
 
 ## Runtime
 1.  **Group** : com.google.android. **Name** : annotations. **Version** : 4.1.1.4.
@@ -1066,12 +1066,12 @@
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Tue Oct 15 14:58:07 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Wed Oct 16 13:02:08 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.chords:spine-chords-codegen-tests:2.0.0-SNAPSHOT.32`
+# Dependencies of `io.spine.chords:spine-chords-codegen-tests:2.0.0-SNAPSHOT.33`
 
 ## Runtime
 1.  **Group** : com.google.android. **Name** : annotations. **Version** : 4.1.1.4.
@@ -1925,12 +1925,12 @@ This report was generated on **Tue Oct 15 14:58:07 EEST 2024** using [Gradle-Lic
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Tue Oct 15 14:58:08 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Wed Oct 16 13:02:09 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.chords:spine-chords-core:2.0.0-SNAPSHOT.32`
+# Dependencies of `io.spine.chords:spine-chords-core:2.0.0-SNAPSHOT.33`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -2912,12 +2912,12 @@ This report was generated on **Tue Oct 15 14:58:08 EEST 2024** using [Gradle-Lic
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Tue Oct 15 14:58:09 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Wed Oct 16 13:02:10 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.chords:spine-chords-proto:2.0.0-SNAPSHOT.32`
+# Dependencies of `io.spine.chords:spine-chords-proto:2.0.0-SNAPSHOT.33`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -3916,12 +3916,12 @@ This report was generated on **Tue Oct 15 14:58:09 EEST 2024** using [Gradle-Lic
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Tue Oct 15 14:58:10 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Wed Oct 16 13:02:11 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.chords:spine-chords-proto-values:2.0.0-SNAPSHOT.32`
+# Dependencies of `io.spine.chords:spine-chords-proto-values:2.0.0-SNAPSHOT.33`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -4715,12 +4715,12 @@ This report was generated on **Tue Oct 15 14:58:10 EEST 2024** using [Gradle-Lic
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Tue Oct 15 14:58:10 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Wed Oct 16 13:02:13 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine.chords:spine-chords-runtime:2.0.0-SNAPSHOT.32`
+# Dependencies of `io.spine.chords:spine-chords-runtime:2.0.0-SNAPSHOT.33`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -5484,4 +5484,4 @@ This report was generated on **Tue Oct 15 14:58:10 EEST 2024** using [Gradle-Lic
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Tue Oct 15 14:58:11 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Wed Oct 16 13:02:14 EEST 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
diff --git a/pom.xml b/pom.xml
@@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject.
  -->
 <groupId>io.spine.chords</groupId>
 <artifactId>Chords</artifactId>
-<version>2.0.0-SNAPSHOT.32</version>
+<version>2.0.0-SNAPSHOT.33</version>
 
 <inceptionYear>2015</inceptionYear>
 

diff --git a/proto/src/main/kotlin/io/spine/chords/proto/form/MessageForm.kt b/proto/src/main/kotlin/io/spine/chords/proto/form/MessageForm.kt
@@ -387,29 +387,24 @@ public open class MessageForm<M : Message> :
          * expected to include field editors for all message's fields, which
          * are required to create a valid value of type [M].
          *
-         * @param M
-         *         a type of the message being edited with the form.
-         * @param B
-         *         a type of the message builder.
-         * @param value
-         *         the message value to be edited within the form.
-         * @param builder
-         *         a lambda that should create and return a new builder for
-         *         a message of type [M].
-         * @param props
-         *         a lambda that can set any additional props on the form.
-         * @param content
-         *         a form's content, which can contain an arbitrary layout along
-         *         with field editor declarations.
-         * @return a form's instance that has been created for this
-         *         declaration site.
+         * @param M A type of the message being edited with the form.
+         * @param B A type of the message builder.
+         * @param value The message value to be edited within the form.
+         * @param builder A lambda that should create and return a new builder for
+         *   a message of type [M].
+         * @param props A lambda that can set any additional props on the form.
+         * @param onBeforeBuild A lambda that allows to amend the message
+         *   after any valid field is entered to it.
+         * @param content A form's content, which can contain an arbitrary layout along
+         *   with field editor declarations.
+         * @return A form's instance that has been created for this declaration site.
          */
         @Composable
         public operator fun <M : Message, B : ValidatingBuilder<out M>> invoke(
             value: MutableState<M?>,
             builder: () -> B,
             props: ComponentProps<MessageForm<M>> = ComponentProps {},
-            onBeforeBuild: (ValidatingBuilder<out M>.() -> Unit)? = null,
+            onBeforeBuild: ((ValidatingBuilder<out M>) -> ValidatingBuilder<out M>) = { it },
             content: @Composable FormPartScope<M>.() -> Unit
         ): MessageForm<M> = Multipart(value, builder, props, onBeforeBuild) {
             FormPart(content)
@@ -433,6 +428,9 @@ public open class MessageForm<M : Message> :
          * @param builder A lambda that should create and return a new builder
          *   for a message of type [M].
          * @param props A lambda that can set any additional props on the form.
+         * @param defaultValue A value that should be displayed in the form by default.
+         * @param onBeforeBuild A lambda that allows to amend the message
+         *   after any valid field is entered to it.
          * @param content A form's content, which can contain an arbitrary
          *   layout along with field editor declarations.
          * @return A form's instance that has been created for this
@@ -450,7 +448,7 @@ public open class MessageForm<M : Message> :
             builder: () -> B,
             props: ComponentProps<MessageForm<M>> = ComponentProps {},
             defaultValue: M? = null,
-            onBeforeBuild: (ValidatingBuilder<out M>.() -> Unit)? = null,
+            onBeforeBuild: ((ValidatingBuilder<out M>) -> ValidatingBuilder<out M>) = { it },
             content: @Composable FormPartScope<M>.() -> Unit
         ): MessageForm<M> = Multipart(field, builder, props, defaultValue, onBeforeBuild) {
             FormPart(content)
@@ -473,6 +471,8 @@ public open class MessageForm<M : Message> :
          * @param builder A lambda that should create and return a new builder
          *   for a message of type [M].
          * @param props A lambda that can set any additional props on the form.
+         * @param onBeforeBuild A lambda that allows to amend the message
+         *   after any valid field is entered to it.
          * @param content A form's content, which can contain an arbitrary
          *   layout along with field editor declarations.
          * @return A form's instance that has been created for this
@@ -483,7 +483,7 @@ public open class MessageForm<M : Message> :
             value: MutableState<M?>,
             builder: () -> B,
             props: ComponentProps<MessageForm<M>> = ComponentProps {},
-            onBeforeBuild: (ValidatingBuilder<out M>.() -> Unit)? = null,
+            onBeforeBuild: ((ValidatingBuilder<out M>) -> ValidatingBuilder<out M>) = { it },
             content: @Composable MultipartFormScope<M>.() -> Unit
         ): MessageForm<M> = createAndRender({
             this.value = value
@@ -518,6 +518,9 @@ public open class MessageForm<M : Message> :
          * @param builder A lambda that should create and return a new builder
          *   for a message of type [M].
          * @param props A lambda that can set any additional props on the form.
+         * @param defaultValue A value that should be displayed in the form by default.
+         * @param onBeforeBuild A lambda that allows to amend the message
+         *   after any valid field is entered to it.
          * @param content A form's content, which can contain an arbitrary
          *   layout along with field editor declarations.
          * @return a form's instance that has been created for this
@@ -535,7 +538,7 @@ public open class MessageForm<M : Message> :
             builder: () -> B,
             props: ComponentProps<MessageForm<M>> = ComponentProps {},
             defaultValue: M? = null,
-            onBeforeBuild: (ValidatingBuilder<out M>.() -> Unit)? = null,
+            onBeforeBuild: ((ValidatingBuilder<out M>) -> ValidatingBuilder<out M>) = { it },
             content: @Composable MultipartFormScope<M>.() -> Unit
         ): MessageForm<M> = createAndRender({
 
@@ -979,19 +982,21 @@ public open class MessageForm<M : Message> :
      * which currently have valid values. Note that there is no guarantee that the message
      * that is about to be built is going to be valid.
      *
-     * The builder is passed as the receiver of this callback,
-     * so properties can be set and read without referring to the builder explicitly.
+     * The altered builder should be returned as a result of this method.
      * For example, if we wanted to set message's `field1` and `field2` explicitly,
      * this could be done like this:
      *
      * ```
      *     MessageForm(..., onBeforeBuild = {
-     *         field1 = field1Value
-     *         field2 = field2Value
+     *         with(it) {
+     *             field1 = field1Value
+     *             field2 = field2Value
+     *         }
+     *         it
      *     },  ...) ...
      * ```
      */
-    protected var onBeforeBuild: (ValidatingBuilder<out M>.() -> Unit)? = null
+    protected var onBeforeBuild: ((ValidatingBuilder<out M>) -> ValidatingBuilder<out M>) = { it }
 
     init {
         valueRequired = true
@@ -1374,11 +1379,9 @@ public open class MessageForm<M : Message> :
         }
 
         val validatedMessage = try {
-            val builder = builderWithCurrentFields()
+            var builder = builderWithCurrentFields()
             val beforeBuildCallback = onBeforeBuild
-            if (beforeBuildCallback != null) {
-                builder.beforeBuildCallback()
-            }
+            builder = beforeBuildCallback(builder)
             builder.vBuild()
         } catch (e: ValidationException) {
             if (updateValidationErrors) {

diff --git a/version.gradle.kts b/version.gradle.kts
@@ -27,4 +27,4 @@
 /**
   * The version of all Chords libraries.
   */
-val chordsVersion: String by extra("2.0.0-SNAPSHOT.32")
+val chordsVersion: String by extra("2.0.0-SNAPSHOT.33")