\n);\n\ncreateRoot(document.querySelector('#root')!).render(\n \n treeWalker={treeWalker}\n itemSize={30}\n height={150}\n width={300}\n >\n {Node}\n ,\n);\n```\n\n\n\n#### Props\n\n##### Props inherited from `FixedSizeList`\n\nYou can read more about these properties in the [`FixedSizeList` documentation](https://react-window.now.sh/#/api/FixedSizeList).\n\n- `children: component`. Uses own implementation, see [below](#children).\n- `className: string = \"\"`\n- `direction: string = \"ltr\"`\n- `height: string | number`\n- `initialScrollOffset: number = 0`\n- `innerRef: function | createRef object`. This property works as it described in the `react-window`. For getting a `FixedSizeList` reference use `listRef`.\n- `innerElementType: React.ElementType = \"div\"`\n- `innerTagName: string`. Deprecated by `react-window`.\n- `itemData: any`\n- `itemKey: function`. Handled internally.\n- `itemSize: number`\n- `layout: string = \"vertical\"`\n- `onItemsRendered: function`\n- `onScroll: function`\n- `outerRef: function | createRef object`\n- `outerElementType: React.ElementType = \"div\"`\n- `outerTagName: string`. Deprecated by `react-window`.\n- `overscanCount: number = 1`\n- `style: object = null`\n- `useIsScrolling: boolean = false`\n- `width: number | string`\n\n##### `async: boolean`\n\nThis option allows making the tree asynchronous; e.g. you will be able to load the branch data on the node opening. All it does under the hood is preserving the tree state between tree buildings on `treeWalker` update, so the user does not see the tree resetting to the default state when the async action is performed.\n\nTo see how it works you can check the [`AsyncData`](./__stories__/AsyncData.story.tsx) story. You can use the `disableAsync` to see what will happen on the async action if the `async` prop is `false`.\n\nWhen combined with the `placeholder` option, the tree re-building won't be interrupted by showing the placeholder; it will be shown only at the first time the tree is building.\n\nTo see how two options interact with each other see the [`AsyncDataIdle`](./__stories__/AsyncDataIdle.story.tsx) story.\n\n##### `children: component`\n\nThe `Node` component responsible for rendering each node.\n\nIt receives the following props:\n\n- Inherited from `react-window`'s `Row` component:\n - `style: object`\n - `isScrolling: boolean` - if `useIsScrolling` is enabled.\n- `Node`-specific props:\n - All fields of the [`FixedSizeNodePublicState`](#types) object.\n - `treeData: any` - any data provided via the `itemData` property of the `FixedSizeTree` component.\n\n##### `placeholder: ReactNode | null`\n\nThis property receives any react node that will be displayed instead of a tree during the building process. This option should only be used if the tree building process requires too much time (which means you have an extremely large dataset, e.g. about a million nodes).\n\nSetting this option enables the [`requestIdleCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback) under the hood for browsers that support this feature. For other browsers the original scenario is applied; no placeholder will be shown.\n\nUsing this feature allows avoiding UI freezes; however, it may slightly increase the time spent for the building process.\n\nTo see how it works, you can check the [BigData](./__stories__/BigData.story.tsx) story. Use `placeholder` tool to add and remove placeholder.\n\nIf you have an asynchronous giant tree and want to use profits of `requestIdleCallback` but don't want placeholder to be shown on the first render (that is probably quite small because all other data will be loaded asynchronously), set `placeholder` to `null`. No placeholder will be shown on the first render but the `requestIdleCallback` building will be enabled and allow avoiding freezes on tree re-building when tree becomes bigger.\n\nTo see how it works you can check the [AsyncDataIdle](./__stories__/AsyncDataIdle.story.tsx) story. It uses the `null` placeholder, so no text is shown for the first build but async requests don't block the UI.\n\n##### `buildingTaskTimeout: number`\n\nThis option works in tandem with the `placeholder` option. With it, you can set the task timeout for the `requestIdleCallback`. The `buildingTaskTimeout` will be sent directly as the `requestIdleCallback`'s `timeout` option.\n\n##### `listRef: Ref`\n\nThis option allows you to get the instance of the internal `react-window` list. It is usually unnecessary because all necessary methods are already provided but still can be useful for edge cases.\n\n##### `rowComponent: component`\n\nThis property receives a custom `Row` component for the `FixedSizeList` that will override the default one. It can be used for adding new functionality.\n\n`Row` component receives the following props:\n\n- `index: number`\n- `data: object` - the data tree component provides to `Row`. It contains the following data:\n - `component: component` - a `Node` component to create a React element from.\n - `getRecordData: function` - a function that gets the record data by `index`. It returns a [`FixedSizeNodePublicState`](#types) object.\n - `treeData: any` - any data provided via the `itemData` property of the `FixedSizeTree` component.\n- `style: object`\n- `isScrolling: boolean`\n\n##### `* treeWalker()`\n\nAn iterator function that walks around the tree and yields node data to build an inner representation of the tree. For algorithm details, see [TreeWalker](#treewalker-3) section.\n\nThe `treeWalker` function should yield the object of the following shape:\n\n- `data: FixedSizeNodeData` - this field is mandatory. See [`FixedSizeNodeData` type](#types) for the shape.\n- `...` - you can add any other data to this object. It will be sent directly to the `treeWalker` at the step [2] of the execution.\n\nTree is re-computed on each `treeWalker` change. To avoid unnecessary tree re-computation keep the `treeWalker` memoized (e.g. with `useCallback` hook). If you want to update tree data, send the new version of `treeWalker` to the tree component.\n\nNote that when `treeWalker` is updated no internal state will be shared with the new tree. Everything will be built from scratch.\n\n#### Methods\n\nThe component provides the following methods.\n\n##### `scrollToItem(id: string | symbol, align?: Align): void`\n\nThe `scrollToItem` method behaves the same as `scrollToItem` from `FixedSizeList` but receives node `id` instead of `index`.\n\n##### `async recomputeTree(state): void`\n\nThis method starts the tree traversing to update the internal state of nodes.\n\nIt receives `state` object that contains nodes' `id` as keys and update rules as values. Each record traverses a subtree of the specified node (also \"owner node\") and does not affect other nodes (it also means that if you specify the root node the whole tree will be traversed).\n\nThe rules object has the following shape:\n\n- `open: boolean` - this rule changes the openness state for the owner node only (subtree nodes are not affected).\n- `subtreeCallback(node: object, ownerNode: object): void` - this callback runs against each node in the subtree of the owner node (including the owner node as well). It receives the subtree node and the owner node. Changing any property of the subtree node will affect the node state and how it will be displayed (e.g. if you change the node openness state it will be displayed according to the changed state).\n\nThe order of rules matters. If you specify the child node rules before the parent node rules, and that rules affect the same property, the parent node `subtreeCallback` will override that property. So if you want to override parent's rules, place children rules after the parent's.\n\nThe type of the node objects received by `subtreeCallback` is `FixedSizeNodePublicState`. See the [types description](#types) below.\n\n##### `recomputeTree` example\n\n```jsx\nimport { useRef } from 'react';\n\nconst treeRef = useRef(null);\n\n// Close all nodes under 'root-1', then re-open 'child-4'\ntreeRef.current?.recomputeTree({\n 'root-1': {\n open: false,\n subtreeCallback(node, ownerNode) {\n // subtreeCallback also runs for the owner node itself, so guard against it\n if (node !== ownerNode) {\n // All descendant nodes will be closed\n node.isOpen = false;\n }\n },\n },\n // But we want `child-4` to be open\n 'child-4': { open: true },\n});\n\n// Attach the ref to the tree component:\n\n {Node}\n;\n```\n\n\nTypeScript\n\n```tsx\nimport { useRef } from 'react';\nimport { FixedSizeTree } from 'react-vtree';\n\n// Assuming MyNodeData is defined as in the example above\nconst treeRef = useRef>(null);\n\ntreeRef.current?.recomputeTree({\n 'root-1': {\n open: false,\n subtreeCallback(node, ownerNode) {\n if (node !== ownerNode) {\n node.isOpen = false;\n }\n },\n },\n 'child-4': { open: true },\n});\n\n// Attach the ref to the tree component:\n\n ref={treeRef}\n treeWalker={treeWalker}\n itemSize={30}\n height={150}\n width={300}\n>\n {Node}\n;\n```\n\n\n\n#### Types\n\n- `FixedSizeNodeData` - value of the `data` field of the object yielded by the `treeWalker` function. The shape is the following:\n - `id` - a unique identifier of the node.\n - `isOpenByDefault` - a default openness state of the node.\n - `...` - you can add any number of additional fields to this object. This object without any change will be sent directly to the `Node` component. You can also use `getRecordData` function to get this object along with the other record data by the index. To describe that data, you have to create a new type that extends the `FixedSizeNodeData` type.\n- `FixedSizeNodePublicState` - the node state available for the `Node` component and `recomputeTree`'s `subtreeCallback` function. It has the following shape:\n - `data: FixedSizeNodeData`.\n - `isOpen: boolean` - a current openness status of the node.\n - `setOpen(state: boolean): Promise` - a function to change the openness state of the node. It receives the new openness state as a `boolean` and opens/closes the node accordingly.\n- `FixedSizeTreeProps` - props that `FixedSizeTree` component receives. Described in the [Props](#props) section.\n- `FixedSizeTreeState` - state that `FixedSizeTree` component has.\n\n### `VariableSizeTree`\n\n#### Example\n\nYou can also take a look at the very similar example at the Storybook:\n\n- [Source code](./__stories__/VariableSizeTree.story.tsx)\n- [Demo](https://lodin.github.io/react-vtree/?path=/story/tree-variablesizetree--default)\n\n```jsx\nimport { VariableSizeTree as Tree } from 'react-vtree';\n\n// Tree component can work with any possible tree structure because it uses an\n// iterator function that the user provides. Structure, approach, and iterator\n// function below is just one of many possible variants.\nconst tree = {\n id: 'root-1',\n name: 'Root #1',\n children: [\n {\n id: 'child-1',\n name: 'Child #1',\n children: [\n { id: 'child-2', name: 'Child #2', children: [] },\n { id: 'child-3', name: 'Child #3', children: [] },\n ],\n },\n {\n id: 'child-4',\n name: 'Child #4',\n children: [{ id: 'child-5', name: 'Child #5', children: [] }],\n },\n ],\n};\n\nconst itemSize = 30;\n\n// This helper function constructs the object that will be sent back at the step\n// [2] during the treeWalker function work. Except for the mandatory `data`\n// field you can put any additional data here.\nconst getNodeData = (node, nestingLevel) => ({\n data: {\n defaultHeight: itemSize, // mandatory\n id: node.id,\n isLeaf: node.children.length === 0,\n isOpenByDefault: true, // mandatory\n name: node.name,\n nestingLevel,\n },\n nestingLevel,\n node,\n});\n\n// The `treeWalker` function runs only on tree re-build which is performed\n// whenever the `treeWalker` prop is changed.\nfunction* treeWalker() {\n // Step [1]: Define the root node of our tree. There can be yielded one or\n // multiple nodes.\n yield getNodeData(tree, 0);\n\n while (true) {\n // Step [2]: Get the parent component back. It will be the object\n // the `getNodeData` function constructed, so you can read any data from it.\n const parent = yield;\n\n for (const child of parent.node.children) {\n // Step [3]: Yielding all the children of the provided component. Then we\n // will return for the step [2] with the first children.\n yield getNodeData(child, parent.nestingLevel + 1);\n }\n }\n}\n\n// Node component receives current node height as a prop\nconst Node = ({ data: { isLeaf, name }, isOpen, style, setOpen }) => (\n
\n);\n\nconst Example: FC = () => (\n treeWalker={treeWalker} height={150} width={300}>\n {Node}\n \n);\n```\n\n\n\n#### Props\n\n##### Props inherited from `VariableSizeList`\n\nYou can read more about these properties in the [`VariableSizeList` documentation](https://react-window.now.sh/#/api/VariableSizeList).\n\nSince `VariableSizeList` in general inherits properties from the `FixedSizeList`, everything described in the [same section](#props-inherited-from-fixedsizelist) for `FixedSizeTree` affects this section. For the rest, there are the following changes:\n\n- `estimatedItemSize: number = 50`\n- `itemSize: (index: number) => number`. This property is optional. If it is not provided, the `defaultHeight` of the specific node will be used. Advanced property; prefer using node state for it.\n\n##### `children`\n\nThe `Node` component. It is the same as the [`FixedSizeTree`](#fixedsizetree)'s one but receives properties from the [`VariableSizeNodePublicState`](#types-1) object.\n\n##### `listRef: Ref`\n\nSame as [`listRef`](#listref-reffixedsizelist) of `FixedSizeTree`.\n\n##### `rowComponent: component`\n\nSee [`rowComponent`](#rowcomponent-component) in the `FixedSizeTree` section; the `getRecordData` returns the [`VariableSizeNodePublicState`](#types-1) object.\n\n##### `* treeWalker()`\n\nAn iterator function that walks over the tree. It behaves the same as `FixedSizeTree`'s `treeWalker`. The `data` object should be in the [`VariableSizeNodeData`](#types-1) shape.\n\n#### Methods\n\nThe component provides the following methods:\n\n##### `scrollToItem(id: string | symbol, align?: Align): void`\n\nThe `scrollToItem` method behaves the same as `scrollToItem` from `VariableSizeList` but receives node `id` instead of `index`.\n\n##### `resetAfterId(id: string | symbol, shouldForceUpdate: boolean = false): void`\n\nThis method replaces the `resetAfterIndex` method of `VariableSizeList` but works exactly the same. It receives node `id` as a first argument.\n\n##### `async recomputeTree(state): void`\n\nSee `FixedSizeTree`'s [`recomputeTree`](#async-recomputetreestate-void) description. There are no differences.\n\n#### Types\n\nAll types in this section are the extended variants of [`FixedSizeTree` types](#types).\n\n- `VariableSizeNodeData` - this object extends [`FixedSizeNodeData`](#types) and contains the following additional fields:\n - `defaultHeight: number` - the default height the node will have.\n- `VariableSizeNodePublicState`. The node state object. Extends the [`FixedSizeNodePublicState`](#types) and contains the following additional fields:\n - `height: number` - the current height of the node. The node will be displayed with this height.\n - `resize(newHeight: number, shouldForceUpdate?: boolean): function` - a function to change the height of the node. It receives two parameters:\n - `newHeight: number` - a new height of the node.\n - `shouldForceUpdate: boolean` - an optional argument that will be sent directly to the [`resetAfterIndex`](https://react-window.now.sh/#/api/VariableSizeList) method.\n- `VariableSizeTreeProps`.\n- `VariableSizeTreeState`.\n\n### TreeWalker algorithm\n\nThe `treeWalker` algorithm works in the following way. During the execution, the `treeWalker` function sends a bunch of objects to the tree component which builds an internal representation of the tree. However, for it, the specific order of yieldings should be performed.\n\n1. The first yielding is always root nodes. They will be the foundation of the whole tree.\n2. Now start a loop where you will receive the parent node and yield all the children of it.\n3. The first yielding of loop iteration should yield an `undefined`. In exchange, you will receive a node for which you should yield all the children in the same way you've done with the root ones.\n4. When all the children are yielded, and the new iteration of loop is started, you yield `undefined` again and in exchange receive the next node. It may be:\n - a child node if the previous node has children;\n - a sibling node if it has siblings;\n - a sibling of an ancestor node.\n5. When the whole tree is finished and algorithm reaches the end, the loop stops. You don't have to finish `treeWalker`'s loop manually.\n\nThe example of this algorithm is the following `treeWalker` function:\n\n```js\nfunction* treeWalker() {\n // Here we start our tree by yielding the data for the root node.\n yield getNodeData(rootNode, 0);\n\n while (true) {\n // Here in the loop we receive the next node whose children should be\n // yielded next.\n const parent = yield;\n\n for (const child of parent.node.children) {\n // Here we go through the parent's children and yield them to the tree\n // component\n yield getNodeData(child, parent.nestingLevel + 1);\n // Then the loop iteration is over, and we are going to our next parent\n // node.\n }\n }\n}\n```\n\n\nTypeScript\n\n```ts\nfunction* treeWalker(): ReturnType> {\n yield getNodeData(rootNode, 0);\n\n while (true) {\n const parent = yield;\n\n for (const child of parent.node.children) {\n yield getNodeData(child, parent.nestingLevel + 1);\n }\n }\n}\n```\n\n\n\n## Migrating `2.x.x` -> `3.x.x`\n\nIf you use `react-vtree` version 2, it is preferable to migrate to version 3. The third version is quite different under the hood and provides a far more optimized approach to the initial tree building and tree openness state changes. The most obvious it becomes if you have a giant tree (with about 1 million of nodes).\n\nTo migrate to the new version, you have to do the following steps.\n\n### 1. Migrate `treeWalker`\n\nThe `treeWalker` was and is the heart of the `react-vtree`. However, now it looks a bit different.\n\nOld `treeWalker` worked for both initial tree building and changing node openness state:\n\n```js\nfunction* treeWalker(refresh) {\n const stack = [];\n\n stack.push({\n nestingLevel: 0,\n node: rootNode,\n });\n\n // Go through all the nodes adding children to the stack and removing them\n // when they are processed.\n while (stack.length !== 0) {\n const { node, nestingLevel } = stack.pop();\n const id = node.id.toString();\n\n // Receive the openness state of the node we are working with\n const isOpened = yield refresh\n ? {\n id,\n isLeaf: node.children.length === 0,\n isOpenByDefault: true,\n name: node.name,\n nestingLevel,\n }\n : id;\n\n if (node.children.length !== 0 && isOpened) {\n for (let i = node.children.length - 1; i >= 0; i--) {\n stack.push({\n nestingLevel: nestingLevel + 1,\n node: node.children[i],\n });\n }\n }\n }\n}\n```\n\nThe new `treeWalker` is only for the tree building. The `Tree` component builds and preserves the tree structure internally. See the full description [above](#treewalker-algorithm).\n\n```js\n// This function prepares an object for yielding. We can yield an object\n// that has `data` object with `id` and `isOpenByDefault` fields.\n// We can also add any other data here.\nconst getNodeData = (node, nestingLevel) => ({\n data: {\n id: node.id,\n isLeaf: node.children.length === 0,\n isOpenByDefault: true,\n name: node.name,\n nestingLevel,\n },\n nestingLevel,\n node,\n});\n\nfunction* treeWalker() {\n // Here we send root nodes to the component.\n for (const node of rootNodes) {\n yield getNodeData(node, 0);\n }\n\n while (true) {\n // Here we receive an object we created via getNodeData function\n // and yielded before. All we need here is to describe its children\n // in the same way we described the root nodes.\n const parentMeta = yield;\n\n for (const child of parentMeta.node.children) {\n yield getNodeData(child, parentMeta.nestingLevel + 1);\n }\n }\n}\n```\n\n\nTypeScript\n\n```ts\nconst getNodeData = (\n node: TreeNode,\n nestingLevel: number,\n): TreeWalkerValue => ({\n data: {\n id: node.id,\n isLeaf: node.children.length === 0,\n isOpenByDefault: true,\n name: node.name,\n nestingLevel,\n },\n nestingLevel,\n node,\n});\n\nfunction* treeWalker(): ReturnType> {\n for (const node of rootNodes) {\n yield getNodeData(node, 0);\n }\n\n while (true) {\n const parentMeta = yield;\n\n for (const child of parentMeta.node.children) {\n yield getNodeData(child, parentMeta.nestingLevel + 1);\n }\n }\n}\n```\n\n\n\n### 2. Migrate tree components\n\nComponents haven't been changed a lot but you may want to add new features like:\n\n- [`async`](#async-boolean)\n- [`placeholder`](#placeholder-reactnode--null)\n- [`buildingTaskTimeout`](#buildingtasktimeout-number).\n\n### 3. Migrate `recomputeTree` method\n\nThe `recomputeTree` method now receives a list of nodes to change (previously, it was an `opennessState` object). See the full description [above](#async-recomputetreestate-void).\n\nThe most important change is the introduction of the `subtreeCallback`. It is a function that will be applied to each node in the subtree of the specified node. Among other useful things it also allows imitating the behavior of old `useDefaultOpenness` and `useDefaultHeight` options.\n\nOld `recomputeTree`:\n\n```js\ntreeInstance.recomputeTree({\n opennessState: {\n 'node-1': true,\n 'node-2': true,\n 'node-3': false,\n },\n refreshNodes: true,\n useDefaultOpenness: false,\n});\n```\n\nNew `recomputeTree`:\n\n```js\ntreeInstance.recomputeTree({\n 'node-1': true,\n 'node-2': {\n open: true,\n subtreeCallback(node, ownerNode) {\n if (node !== ownerNode) {\n node.isOpen = false;\n }\n },\n },\n 'node-3': false,\n});\n```\n\n### 4. Migrate all your `toggle()` calls to `setOpen(boolean)`\n\nIn the `3.x.x` version node provides a `setOpen` function instead of `toggle` that allows more fine-grained control over the openness state.\n\nOld `toggle`:\n\n```javascript\nconst Node = ({ data: { isLeaf, name }, isOpen, style, toggle }) => (\n
\n {/* Imitating the old `toggle` function behavior */}\n \n
\n )}\n
{name}
\n
\n);\n```\n\n\nTypeScript\n\n```tsx\nimport { type CSSProperties, type FC } from 'react';\nimport { type FixedSizeNodePublicState } from 'react-vtree';\n\ntype NodeProps = FixedSizeNodePublicState & {\n style: CSSProperties;\n};\n\nconst Node: FC = ({\n data: { isLeaf, name },\n isOpen,\n style,\n setOpen,\n}) => (\n
\n {!isLeaf && (\n
\n \n
\n )}\n
{name}
\n
\n);\n```\n\n\n\n### 5. Migrate all your IDs to string\n\nUsing node IDs as keys should improve React rendering performance. However, it means that you won't be able to use `Symbol` as IDs anymore. You should move all your IDs to be strings instead of symbols.","readmeFilename":"README.md"}