shelving/util/elementmodule

These types and helpers describe a React-compatible element structure (type, props, key) and the generic tools for walking, filtering, and flattening collections of them. The tree-shaped layer built on top of Element — TreeElement, path resolution, and tree flattening — lives in a sibling file; see shelving/util/tree.

Things to know:

  • Element is intentionally compatible with React.ReactElement. It's declared as a type (not an interface) so its implicit index signature lets it satisfy Data for queryElements().
  • Elements is the recursive union React calls ReactNode — a single element, a (possibly nested) iterable, a string, null, or undefined.
  • walkElements() flattens iterable nesting only — it does NOT descend into props.children automatically. Walking deeper is the consumer's job.

Usage

Walking and filtering elements

ts
import { walkElements, filterElements, queryElements } from "shelving/util";

// Flatten any Elements shape to a flat iterable.
for (const el of walkElements(someElements)) {
  console.log(el.type, el.key);
}

// Filter by a match function.
const files = Array.from(filterElements(root, el => el.type === "tree-element"));

// Use query syntax for richer filtering, sorting, and limiting.
const docs = Array.from(queryElements(root, { type: "tree-documentation" }));

Extracting text and merging elements

ts
import { getElementText, mergeElements, isElement, isElements } from "shelving/util";

getElementText(<span>Hello <strong>world</strong></span>); // "Hello world"

const combined = mergeElements(headerElements, bodyElements);
// Returns [headerElements, bodyElements] when both are set; returns whichever is non-nullish when one is absent.

Functions

Go

isElement()function

Is an unknown value an element?

isElement(value: unknown): value is Element
Go

isElements()function

Is an unknown value a collection of elements?

isElements(value: unknown): value is Elements
Go

getElementText()function

Strip all tags from elements to produce a plain text string.

getElementText(elements: Elements): string
Go

walkElements()function

Walk an Elements value into a flat iterable of Element objects.

walkElements(elements: Elements<T>): Iterable<T>
walkElements(elements: Elements): Iterable<Element>
Go

queryElements()function

Filter elements yielded by walkElements() using a Query<Element> object.

queryElements(elements: Elements, query: Query<Element>): Iterable<Element>
Go

filterElements()function

Filter elements yielded by walkElements() using a match function.

filterElements(elements: Elements, match: (element: Element) => boolean): Iterable<Element>
Go

mergeElements()function

Combine two Elements, preserving both if both are set.

mergeElements(a: Elements<T>, b: Elements<T>): Elements<T>
mergeElements(a: Elements, b: Elements): Elements

Types

Go

ElementPropstype

Set of valid props for an element.

{
	readonly children?: Elements;
}
Go

Elementtype

Element with a type, props, and optional key (compatible with React.ReactElement).

{
	readonly type: string | ((props: P) => Elements | null);
	readonly props: P;
	readonly key: string | null;
	readonly $$typeof?: symbol;
}
Go

Elementstype

Collection of elements (compatible with React.ReactNode).

undefined | null | string | T | Iterable<Elements<T>>