Documentation
Guides

Async loading

Load a parent's children the first time it is expanded, show the loading and error states, retry a failed load and refresh loaded children.

Children that come from your server are an opt-in feature: asyncChildren(), from @fragiola/tree/async-children (every adapter's /async-children entry). A tree that never imports it does not ship it, and a document with a childrenStatus does not load without it. Installed, a parent whose children come from your server has a childrenStatus instead of childItemIds. The first time it is expanded and visible, the engine calls your loadChildren(item, { signal }) and gives the model what it returns. The package makes no network call: the fetch, the cache and the error message are yours.

Marking the parents

const json: TreeJson<Types> = {
    version: 1,
    rootItemIds: ["photos", "documents"],
    items: {
        photos: { kind: "folder", label: "Photos", childrenStatus: "unloaded" },
        documents: { kind: "folder", label: "Documents", childrenStatus: "unloaded" },
    },
};

The status is unloaded (never asked), loading, loaded or error. A child that is a parent itself gets a childrenStatus too, and loads when it is expanded.

The loader

loadChildren returns the children as item JSON (TreeItemJson<Types>[]); an item without an id gets one from the model. Pass signal to fetch: the engine aborts a load when the tree unmounts, and an aborted or stale load changes nothing.

import { type LoadChildren, Tree, type TreeItemJson } from "@fragiola/tree-react";
import { asyncChildren } from "@fragiola/tree-react/async-children";

const features = [asyncChildren()] as const;

const loadChildren: LoadChildren<Types> = async (item, { signal }) => {
    const response = await fetch(`/api/folders/${item.id}/children`, { signal });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return (await response.json()) as TreeItemJson<Types>[];
};

export function Drive() {
    return (
        <Tree.Root<Types, typeof features>
            defaultTree={json}
            features={features}
            loadChildren={loadChildren}
            aria-label="Cloud drive"
        >
            <Tree.Items<Types>>{(item) => <DriveItem item={item} />}</Tree.Items>
            <Tree.LiveRegion className="visually-hidden" />
        </Tree.Root>
    );
}

The engine runs the commands around it (item.set-children-status to loading, then item.set-children, or item.set-children-status to error), so your middleware and listeners see a load like any other change.

Loading and error states

While loading, the item carries aria-busy and every part data-loading; after a failure, data-load-error. Show a spinner, or an error with a retry button, from the item's status:

import { type ItemOf, Tree, useTree, useTreeState } from "@fragiola/tree-react";

function DriveItem({ item }: { item: ItemOf<Types> }) {
    const { engine } = useTree<Types>();
    const status = useTreeState<Types, string | undefined>((_state, model) =>
        model.get("children-status-by", { itemId: item.id }),
    );
    return (
        <Tree.Item item={item}>
            <Tree.ItemContent className="row">
                <Tree.Toggle>▸</Tree.Toggle>
                <span>{item.label}</span>
                {status === "loading" && <Spinner aria-hidden />}
                {status === "error" && (
                    <button
                        type="button"
                        aria-label={`Retry loading ${item.label}`}
                        onClick={() => engine.run("load-children", { itemId: item.id })}
                    >
                        Retry
                    </button>
                )}
            </Tree.ItemContent>
            <Tree.Group<Types>>{(child) => <DriveItem item={child} />}</Tree.Group>
        </Tree.Item>
    );
}

engine.run("load-children", { itemId }) loads again (a retry, or a first load without expanding); it is refused while the item is loading. A failed load is announced through your announce (an event of type load-error, with the itemId and the error):

const announce = (event: AnnounceEvent) =>
    event.type === "load-error" ? "Could not load this folder. Use Retry to try again." : undefined;
Async loading
Gallery

Refreshing

item.reset-children forgets an item's loaded children (and everything inside them): the status goes back to unloaded, and the next expand loads again; when the item is expanded, the engine loads it right away.

model.run("item.reset-children", { itemId: "photos" });

To put children in yourself (from a cache, a push from the server), run item.set-children with the items.

Saving a tree that loads

A loading item is saved as unloaded: a load is never part of the document, and the next engine starts it again. Loaded children are saved like any others.