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;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.
Drag and drop
Move items with the pointer or the keyboard, draw the drop indicator, restrict what moves and where, and announce each step to screen readers.
Inline rename
Edit an item's label in place with your own input and useTreeItemRename, validate the name with middleware, and show why it was refused.