From 15842054018101b295ef965d04d3fe238df5d286 Mon Sep 17 00:00:00 2001
From: Michael Bowen <10384982+mikeebowen@users.noreply.github.com>
Date: Thu, 23 Jan 2025 13:35:55 -0800
Subject: [PATCH 1/3] add GetOrAddFirstChild method

---
 .../OpenXmlElement.cs                         | 21 ++++++++++++++++++-
 .../PublicAPI/PublicAPI.Shipped.txt           |  1 +
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/DocumentFormat.OpenXml.Framework/OpenXmlElement.cs b/src/DocumentFormat.OpenXml.Framework/OpenXmlElement.cs
index 969db9c0d..90bc5b28e 100644
--- a/src/DocumentFormat.OpenXml.Framework/OpenXmlElement.cs
+++ b/src/DocumentFormat.OpenXml.Framework/OpenXmlElement.cs
@@ -796,11 +796,30 @@ public void RemoveNamespaceDeclaration(string prefix)
         /// Finds the first child element in type T.
         /// </summary>
         /// <typeparam name="T">Type of element.</typeparam>
-        /// <returns></returns>
+        /// <returns>The first child element of type T or null</returns>
         public T? GetFirstChild<T>()
             where T : OpenXmlElement
             => ChildElements.First<T>();
 
+        /// <summary>
+        /// Finds the first child element of type T or adds a new element if it does not exist.
+        /// </summary>
+        /// <typeparam name="T">Type of element.</typeparam>
+        /// <returns>The new or existing OpenXmlElement</returns>
+        public T GetOrAddFirstChild<T>()
+            where T : OpenXmlElement, new()
+        {
+            var child = GetFirstChild<T>();
+
+            if (child is null)
+            {
+                child = new T();
+                AppendChild(child);
+            }
+
+            return child;
+        }
+
         /// <summary>
         /// Gets the OpenXmlElement element that immediately precedes the current OpenXmlElement element.
         /// Returns null (Nothing in Visual Basic ) if there is no preceding OpenXmlElement element.
diff --git a/src/DocumentFormat.OpenXml.Framework/PublicAPI/PublicAPI.Shipped.txt b/src/DocumentFormat.OpenXml.Framework/PublicAPI/PublicAPI.Shipped.txt
index 3a8794d0b..cf8ffece3 100644
--- a/src/DocumentFormat.OpenXml.Framework/PublicAPI/PublicAPI.Shipped.txt
+++ b/src/DocumentFormat.OpenXml.Framework/PublicAPI/PublicAPI.Shipped.txt
@@ -270,6 +270,7 @@ DocumentFormat.OpenXml.OpenXmlElement.Features.get -> DocumentFormat.OpenXml.Fea
 DocumentFormat.OpenXml.OpenXmlElement.GetAttribute(string! localName, string! namespaceUri) -> DocumentFormat.OpenXml.OpenXmlAttribute
 DocumentFormat.OpenXml.OpenXmlElement.GetAttributes() -> System.Collections.Generic.IList<DocumentFormat.OpenXml.OpenXmlAttribute>!
 DocumentFormat.OpenXml.OpenXmlElement.GetFirstChild<T>() -> T?
+DocumentFormat.OpenXml.OpenXmlElement.GetOrAddFirstChild<T>() -> T!
 DocumentFormat.OpenXml.OpenXmlElement.HasAttributes.get -> bool
 DocumentFormat.OpenXml.OpenXmlElement.InsertAfterSelf<T>(T! newElement) -> T!
 DocumentFormat.OpenXml.OpenXmlElement.InsertBeforeSelf<T>(T! newElement) -> T!

From 9885cde3663c396d8bc61b714a518779ec8cd048 Mon Sep 17 00:00:00 2001
From: Michael Bowen <10384982+mikeebowen@users.noreply.github.com>
Date: Thu, 20 Mar 2025 15:09:31 -0700
Subject: [PATCH 2/3] add test for GetOrAddFirstChild

---
 .../ofapiTest/OpenXmlElementTest2.cs              | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/test/DocumentFormat.OpenXml.Tests/ofapiTest/OpenXmlElementTest2.cs b/test/DocumentFormat.OpenXml.Tests/ofapiTest/OpenXmlElementTest2.cs
index aab185f0d..98cd4fe18 100644
--- a/test/DocumentFormat.OpenXml.Tests/ofapiTest/OpenXmlElementTest2.cs
+++ b/test/DocumentFormat.OpenXml.Tests/ofapiTest/OpenXmlElementTest2.cs
@@ -216,5 +216,20 @@ internal override void ConfigureMetadata(ElementMetadata.Builder builder)
         private class ChildElement : OpenXmlLeafElement
         {
         }
+
+        /// <summary>
+        /// A test for OpenXmlElement.GetOrAddFirstChild.
+        /// </summary>
+        [Fact]
+        public void GetOrAddFirstChildTest()
+        {
+            Paragraph p = new();
+            Run r = p.GetOrAddFirstChild<Run>();
+            Assert.NotNull(r);
+            Assert.Same(r, p.GetFirstChild<Run>());
+
+            var r2 = p.GetOrAddFirstChild<Run>();
+            Assert.Same(r, r2);
+        }
     }
 }

From 83a4d82cf5bbfb018cbd2aa22d2e0569006c7ec3 Mon Sep 17 00:00:00 2001
From: Michael Bowen <10384982+mikeebowen@users.noreply.github.com>
Date: Mon, 24 Mar 2025 09:08:03 -0700
Subject: [PATCH 3/3] Update
 src/DocumentFormat.OpenXml.Framework/OpenXmlElement.cs

Co-authored-by: Taylor Southwick <tasou@microsoft.com>
---
 src/DocumentFormat.OpenXml.Framework/OpenXmlElement.cs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/DocumentFormat.OpenXml.Framework/OpenXmlElement.cs b/src/DocumentFormat.OpenXml.Framework/OpenXmlElement.cs
index 90bc5b28e..9031b05de 100644
--- a/src/DocumentFormat.OpenXml.Framework/OpenXmlElement.cs
+++ b/src/DocumentFormat.OpenXml.Framework/OpenXmlElement.cs
@@ -802,7 +802,7 @@ public void RemoveNamespaceDeclaration(string prefix)
             => ChildElements.First<T>();
 
         /// <summary>
-        /// Finds the first child element of type T or adds a new element if it does not exist.
+        /// Finds the first child element of <typeparam ref="T"/> or adds a new element if it does not exist.
         /// </summary>
         /// <typeparam name="T">Type of element.</typeparam>
         /// <returns>The new or existing OpenXmlElement</returns>