shelving/util/treemodule

These types and helpers describe a tree of elements — a hierarchical structure built on top of shelving/util/element, used to represent a documentation site's content hierarchy. The shelving/extract module builds trees of TreeElement nodes from source files; the shelving/ui component renders them.

Things to know:

  • TreeElement requires a non-null key (a slug string) and a type starting with "tree-". Plain Element values can have key: null.
  • The JSX intrinsics (tree-element, tree-documentation) are declared here so TSX files get type-checked props.
  • flattenTree() is the one transform from a raw extracted tree to the structure the UI runs on: it stamps a canonical path on every element and indexes them into a Map keyed by both flat name and canonical path.
  • A child name may contain / (e.g. a module "util/string"), in which case it becomes its own multi-segment chunk of the canonical path.

Usage

Flattening a tree for lookup, routing, and rendering

ts
import { flattenTree } from "shelving/util";

// One pass: stamps each element's canonical `path` and indexes it under both keys.
const map = flattenTree(root);

// Flat keys — what cross-references (`extends` / `overrides`) and README links resolve through.
map.get("Store");                  // the `Store` element
map.get("Store.get");              // the `Store.get` member (qualified `Class.member` key)
map.get("Store")?.props.path;      // "/store/Store" — its stamped canonical URL

// Canonical path keys — what the router resolves a URL to.
map.get("/store/Store");           // the same `Store` element
map.get("/store/Store")?.props.children; // …with its (stamped) children, so the map doubles as the tree

// Merge several trees into one lookup (later writers win on the rare key collision).
const merged = flattenTree(otherRoot, map);

Working with DocumentationElement props

ts
import type { DocumentationElement } from "shelving/util";

// A tree-documentation element carries structured API docs.
const el: DocumentationElement = {
  type: "tree-documentation",
  key: "getFirst",
  props: {
    name: "getFirst",
    kind: "function",
    signatures: ["getFirst<T>(arr: T[]): T | undefined"],
    params: [{ name: "arr", type: "T[]" }],
    returns: [{ type: "T | undefined" }],
  },
};

Functions

Go

flattenTree()function

Flatten a tree into a Map for O(1) lookup, stamping a canonical path onto every element as it walks.

flattenTree(root: TreeElement, base?: ReadonlyMap<string, TreeElement>): Map<string, TreeElement>
Go

searchTree()function

Search the descendants of a tree element and return the best-ranked matches.

searchTree(scope: TreeElement, query: string, options?: SearchTreeOptions): TreeElement[]

Interfaces

Go

TreeElementPropsinterface

Props for a tree element — must have a tree- prefixed type.

{
	readonly name: string;
	readonly title?: string | undefined;
	readonly description?: string | undefined;
	readonly content?: string | undefined;
	readonly source?: AbsolutePath | undefined;
	readonly path?: AbsolutePath | undefined;
	readonly children?: TreeElements | undefined;
}
Go

TreeElementinterface

Element in a heirarchical tree.

{
	readonly key: string;
	readonly type: `tree-${string}`;
}
Go

DocumentationParaminterface

A single parameter for a documented code symbol.

{
	readonly name: string;
	readonly type?: string | undefined;
	readonly description?: string | undefined;
	readonly optional?: boolean | undefined;
	readonly default?: string | undefined;
	readonly readonly?: boolean | undefined;
}
Go

DocumentationReturninterface

A single @returns entry — multiple allowed to document union return types separately.

{
	readonly type?: string | undefined;
	readonly description?: string | undefined;
}
Go

DocumentationThrowinterface

A single @throws entry — multiple allowed to document distinct error types.

{
	readonly type?: string | undefined;
	readonly description?: string | undefined;
}
Go

DocumentationExampleinterface

A single @example entry — the example text/code block.

{
	readonly description?: string | undefined;
}
Go

DocumentationElementPropsinterface

Props for a documented code symbol — a single shape for any kind of code element.

{
	readonly kind?: string | undefined;
	readonly signatures?: ImmutableArray<string> | undefined;
	readonly params?: ImmutableArray<DocumentationParam> | undefined;
	readonly returns?: ImmutableArray<DocumentationReturn> | undefined;
	readonly throws?: ImmutableArray<DocumentationThrow> | undefined;
	readonly examples?: ImmutableArray<DocumentationExample> | undefined;
	readonly class?: string | undefined;
	readonly readonly?: boolean | undefined;
	readonly extends?: string | undefined;
	readonly implements?: ImmutableArray<string> | undefined;
	readonly types?: ImmutableArray<string> | undefined;
	readonly properties?: ImmutableArray<DocumentationParam> | undefined;
}
Go

SearchTreeOptionsinterface

Options for searchTree().

{
	readonly limit?: number | undefined;
	readonly filter?: Query | undefined;
}

Types

Go

TreeElementstype

Collection of tree elements.

Elements<TreeElement>