feat(serialization): support metadata-driven ordered emit for transparent XML choice groups (Milestone 7)

- Enhanced `FHIRProperty` to define 'choiceGroup' metadata, supporting transparent XML choice groups without wrapper elements.
- Introduced `ChoiceGroupItem` type for heterogeneous child elements emitted in document order.
- Updated `FHIRComplexTypeXmlNormalizer` to preserve interleaved document order for choice groups by consuming source DOM elements during denormalization.
- Added serialization support for nested choice groups at any depth, ensuring round-trip byte stability (XML to object to XML).
- Implemented comprehensive tests validating ordered emit, namespace handling, and fidelity for choice group serialization and deserialization processes.

Author: Ardenexal

src/Component/Metadata/src/Attribute/FhirProperty.php

@@ -20,6 +20,15 @@
  *   'extension'         — Extension array (named 'extension')
  *   'modifierExtension' — ModifierExtension array (named 'modifierExtension')
  *   'choice'            — Polymorphic value[x] / deceased[x] — must set isChoice: true and variants
+ *   'choiceGroup'       — Transparent (wrapper-less) XML choice group (FHIR tooling extension
+ *                         xml-choice-group). The property is an ordered list<ChoiceGroupItem> whose
+ *                         heterogeneous children emit directly under the parent, in document order
+ *                         (e.g. CDA AD: streetAddressLine, city, streetAddressLine). Set
+ *                         isArray: true, phpType: ChoiceGroupItem::class, and variants keyed by
+ *                         child element name (jsonKey = element name, phpType = the item value's
+ *                         FQCN or 'string'). Unlike 'choice', isChoice stays FALSE — every variant
+ *                         maps to the one list property and appends, rather than selecting a single
+ *                         value[x] slot.
  *   'enum'              — Backed enum (CDA coded property bound to a generated enum, e.g. NullFlavor);
  *                         the property type IS the enum and its ->value is the code string
  *
