feat: add a deep descendant-element search to the ODF XML query helpers

elementsWithTag walks a node forest depth-first, pre-order, returning
every element anywhere in it (not just direct children) with a given
tag, in document order -- mirroring ooxml.js's own elementsWithTag
(src/typed/util.ts).

childrenWithTag's direct-children-only search isn't enough for a
schema position that varies relative to its container, e.g. a text:p
that may sit directly under a draw:text-box or be nested one or more
levels inside a text:list/text:list-item.

Author: Mearman

src/index.ts

@@ -80,7 +80,7 @@ export type { StyleFamily, InternRequest, OtherPartRef, StyleRegistryOptions } f
 
 export { ensureSpan } from './styles/span';
 
-export { rootElement, findChildElement, childrenWithTag, attrValue } from './xml/query';
+export { rootElement, findChildElement, childrenWithTag, elementsWithTag, attrValue } from './xml/query';
 export { decodeXmlText } from './xml/entities';
 
 export { parseOdfLength, formatOdfLength } from './typed/shared/units';

src/xml/query.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { el, txt } from './fragment';
-import { rootElement, findChildElement, childrenWithTag, attrValue } from './query';
+import { rootElement, findChildElement, childrenWithTag, elementsWithTag, attrValue } from './query';
 
 describe('rootElement', () => {
   it('returns the first element node, skipping a leading declaration', () => {
@@ -44,6 +44,26 @@ describe('childrenWithTag', () => {
   });
 });
 
+describe('elementsWithTag', () => {
+  it('finds a matching element at any depth, in document order', () => {
+    const deep = el('text:p', {}, [txt('deep')]);
+    const shallow = el('text:p', {}, [txt('shallow')]);
+    const list = el('text:list', {}, [el('text:list-item', {}, [deep])]);
+    const container = el('draw:text-box', {}, [shallow, list]);
+    expect(elementsWithTag([container], 'text:p')).toEqual([shallow, deep]);
+  });
+
+  it('returns an empty array when nothing matches', () => {
+    expect(elementsWithTag([el('draw:text-box')], 'text:p')).toEqual([]);
+  });
+
+  it('does not match the forest root itself unless it is passed as one of the input nodes', () => {
+    const root = el('text:p', {}, [txt('x')]);
+    expect(elementsWithTag(root.children, 'text:p')).toEqual([]);
+    expect(elementsWithTag([root], 'text:p')).toEqual([root]);
+  });
+});
+
 describe('attrValue', () => {
   it('returns the value of a present attribute', () => {
     expect(attrValue(el('style:style', { 'style:name': 'P1' }), 'style:name')).toBe('P1');

src/xml/query.ts

@@ -33,6 +33,27 @@ export function childrenWithTag(element: XmlElement, tag: string): XmlElement[]
   return out;
 }
 
+// Depth-first pre-order walk over a node forest, descending into every element's own children -- the shared traversal every descendant-search helper below builds on.
+function* walk(nodes: readonly XmlNode[]): Generator<XmlNode> {
+  for (const node of nodes) {
+    yield node;
+    if (node.type === 'element') {
+      yield* walk(node.children);
+    }
+  }
+}
+
+// Every element anywhere in the given forest (not just direct children) with the given tag, in document order -- for a schema position that isn't fixed relative to its container (e.g. a text:p that may sit directly under a draw:text-box or be nested inside a text:list-item), where childrenWithTag's direct-children-only search isn't enough. Mirrors ooxml.js's own elementsWithTag (src/typed/util.ts), which establishes the same descendant-search convention for the equivalent OOXML concept.
+export function elementsWithTag(nodes: readonly XmlNode[], tag: string): XmlElement[] {
+  const out: XmlElement[] = [];
+  for (const node of walk(nodes)) {
+    if (node.type === 'element' && node.tag === tag) {
+      out.push(node);
+    }
+  }
+  return out;
+}
+
 export function attrValue(element: XmlElement, name: string): string | undefined {
   return element.attributes.find((attribute) => attribute.name === name)?.value;
 }