@delightfuldocs/ia-tree v0.3.0
ia-tree
ia-tree
is a specification for representing the information architecture of a website as an abstract syntax tree. It implements the unist spec.
Motivation
I've seen a lot of projects come up with data structures for representing the structure of websites and then creating components and utilities to work with those structures.
It's a lot of redundant work!
If a standard data structure can represent the structure of any website, a common set of components and utilities can be used to render and manipulate that structure.
For example, I should be able to pass the same data into different React components — say, a Sidebar
component and a Breadcrumbs
component — and have both render with sensible defaults.
Install
npm install @delightfuldocs/ia-tree
# yarn add @delightfuldocs/ia-tree
Usage
Import the package:
// ESM import { root, group, page } from "@delightfuldocs/ia-tree"; // CJS const { root, group, page } = require("@delightfuldocs/ia-tree");
Create a tree:
const tree = root([ group("Getting started", [ page("overview", "Overview"), page("quick-start", "Quick start"), page("changelog", "Changelog"), ]), ]);
Use unist utilities to interact with the tree:
import { root, group, page } from "@delightfuldocs/ia-tree"; import { visit } from "unist-util-visit"; const tree = root([ group("Getting started", [ page("overview", "Overview"), page("quick-start", "Quick start"), page("changelog", "Changelog"), ]), ]); visit(tree, (node) => { console.log(node); });
API reference
Builders
Helper functions for creating a valid tree.
group(label: string, children: Child[]) => Group
Creates a Group
node.
Parameters
label
- A human readable label for the group.children
- The nodes that exist within the group.
Returns
Group
root(children: Child[]) => Root
Creates a Root
node.
Type guards
Functions for checking if something is a node (or a certain type of node). These are particularly useful if you're using unist utilities, such as unist-util-visit
to navigate a tree and only want to manipulate certain nodes.
isChild(data: any) => boolean
Returns true
if data
is a Child
node.
isGroup(data: any) => boolean
Returns true
if data
is a Group
node.
Types
The type definitions of the nodes that can exist within a tree.
Child
type Child = Group | Link | Page | Section;
Represents any node that can be a child of a Parent
node. The only node that can't be a child is the Root
node.
Group
type Group = {
type: "group";
label: string;
children: Child[];
};
Represents a group of nodes. The Group
node itself is not associated with a web page. It's simply a collection of nodes assigned a label.
For example, in the Stripe documentation, sidebar labels like Online payments, Invoicing, Get started, and Working with invoices are equivalent to groups:
Link
type Link = {
type: "link";
url: string;
label: string;
};
Represents a link to an external web page.
Page
type Page = {
type: "page";
id: string;
label: string;
children?: Child[];
};
Represents a page of content that exists within the information architecture. The page can optionally have sub-pages via the children
property.
Parent
type Parent = Group | Page | Root | Section;
Represents any node that can have children. The only nodes that can't have children are Link
nodes. It's not required for Page
nodes to have children.
Root
type Root = {
type: "root";
children: Child[];
};
Represents the root node of an information architecture. It can only be used at the root node of a tree. All other nodes can be a descendant of a Root
node.
Section
type Section = {
type: "section";
id: string;
label: string;
children: Child[];
};
Represents a distinct section within an information architecture. The Section
node itself is associated with a page in the information architecture.
When users view a section's page, or a page that exists within a section, the intent is for the primary navigation to only contain pages belonging to that section.
For example, in Stripe's documentation, the Payments or Business operations pages each have their own sidebars. These could be represented as sections.
Utilities
ia-tree-get-breadcrumbs
ia-tree-get-section