@@ -30,7 +39,9 @@ final class FhirProperty
 {
     /**
      * @param list<array{fhirType: string, propertyKind: string, phpType: string, jsonKey: string}>|null $variants
-     *                                                                                                             Populated only when isChoice is true. Each variant describes one concrete type in the union.
+     *                                                                                                             Per-variant metadata. Populated when isChoice is true (one entry per value[x] type) OR
+     *                                                                                                             when propertyKind is 'choiceGroup' (one entry per allowed child element name, jsonKey =
+     *                                                                                                             element name, phpType = the item value's FQCN or 'string'). Null otherwise.
      */
     public function __construct(
         /** FHIR type code: 'date', 'HumanName', 'BackboneElement', 'choice', etc. */
@@ -43,7 +54,7 @@ public function __construct(
         public readonly bool $isRequired = false,
         /** True for choice elements (value[x], deceased[x]). Requires variants to be set. */
         public readonly bool $isChoice = false,
-        /** Per-variant metadata for choice elements; null for non-choice properties. */
+        /** Per-variant metadata for 'choice' (value[x]) and 'choiceGroup' properties; null otherwise. */
         public readonly ?array $variants = null,
         /**
          * JSON/XML key override. Null means use the PHP property name as-is.

src/Component/Metadata/src/ChoiceGroupItem.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ardenexal\FHIRTools\Component\Metadata;
+
+/**
+ * One member of a transparent (wrapper-less) XML choice group.
+ *
+ * Some elements carry the FHIR tooling extension
+ * `http://hl7.org/fhir/tools/StructureDefinition/xml-choice-group`, meaning their heterogeneous
+ * child elements appear directly under the parent — with no intervening wrapper element — and in
+ * significant document order (e.g. a CDA `AD` postal address: `streetAddressLine`, `city`,
+ * `streetAddressLine`, …). Such a property is modelled as an ordered `list<ChoiceGroupItem>`, where
+ * each item pairs the child's XML element name (the discriminator) with its value, and the list
+ * order IS the document order.
+ *
+ * The type is intentionally generic — not tied to any particular FHIR/CDA datatype — so the
+ * serializer can drive any `xml-choice-group` element from metadata alone:
+ *  - `$elementName` is the local XML element name, e.g. `streetAddressLine`. It is the discriminator
+ *    for the choice (NOT a class name and NOT an attribute such as `@partType`).
+ *  - `$value` is the child's value: a complex datatype object (e.g. an ADXP) or a bare string for a
+ *    primitive/text part.
+ *
+ * Round-trip note: the serializer reads `$value` reflectively/via the registered variant `phpType`,
+ * so this type carries no compile-time dependency on the concrete datatype classes it wraps.
+ *
+ * Boundary (see M7 plan, task 6): a pure-text choice-group member that has NO element name (e.g. the
+ * `xmlText` string slice of CDA `AD`) is not yet representable here — `$elementName` is required.
+ * The mixed element-and-text case must be designed deliberately before that slice is supported.
+ *
+ * @author Ardenexal
+ */
+final readonly class ChoiceGroupItem
+{
+    /**
+     * @param string        $elementName Local XML element name of the child (the choice discriminator)
+     * @param object|string $value       The child's value: a complex datatype object, or a string for a primitive/text part
+     */
+    public function __construct(
+        public string $elementName,
+        public object|string $value,
+    ) {
+    }
+}

src/Component/Serialization/src/FHIRSerializationService.php

@@ -216,6 +216,16 @@ public function deserializeFromXml(string $xmlData, string $targetClass, array $
             // "2002") are not cast to float/int, which would lose precision on round-trip.
             $xmlContext[XmlEncoder::TYPE_CAST_ATTRIBUTES] = false;
 
+            // Stash the source document element so the denormalizer can recover document order for
+            // transparent xml-choice-group properties — Symfony's XmlEncoder decode regroups
+            // same-named siblings and loses the interleaving (CDA M7). LIBXML_NONET disables network
+            // access; DOCTYPE entities are not expanded. The denormalizer threads the element down to
+            // each complex child, so a choice group nested at any depth recovers its order.
+            $sourceDocument = new \DOMDocument();
+            if (@$sourceDocument->loadXML($xmlData, \LIBXML_NONET) && $sourceDocument->documentElement !== null) {
+                $xmlContext[FHIRComplexTypeXmlNormalizer::SOURCE_ELEMENT_CONTEXT_KEY] = $sourceDocument->documentElement;
+            }
+
             $result = $this->serializer->deserialize($xmlData, $targetClass, 'xml', $xmlContext);
 
             if (!is_object($result)) {

src/Component/Serialization/src/Metadata/PropertyMetadata.php

@@ -21,7 +21,7 @@ final class PropertyMetadata
      * @param bool                               $isArray           True when the property holds a list
      * @param bool                               $isRequired        True when cardinality is 1..*
      * @param bool                               $isChoice          True for choice elements (value[x])
-     * @param list<PropertyVariantMetadata>|null $variants          Non-null only when isChoice is true
+     * @param list<PropertyVariantMetadata>|null $variants          Non-null for 'choice' (value[x]) and 'choiceGroup' properties; null otherwise
      * @param string|null                        $jsonKey           Key override; null = use PHP property name
      * @param string|null                        $phpItemClass      FQCN for complex/backbone array item class (e.g. HumanName::class);
      *                                                              null for primitives, scalars, and choice elements

src/Component/Serialization/src/Metadata/PropertyMetadataProvider.php

@@ -122,8 +122,12 @@ private function resolveFromAttributes(string $className): array
                     /** @var FhirProperty $attr */
                     $attr = $attributes[0]->newInstance();
 
+                    // Build variants for value[x] choices (isChoice) AND for transparent
+                    // xml-choice-group properties (propertyKind 'choiceGroup'), which reuse the
+                    // same per-variant shape keyed by child element name. value[x] semantics are
+                    // unchanged; choiceGroup keeps isChoice false (see FhirProperty propertyKind doc).
                     $variants = null;
-                    if ($attr->isChoice && $attr->variants !== null) {
+                    if ($attr->variants !== null && ($attr->isChoice || $attr->propertyKind === 'choiceGroup')) {
                         $variants = array_map(
                             static fn (array $v): PropertyVariantMetadata => PropertyVariantMetadata::fromArray(
                                 $v['fhirType'],