Use custom options to specify how array items are displayed

Previously the option `detail` documented in JSON Forms was misused for
this.

Author: Dominic Tubach

README.md

@@ -9,6 +9,35 @@ In this implementation there are some custom features and keywords not
 specified in standard JSON Forms. (TODO: Not all additional possibilities are
 described here, yet.)
 
+### Array control: options `itemLayout` and `elements`
+
+There are two additional options in controls referencing an array.
+
+The option `itemLayout` allows to specify the layout for the individual controls
+of an array item (e.g. `VerticalLayout`). The default is `TableRow`.
+
+The option `elements` allows to specify the controls for the properties of an
+array item. By default a control is generated for each item property.
+
+Example:
+```json
+{
+  "itemLayout": "VerticalLayout",
+  "elements": [
+    {
+      "type": "Control",
+      "label": "Name",
+      "scope": "#/properties/name"
+    },
+    {
+      "type": "Control",
+      "label": "Birth Date",
+      "scope": "#/properties/birthDate"
+    }
+  ]
+}
+```
+
 ### Description display
 
 The Keyword `descriptionDisplay` in Control options allows to specify the
@@ -39,4 +68,7 @@ Some things cannot be done with (standard) Drupal forms, e.g.
 [Rules](https://jsonforms.io/docs/uischema/rules/) cannot completely be mapped
 to [conditional form fields](https://www.drupal.org/docs/drupal-apis/form-api/conditional-form-fields).
 
+The [`detail` option](https://jsonforms.io/docs/uischema/controls#the-detail-option)
+for controls referencing an array is unsupported.
+
 TODO: Describe all limitations.

src/Form/Control/ArrayArrayFactory.php

@@ -209,19 +209,32 @@ private function buildTableHeader(LayoutDefinition $arrayLayoutDefinition): arra
   }
 
   private function createLayoutDefinition(ArrayControlDefinition $definition): ArrayLayoutDefinition {
-    // Note: We actually do not use "detail" as it is described in JSON Forms:
+    // Note: We used to use "detail" as specification of the "normal" display,
+    // not as it is described in JSON Forms:
     // https://jsonforms.io/docs/uischema/controls#the-detail-option
-    // Should we use another option name instead?
-    $arrayUiSchema = $definition->getOptionsValue('detail');
-    if (!$arrayUiSchema instanceof \stdClass) {
-      $arrayUiSchema = new \stdClass();
+    // Now we use the option "elements" to specify individual controls for the
+    // properties of an item and the option "itemLayout" to specify the layout
+    // to display the elements.
+    $detail = $definition->getOptionsValue('detail');
+    Assertion::nullOrIsInstanceOf($detail, \stdClass::class);
+    if (isset($detail->type) || isset($detail->elements)) {
+      // phpcs:disable Drupal.Semantics.FunctionTriggerError.TriggerErrorTextLayoutRelaxed
+      @trigger_error(<<<EOD
+The properties "type" and "elements" in option "detail" of an array control are
+deprecated and were never supported in accordance to the JSON Forms
+documentation. Use the options "itemLayout" and "elements" instead.
+EOD,
+        E_USER_DEPRECATED);
+      // phpcs:enable
     }
 
-    $arrayUiSchema->type ??= 'TableRow';
+    $arrayUiSchema = new \stdClass();
+    $arrayUiSchema->type = $definition->getOptionsValue('itemLayout') ?? $detail->type ?? 'TableRow';
 
     $items = $definition->getItems();
     Assertion::isInstanceOf($items, \stdClass::class);
-    $arrayUiSchema->elements ??= $this->createElementSchemas($items);
+    $arrayUiSchema->elements = $definition->getOptionsValue('elements') ?? $detail->elements
+      ?? $this->createElementSchemas($items);
 
     return new ArrayLayoutDefinition(
       $arrayUiSchema, $items, $definition->isUiReadonly(), $definition->getRootDefinition()